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