git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_controls.3

   1 .TH LDAP_CONTROLS 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2016 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_control_create, ldap_control_find, ldap_control_dup,
   7 ldap_controls_dup, ldap_control_free, ldap_controls_free
   8 \- LDAP control manipulation routines
   9 .SH LIBRARY
  10 OpenLDAP LDAP (libldap, \-lldap)
  11 .SH SYNOPSIS
  12 .B #include <ldap.h>
  13 .LP
  14 .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");"
  15 .LP
  16 .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");"
  17 .LP
  18 .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");"
  19 .LP
  20 .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");"
  21 .LP
  22 .BI "void ldap_control_free(LDAPControl *" ctrl ");"
  23 .LP
  24 .BI "void ldap_controls_free(LDAPControl **" ctrls ");"
  25 .SH DESCRIPTION
  26 These routines are used to manipulate structures used for LDAP controls.
  27
  28 .BR ldap_control_create ()
  29 creates a control with the specified
  30 .I OID
  31 using the contents of the
  32 .I value
  33 parameter for the control value, if any.  The content of
  34 .I value
  35 is duplicated if
  36 .I dupval
  37 is non-zero.  The
  38 .I iscritical
  39 parameter must be non-zero for a critical control. The created control
  40 is returned in the
  41 .I ctrlp
  42 parameter.  The routine returns
  43 .B LDAP_SUCCESS
  44 on success or some other error code on failure.
  45 The content of
  46 .IR value ,
  47 for supported control types, can be prepared using helpers provided
  48 by this implementation of libldap, usually in the form
  49 .BR "ldap_create_<control name>_control_value" ().
  50 Otherwise, it can be BER-encoded using the functionalities of liblber.
  51
  52 .BR ldap_control_find ()
  53 searches the NULL-terminated
  54 .I ctrls
  55 array for a control whose OID matches the
  56 .I oid
  57 parameter.  The routine returns a pointer to the control if found,
  58 NULL otherwise.
  59 If the parameter
  60 .I nextctrlp
  61 is not NULL, on return it will point to the next control
  62 in the array, and can be passed to the
  63 .BR ldap_control_find ()
  64 routine for subsequent calls, to find further occurrences of the same
  65 control type.
  66 The use of this function is discouraged; the recommended way of handling
  67 controls in responses consists in going through the array of controls,
  68 dealing with each of them in the returned order, since it could matter.
  69
  70 .BR ldap_control_dup ()
  71 duplicates an individual control structure, and
  72 .BR ldap_controls_dup ()
  73 duplicates a NULL-terminated array of controls.
  74
  75 .BR ldap_control_free ()
  76 frees an individual control structure, and
  77 .BR ldap_controls_free ()
  78 frees a NULL-terminated array of controls.
  79
  80 .SH SEE ALSO
  81 .BR ldap (3),
  82 .BR ldap_error (3)
  83 .SH ACKNOWLEDGEMENTS
  84 .so ../Project