Controls

   LDAPv3 operations can be extended through the use of controls.
   Controls may be sent to a server or returned to the client
   with any LDAP message. These controls are referred to as server
   controls.

   The LDAP API also supports a client-side extension mechanism
   through the use of client controls. These controls affect the
   behavior of the LDAP API only and are never sent to a server.
   A common data structure is used to represent both types of
   controls:

           typedef struct ldapcontrol {
                   char                            *ldctl_oid;
                   struct berval                   ldctl_value;
                   char                            ldctl_iscritical;
           } LDAPControl, *PLDAPControl;

   The fields in the ldapcontrol structure have the following
   meanings:

   ldctl_oid      The control type, represented as a string.
   ldctl_value    The data associated with the control (if any).
                  To specify a zero-length value, set ldctl_
                  value.bv_len to zero and ldctl_value.bv_val to
                  a zero-length string. To indicate that no data is
                  associated with the control, set ldctl_value.bv_
                  val to NULL.
   ldctl_         Indicates whether the control is critical or not.
   iscritical     If this field is non-zero, the operation will only
                  be carried out if the control is recognized by the
                  server and/or client.

   Some LDAP API calls allocate an ldapcontrol structure or a
   NULL-terminated array of ldapcontrol structures. The following
   functions can be used to dispose of a single control or an array
   of controls:

        void ldap_control_free( LDAPControl *ctrl );

        void ldap_controls_free( LDAPControl **ctrls );

   A set of controls that affect the entire session can be set using
   the ldap_set_option() function. A list of controls can also be
   passed directly to some LDAP API calls, such as ldap_search_
   ext(), in which case any controls set for the session through
   the use of ldap_set_option() are ignored. Control lists are
   represented as a NULL-terminated array of pointers to ldapcontrol
   structures.

   Server controls are defined by LDAPv3 protocol extension
   documents; for example, a control has been proposed to support
   paging of search results. No client controls are currently
   implemented in this version of the API.