D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
proc
/
self
/
root
/
home
/
vblioqus
/
karachi777.vip
/
images
/
494334
/
65412
/
Filename :
man3.tar
back
Copy
ld_errno.3 0000644 00000015044 15152554700 0006444 0 ustar 00 .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin ber_bvfree.3 0000644 00000014606 15152554700 0006744 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_modify_s.3 0000644 00000010711 15152554700 0007445 0 ustar 00 .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary. For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the attribute if no values remain. If the entire attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_control_create.3 0000644 00000005675 15152554700 0010654 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ldap_memfree.3 0000644 00000003060 15152554700 0007253 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ldap_memcalloc.3 0000644 00000003060 15152554700 0007567 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ldap_explode_dn.3 0000644 00000015161 15152554700 0007761 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ber_bvecadd.3 0000644 00000014606 15152554701 0007064 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_add.3 0000644 00000005232 15152554701 0006367 0 ustar 00 .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ldap_dn2dcedn.3 0000644 00000015161 15152554701 0007322 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_memrealloc.3 0000644 00000003060 15152554701 0007754 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ber_get_stringa.3 0000644 00000030566 15152554701 0010005 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_init_fd.3 0000644 00000013727 15152554701 0007263 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin ber_get_next.3 0000644 00000030566 15152554701 0007314 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_abandon_ext.3 0000644 00000004455 15152554701 0010127 0 ustar 00 .lf 1 stdin .TH LDAP_ABANDON 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_abandon_ext \- Abandon an LDAP operation in progress .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .ft B int ldap_abandon_ext( .RS .ft B LDAP *\fIld\fB, Bint \fImsgid\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_abandon_ext() routine is used to send a LDAP Abandon request for an operation in progress. The \fImsgid\fP passed should be the message id of an outstanding LDAP operation, such as returned by .BR ldap_search_ext (3). .LP .BR ldap_abandon_ext () checks to see if the result of the operation has already come in. If it has, it deletes it from the queue of pending messages. If not, it sends an LDAP abandon request to the LDAP server. .LP The caller can expect that the result of an abandoned operation will not be returned from a future call to .BR ldap_result (3). .LP .B ldap_abandon_ext() allows server and client controls to be passed in via the .I sctrls and .I cctrls parameters, respectively. .LP .B ldap_abandon_ext() returns a code indicating success or, in the case of failure, the nature of the failure. See .BR ldap_error (3) for details. .SH DEPRECATED INTERFACES The .B ldap_abandon() routine is deprecated in favor of the .B ldap_abandon_ext() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 61 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_result (3), .BR ldap_search_ext (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 69 stdin ldap_unbind_s.3 0000644 00000027376 15152554701 0007455 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_start_tls.3 0000644 00000003237 15152554701 0007661 0 ustar 00 .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin ldap_str2dn.3 0000644 00000015161 15152554702 0007056 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_str2objectclass.3 0000644 00000021442 15152554702 0010750 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ber_peek_tag.3 0000644 00000030566 15152554702 0007257 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ber_get_boolean.3 0000644 00000030566 15152554702 0007756 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_get_values.3 0000644 00000005350 15152554702 0007777 0 ustar 00 .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin ldap_modrdn2_s.3 0000644 00000004420 15152554702 0007525 0 ustar 00 .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ldap_delete_ext_s.3 0000644 00000004767 15152554702 0010320 0 ustar 00 .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin ldap_initialize.3 0000644 00000013727 15152554702 0010011 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin ldap_parse_sasl_bind_result.3 0000644 00000007704 15152554702 0012374 0 ustar 00 .lf 1 stdin .TH LDAP_PARSE_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_result \- Parsing results .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_result( LDAP *ld, LDAPMessage *result, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .LP .ft B int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, struct berval **servercredp, int freeit ) .LP .ft B int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, char **retoidp, struct berval **retdatap, int freeit ) .SH DESCRIPTION .LP These routines are used to extract information from a result message. They will operate on the first result message in a chain of search results (skipping past other message types). They take the \fIresult\fP as returned by a call to .BR ldap_result (3), .BR ldap_search_s (3) or .BR ldap_search_st (3). In addition to .BR ldap_parse_result() , the routines .B ldap_parse_sasl_bind_result() and .B ldap_parse_extended_result() are used to get all the result information from SASL bind and extended operations. .LP The \fIerrcodep\fP parameter will be filled in with the result code from the result message. .LP The server might supply a matched DN string in the message indicating how much of a name in a request was recognized. The \fImatcheddnp\fP parameter will be filled in with this string if supplied, else it will be NULL. If a string is returned, it should be freed using .BR ldap_memfree (3). .LP The \fIerrmsgp\fP parameter will be filled in with the error message field from the parsed message. This string should be freed using .BR ldap_memfree (3). .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of referral strings from the parsed message. This array should be freed using .BR ldap_memvfree (3). If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed using .BR ldap_controls_free (3). If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .LP For SASL bind results, the \fIservercredp\fP parameter will be filled in with an allocated berval structure containing the credentials from the server if present. The structure should be freed using .BR ber_bvfree (3). .LP For extended results, the \fIretoidp\fP parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. The string should be freed using .BR ldap_memfree (3). If no OID was returned, \fI*retoidp\fP is set to NULL. .LP For extended results, the \fIretdatap\fP parameter will be filled in with a pointer to a berval structure containing the data from the extended operation response. The structure should be freed using .BR ber_bvfree (3). If no data were returned, \fI*retdatap\fP is set to NULL. .LP For all the above result parameters, NULL values can be used in calls in order to ignore certain fields. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the result parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_memfree (3), .BR ldap_memvfree (3), .BR ldap_get_values (3), .BR ldap_controls_free (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 108 stdin ldap_compare_ext.3 0000644 00000005343 15152554702 0010151 0 ustar 00 .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin ldap_next_attribute.3 0000644 00000004466 15152554702 0010711 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_ATTRIBUTE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **berptr ) .LP .ft B char *ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ber ) .SH DESCRIPTION The .B ldap_first_attribute() and .B ldap_next_attribute() routines are used to step through the attributes in an LDAP entry. .B ldap_first_attribute() takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a pointer to character string containing the first attribute description in the entry. .B ldap_next_attribute() returns the next attribute description in the entry. .LP It also returns, in \fIberptr\fP, a pointer to a BerElement it has allocated to keep track of its current position. This pointer should be passed to subsequent calls to .B ldap_next_attribute() and is used to effectively step through the entry's attributes. The caller is solely responsible for freeing the BerElement pointed to by \fIberptr\fP when it is no longer needed by calling .BR ber_free (3). When calling .BR ber_free (3) in this instance, be sure the second argument is 0. .LP The attribute names returned are suitable for inclusion in a call to .BR ldap_get_values (3) to retrieve the attribute's values. .SH ERRORS If an error occurs, NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES The .B ldap_first_attribute() and .B ldap_next_attribute() return dynamically allocated memory that must be freed by the caller via .BR ldap_memfree (3). .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_get_values (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 74 stdin ldap_free_urldesc.3 0000644 00000006031 15152554702 0010300 0 ustar 00 .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin ber_put_int.3 0000644 00000022113 15152554702 0007147 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_sort_entries.3 0000644 00000002350 15152554702 0010356 0 ustar 00 .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin ldap_count_entries.3 0000644 00000004552 15152554703 0010526 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_ENTRY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_entries( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) .SH DESCRIPTION .LP These routines are used to parse results received from .BR ldap_result (3) or the synchronous LDAP search operation routines .BR ldap_search_s (3) and .BR ldap_search_st (3). .LP The .B ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) or .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first entry in the result. .LP This pointer should be supplied on a subsequent call to .B ldap_next_entry() to get the next entry, the result of which should be supplied to the next call to .BR ldap_next_entry() , etc. .B ldap_next_entry() will return NULL when there are no more entries. The entries returned from these calls are used in calls to the routines described in .BR ldap_get_dn (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), etc. .LP A count of the number of entries in the search result can be obtained by calling .BR ldap_count_entries() . .SH ERRORS If an error occurs in .B ldap_first_entry() or .BR ldap_next_entry() , NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. If an error occurs in .BR ldap_count_entries() , -1 is returned, and .B ld_errno is set appropriately. See .BR ldap_error (3) for a description of possible error codes. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), .BR ldap_get_dn (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 81 stdin ldap_dup.3 0000644 00000007056 15152554703 0006437 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_dup( .RS .ft B LDAP *\fIold\fB ); .RE .LP .ft B int ldap_destroy( .RS .ft B LDAP *\fIold\fB ); .RE .SH DESCRIPTION .LP .B ldap_dup() duplicates an existing LDAP .RB ( "LDAP *" ) session handle. The new session handle may be used concurrently with the original session handle. In a threaded environment, different threads may execute concurrent requests on the same connection/session without fear of contamination. Each session handle manages its own private error results. .LP .B ldap_destroy() destroys an existing session handle. .LP The .B ldap_dup() and .B ldap_destroy() functions are used in conjunction with a "thread safe" version of .B libldap .RB ( libldap_r ) to enable operation thread safe API calls, so that a single session may be simultaneously used across multiple threads with consistent error handling. .LP When a session is created through the use of one of the session creation functions including .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3) or .BR ldap_init_fd (3) an .B "LDAP *" session handle is returned to the application. The session handle may be shared amongst threads, however the error codes are unique to a session handle. Multiple threads performing different operations using the same session handle will result in inconsistent error codes and return values. .LP To prevent this confusion, .B ldap_dup() is used duplicate an existing session handle so that multiple threads can share the session, and maintain consistent error information and results. .LP The message queues for a session are shared between sibling session handles. Results of operations on a sibling session handles are accessible to all the sibling session handles. Applications desiring results associated with a specific operation should provide the appropriate msgid to .BR ldap_result() . Applications should avoid calling .B ldap_result() with .B LDAP_RES_ANY as that may "steal" and return results in the calling thread that another operation in a different thread, using a different session handle, may require to complete. .LP When .B ldap_unbind() is called on a session handle with siblings, all the siblings become invalid. .LP Siblings must be destroyed using .BR ldap_destroy() . Session handle resources associated with the original .RB ( "LDAP *" ) will be freed when the last session handle is destroyed or when .B ldap_unbind() is called, if no other session handles currently exist. .SH ERRORS If an error occurs, .B ldap_dup() will return NULL and .I errno should be set appropriately. .B ldap_destroy() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .SH SEE ALSO .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3), .BR ldap_init_fd (3), .BR errno (3) .SH ACKNOWLEDGEMENTS This work is based on the previously proposed .B LDAP C API Concurrency Extensions draft .BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) effort. .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 127 stdin lber-memory.3 0000644 00000003034 15152554703 0007071 0 ustar 00 .lf 1 stdin .TH LBER_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_memalloc, ber_memcalloc, ber_memrealloc, ber_memfree, ber_memvfree \- OpenLDAP LBER memory allocators .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "void *ber_memalloc(ber_len_t " bytes ");" .LP .BI "void *ber_memcalloc(ber_len_t " nelems ", ber_len_t " bytes ");" .LP .BI "void *ber_memrealloc(void *" ptr ", ber_len_t " bytes ");" .LP .BI "void ber_memfree(void *" ptr ");" .LP .BI "void ber_memvfree(void **" vec ");" .SH DESCRIPTION .LP These routines are used to allocate/deallocate memory used/returned by the Lightweight BER library as required by .BR lber-encode (3) and .BR lber-decode (3). .BR ber_memalloc (), .BR ber_memcalloc (), .BR ber_memrealloc (), and .BR ber_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ber_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. .SH SEE ALSO .BR lber-decode (3), .BR lber-encode (3), .BR lber-types (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 50 stdin ldap_controls_dup.3 0000644 00000005675 15152554703 0010367 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ldap_unbind_ext_s.3 0000644 00000027376 15152554703 0010337 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_simple_bind_s.3 0000644 00000027376 15152554703 0010465 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_url_parse.3 0000644 00000006031 15152554703 0007633 0 ustar 00 .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin ldap_parse_reference.3 0000644 00000004457 15152554703 0011001 0 ustar 00 .lf 1 stdin .TH LDAP_PARSE_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_reference \- Extract referrals and controls from a reference message .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_reference( LDAP *ld, LDAPMessage *reference, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .SH DESCRIPTION .LP The .B ldap_parse_reference() routine is used to extract referrals and controls from a reference message. The \fIreference\fP parameter is a reference message as returned by a call to .BR ldap_first_reference (3) , .BR ldap_next_reference (3) , .BR ldap_first_message (3) , .BR ldap_next_message (3) , or .BR ldap_result (3) . .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of character strings. The strings are copies of the referrals contained in the parsed message. The array should be freed by calling .BR ldap_value_free (3) . If \fIreferralsp\fP is NULL, no referrals are returned. If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed by calling .BR ldap_controls_free (3). If \fIserverctrlsp\fP is NULL, no controls are returned. If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the \fIreferralsp\fP and \fIserverctrlsp\fP parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_first_reference (3), .BR ldap_first_message (3), .BR ldap_result (3), .BR ldap_get_values (3), .BR ldap_controls_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 62 stdin ber_dupbv.3 0000644 00000014606 15152554703 0006616 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ber_put_enum.3 0000644 00000022113 15152554703 0007322 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_sort_values.3 0000644 00000002350 15152554703 0010205 0 ustar 00 .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin ldap_dnfree.3 0000644 00000015161 15152554703 0007106 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_next_entry.3 0000644 00000004552 15152554703 0010044 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_ENTRY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_entries( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) .SH DESCRIPTION .LP These routines are used to parse results received from .BR ldap_result (3) or the synchronous LDAP search operation routines .BR ldap_search_s (3) and .BR ldap_search_st (3). .LP The .B ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) or .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first entry in the result. .LP This pointer should be supplied on a subsequent call to .B ldap_next_entry() to get the next entry, the result of which should be supplied to the next call to .BR ldap_next_entry() , etc. .B ldap_next_entry() will return NULL when there are no more entries. The entries returned from these calls are used in calls to the routines described in .BR ldap_get_dn (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), etc. .LP A count of the number of entries in the search result can be obtained by calling .BR ldap_count_entries() . .SH ERRORS If an error occurs in .B ldap_first_entry() or .BR ldap_next_entry() , NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. If an error occurs in .BR ldap_count_entries() , -1 is returned, and .B ld_errno is set appropriately. See .BR ldap_error (3) for a description of possible error codes. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), .BR ldap_get_dn (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 81 stdin ldap_syntax2str.3 0000644 00000021442 15152554703 0010003 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_count_values_len.3 0000644 00000005350 15152554703 0011207 0 ustar 00 .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin ldap_modrdn.3 0000644 00000004420 15152554703 0007122 0 ustar 00 .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ldap_syntax2name.3 0000644 00000021442 15152554703 0010113 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ber_put_string.3 0000644 00000022113 15152554703 0007664 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ber_bvarray_add.3 0000644 00000014606 15152554704 0007755 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_tls.3 0000644 00000003237 15152554704 0006447 0 ustar 00 .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin ldap.3 0000644 00000021522 15152554704 0005562 0 ustar 00 .lf 1 stdin .TH LDAP 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap \- OpenLDAP Lightweight Directory Access Protocol API .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .ft .fi .SH DESCRIPTION .LP The Lightweight Directory Access Protocol (LDAP) (RFC 4510) provides access to X.500 directory services. These services may be stand\-alone or part of a distributed directory service. This client API supports LDAP over TCP (RFC 4511), LDAP over TLS/SSL, and LDAP over IPC (UNIX domain sockets). This API supports SASL (RFC 4513) and Start TLS (RFC 4513) as well as a number of protocol extensions. This API is loosely based upon IETF/LDAPEXT C LDAP API draft specification, a (orphaned) work in progress. .LP The OpenLDAP Software package includes a stand\-alone server in .BR slapd (8), various LDAP clients, and an LDAP client library used to provide programmatic access to the LDAP protocol. This man page gives an overview of the LDAP library routines. .LP Both synchronous and asynchronous APIs are provided. Also included are various routines to parse the results returned from these routines. These routines are found in the \-lldap library. .LP The basic interaction is as follows. A session handle is created using .BR ldap_initialize (3) and set the protocol version to 3 by calling .BR ldap_set_option (3). The underlying session is established first operation is issued. This would generally be a Start TLS or Bind operation, or a Search operation to read attributes of the Root DSE. A Start TLS operation is performed by calling .BR ldap_start_tls_s (3). A LDAP bind operation is performed by calling .BR ldap_sasl_bind (3) or one of its friends. A Search operation is performed by calling ldap_search_ext_s(3) or one of its friends. Subsequently, additional operations are performed by calling one of the synchronous or asynchronous routines (e.g., .BR ldap_compare_ext_s (3) or .BR ldap_compare_ext (3) followed by .BR ldap_result (3)). Results returned from these routines are interpreted by calling the LDAP parsing routines such as .BR ldap_parse_result (3). The LDAP association and underlying connection is terminated by calling .BR ldap_unbind_ext (3). Errors can be interpreted by calling .BR ldap_err2string (3). .SH LDAP versions This library supports version 3 of the Lightweight Directory Access Protocol (LDAPv3) as defined in RFC 4510. It also supports a variant of version 2 of LDAP as defined by U-Mich LDAP and, to some degree, RFC 1777. Version 2 (all variants) are considered obsolete. Version 3 should be used instead. .LP For backwards compatibility reasons, the library defaults to version 2. Hence, all new applications (and all actively maintained applications) should use .BR ldap_set_option (3) to select version 3. The library manual pages assume version 3 has been selected. .SH INPUT and OUTPUT PARAMETERS All character string input/output is expected to be/is UTF-8 encoded Unicode (version 3.2). .LP Distinguished names (DN) (and relative distinguished names (RDN) to be passed to the LDAP routines should conform to RFC 4514 UTF-8 string representation. .LP Search filters to be passed to the search routines are to be constructed by hand and should conform to RFC 4515 UTF-8 string representation. .LP LDAP URLs to be passed to routines are expected to conform to RFC 4516 format. The .BR ldap_url (3) routines can be used to work with LDAP URLs. .LP LDAP controls to be passed to routines can be manipulated using the .BR ldap_controls (3) routines. .SH DISPLAYING RESULTS Results obtained from the search routines can be output by hand, by calling .BR ldap_first_entry (3) and .BR ldap_next_entry (3) to step through the entries returned, .BR ldap_first_attribute (3) and .BR ldap_next_attribute (3) to step through an entry's attributes, and .BR ldap_get_values (3) to retrieve a given attribute's values. Attribute values may or may not be displayable. .SH UTILITY ROUTINES Also provided are various utility routines. The .BR ldap_sort (3) routines are used to sort the entries and values returned via the ldap search routines. .SH DEPRECATED INTERFACES A number of interfaces are now considered deprecated. For instance, ldap_add(3) is deprecated in favor of ldap_add_ext(3). .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 123 stdin .SH BER LIBRARY Also included in the distribution is a set of lightweight Basic Encoding Rules routines. These routines are used by the LDAP library routines to encode and decode LDAP protocol elements using the (slightly simplified) Basic Encoding Rules defined by LDAP. They are not normally used directly by an LDAP application program except in the handling of controls and extended operations. The routines provide a printf and scanf\-like interface, as well as lower\-level access. These routines are discussed in .BR lber\-decode (3), .BR lber\-encode (3), .BR lber\-memory (3), and .BR lber\-types (3). .SH INDEX .TP 20 .SM ldap_initialize(3) initialize the LDAP library without opening a connection to a server .TP .SM ldap_result(3) wait for the result from an asynchronous operation .TP .SM ldap_abandon_ext(3) abandon (abort) an asynchronous operation .TP .SM ldap_add_ext(3) asynchronously add an entry .TP .SM ldap_add_ext_s(3) synchronously add an entry .TP .SM ldap_sasl_bind(3) asynchronously bind to the directory .TP .SM ldap_sasl_bind_s(3) synchronously bind to the directory .TP .SM ldap_unbind_ext(3) synchronously unbind from the LDAP server and close the connection .TP .SM ldap_unbind(3) and ldap_unbind_s(3) are equivalent to .BR ldap_unbind_ext (3) .TP .SM ldap_memfree(3) dispose of memory allocated by LDAP routines. .TP .SM ldap_compare_ext(3) asynchronously compare to a directory entry .TP .SM ldap_compare_ext_s(3) synchronously compare to a directory entry .TP .SM ldap_delete_ext(3) asynchronously delete an entry .TP .SM ldap_delete_ext_s(3) synchronously delete an entry .TP .SM ld_errno(3) LDAP error indication .TP .SM ldap_errlist(3) list of LDAP errors and their meanings .TP .SM ldap_err2string(3) convert LDAP error indication to a string .TP .SM ldap_extended_operation(3) asynchronously perform an arbitrary extended operation .TP .SM ldap_extended_operation_s(3) synchronously perform an arbitrary extended operation .TP .SM ldap_first_attribute(3) return first attribute name in an entry .TP .SM ldap_next_attribute(3) return next attribute name in an entry .TP .SM ldap_first_entry(3) return first entry in a chain of search results .TP .SM ldap_next_entry(3) return next entry in a chain of search results .TP .SM ldap_count_entries(3) return number of entries in a search result .TP .SM ldap_get_dn(3) extract the DN from an entry .TP .SM ldap_get_values_len(3) return an attribute's values with lengths .TP .SM ldap_value_free_len(3) free memory allocated by ldap_get_values_len(3) .TP .SM ldap_count_values_len(3) return number of values .TP .SM ldap_modify_ext(3) asynchronously modify an entry .TP .SM ldap_modify_ext_s(3) synchronously modify an entry .TP .SM ldap_mods_free(3) free array of pointers to mod structures used by ldap_modify_ext(3) .TP .SM ldap_rename(3) asynchronously rename an entry .TP .SM ldap_rename_s(3) synchronously rename an entry .TP .SM ldap_msgfree(3) free results allocated by ldap_result(3) .TP .SM ldap_msgtype(3) return the message type of a message from ldap_result(3) .TP .SM ldap_msgid(3) return the message id of a message from ldap_result(3) .TP .SM ldap_search_ext(3) asynchronously search the directory .TP .SM ldap_search_ext_s(3) synchronously search the directory .TP .SM ldap_is_ldap_url(3) check a URL string to see if it is an LDAP URL .TP .SM ldap_url_parse(3) break up an LDAP URL string into its components .TP .SM ldap_sort_entries(3) sort a list of search results .TP .SM ldap_sort_values(3) sort a list of attribute values .TP .SM ldap_sort_strcasecmp(3) case insensitive string comparison .SH SEE ALSO .BR ldap.conf (5), .BR slapd (8), .BR draft-ietf-ldapext-ldap-c-api-xx.txt \ <http://www.ietf.org> .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 274 stdin .LP These API manual pages are loosely based upon descriptions provided in the IETF/LDAPEXT C LDAP API Internet Draft, a (orphaned) work in progress. ldap_rename_s.3 0000644 00000005211 15152554704 0007430 0 ustar 00 .lf 1 stdin .TH LDAP_RENAME 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_rename, ldap_rename_s \- Renames the specified entry. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_rename( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[], msgidp ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; int *msgidp); .LP .ft B int ldap_rename_s( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[] ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; .SH DESCRIPTION These routines are used to perform a LDAP rename operation. The function changes the leaf component of an entry's distinguished name and optionally moves the entry to a new parent container. The .B ldap_rename_s performs a rename operation synchronously. The method takes \fIdn\fP, which points to the distinguished name of the entry whose attribute is being compared, \fInewparent\fP,the distinguished name of the entry's new parent. If this parameter is NULL, only the RDN is changed. The root DN is specified by passing a zero length string, "". \fIdeleteoldrdn\fP specifies whether the old RDN should be retained or deleted. Zero indicates that the old RDN should be retained. If you choose this option, the attribute will contain both names (the old and the new). Non-zero indicates that the old RDN should be deleted. \fIserverctrls\fP points to an array of LDAPControl structures that list the client controls to use with this extended operation. Use NULL to specify no client controls. \fIclientctrls\fP points to an array of LDAPControl structures that list the client controls to use with the search. .LP .B ldap_rename works just like .B ldap_rename_s, but the operation is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result(3). .SH ERRORS .B ldap_rename() returns \-1 in case of error initiating the request, and will set the \fIld_errno\fP field in the \fIld\fP parameter to indicate the error. .BR ldap_rename_s() returns the LDAP error code resulting from the rename operation. .SH SEE ALSO .BR ldap (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 67 stdin ldap_objectclass2str.3 0000644 00000021442 15152554704 0010752 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_attributetype2name.3 0000644 00000021442 15152554704 0011473 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_unbind_ext.3 0000644 00000027376 15152554704 0010016 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_count_values.3 0000644 00000005350 15152554704 0010352 0 ustar 00 .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin ber_flush.3 0000644 00000022113 15152554704 0006610 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_memory.3 0000644 00000003060 15152554704 0007147 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ldap_first_entry.3 0000644 00000004552 15152554704 0010216 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_ENTRY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_entries( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) .SH DESCRIPTION .LP These routines are used to parse results received from .BR ldap_result (3) or the synchronous LDAP search operation routines .BR ldap_search_s (3) and .BR ldap_search_st (3). .LP The .B ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) or .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first entry in the result. .LP This pointer should be supplied on a subsequent call to .B ldap_next_entry() to get the next entry, the result of which should be supplied to the next call to .BR ldap_next_entry() , etc. .B ldap_next_entry() will return NULL when there are no more entries. The entries returned from these calls are used in calls to the routines described in .BR ldap_get_dn (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), etc. .LP A count of the number of entries in the search result can be obtained by calling .BR ldap_count_entries() . .SH ERRORS If an error occurs in .B ldap_first_entry() or .BR ldap_next_entry() , NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. If an error occurs in .BR ldap_count_entries() , -1 is returned, and .B ld_errno is set appropriately. See .BR ldap_error (3) for a description of possible error codes. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), .BR ldap_get_dn (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 81 stdin ldap_parse_vlv_control.3 0000644 00000004452 15152554704 0011406 0 ustar 00 .lf 1 stdin .TH LDAP_PARSE_VLV_CONTROL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_vlv_control \- Decode the information returned from a search operation that used a VLV (virtual list view) control .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_vlv_control( ld, ctrlp, target_posp, list_countp, contextp, errcodep ) .ft LDAP *ld; LDAPControl **ctrlp; unsigned long *target_posp, *list_countp; struct berval **contextp; int *errcodep; .SH DESCRIPTION The .B ldap_parse_vlv_control is used to decode the information returned from a search operation that used a VLV (virtual list view)control. It takes a null terminated array of LDAPControl structures, usually obtained by a call to the .BR ldap_parse_result function, a \fItarget_pos\fP which points to the list index of the target entry. If this parameter is NULL, the target position is not returned. The index returned is an approximation of the position of the target entry. It is not guaranteed to be exact. The parameter \fIlist_countp\fP points to the server's estimate of the size of the list. If this parameter is NULL, the size is not returned. \fIcontextp\fP is a pointer to the address of a berval structure that contains a server-generated context identifier if server returns one. If server does not return a context identifier, the server returns a NULL in this parameter. If this parameter is set to NULL, the context identifier is not returned. You should use this returned context in the next call to create a VLV control. When the berval structure is no longer needed, you should free the memory by calling the \fIber_bvfree function.e\fP \fIerrcodep\fP is an output parameter, which points to the result code returned by the server. If this parameter is NULL, the result code is not returned. .LP See ldap.h for a list of possible return codes. .SH SEE ALSO .BR ldap_search (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 50 stdin ldap_compare_s.3 0000644 00000005343 15152554704 0007615 0 ustar 00 .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin ldap_search_st.3 0000644 00000012165 15152554704 0007620 0 ustar 00 .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin ldap_add_ext_s.3 0000644 00000005232 15152554704 0007574 0 ustar 00 .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ldap_get_option.3 0000644 00000046074 15152554704 0010022 0 ustar 00 .lf 1 stdin .TH LDAP_GET_OPTION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_option, ldap_set_option \- LDAP option handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");" .LP .BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");" .SH DESCRIPTION .LP These routines provide access to options stored either in a LDAP handle or as global options, where applicable. They make use of a neutral interface, where the type of the value either retrieved by .BR ldap_get_option (3) or set by .BR ldap_set_option (3) is cast to .BR "void *" . The actual type is determined based on the value of the .B option argument. Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles inherit their default settings from the global options in effect at the time the handle is created. .TP .B LDAP_OPT_API_FEATURE_INFO Fills-in a .BR "LDAPAPIFeatureInfo" ; .BR outvalue must be a .BR "LDAPAPIFeatureInfo *" , pointing to an already allocated struct. The .B ldapaif_info_version field of the struct must be initialized to .B LDAP_FEATURE_INFO_VERSION before making the call. The .B ldapaif_name field must be set to the name of a feature to query. This is a read-only option. .TP .B LDAP_OPT_API_INFO Fills-in a .BR "LDAPAPIInfo" ; .BR outvalue must be a .BR "LDAPAPIInfo *" , pointing to an already allocated struct. The .B ldapai_info_version field of the struct must be initialized to .B LDAP_API_INFO_VERSION before making the call. If the version passed in does not match the current library version, the expected version number will be stored in the struct and the call will fail. The caller is responsible for freeing the elements of the .B ldapai_extensions array and the array itself using .BR ldap_memfree (3). The caller must also free the .BR ldapi_vendor_name . This is a read-only option. .TP .B LDAP_OPT_CLIENT_CONTROLS Sets/gets the client-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts client-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag. .BR invalue should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON ; .BR outvalue must be .BR "int *" . When set, the library will call .BR connect (2) and return, without waiting for response. This leaves the handle in a connecting state. Subsequent calls to library routines will poll for completion of the connect before performing further operations. As a consequence, library calls that need to establish a connection with a DSA do not block even for the network timeout (option .BR LDAP_OPT_NETWORK_TIMEOUT ). This option is OpenLDAP specific. .TP .B LDAP_OPT_CONNECT_CB This option allows to set a connect callback. .B invalue must be a .BR "const struct ldap_conncb *" . Callbacks are executed in last in-first served order. Handle-specific callbacks are executed first, followed by global ones. Right before freeing the callback structure, the .B lc_del callback handler is passed a .B NULL .BR Sockbuf . Calling .BR ldap_get_option (3) for this option removes the callback whose pointer matches .BR outvalue . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEBUG_LEVEL Sets/gets the debug level of the client library. .BR invalue must be a .BR "const int *" ; .BR outvalue must be a .BR "int *" . Valid debug levels are .BR LDAP_DEBUG_ANY , .BR LDAP_DEBUG_ARGS , .BR LDAP_DEBUG_BER , .BR LDAP_DEBUG_CONNS , .BR LDAP_DEBUG_NONE , .BR LDAP_DEBUG_PACKETS , .BR LDAP_DEBUG_PARSE , and .BR LDAP_DEBUG_TRACE . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEFBASE Sets/gets a string containing the DN to be used as default base for search operations. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_DEREF Sets/gets the value that defines when alias dereferencing must occur. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . They cannot be NULL. The value of .BR *invalue should be one of .BR LDAP_DEREF_NEVER (the default), .BR LDAP_DEREF_SEARCHING , .BR LDAP_DEREF_FINDING , or .BR LDAP_DEREF_ALWAYS . Note that this has ever been the only means to determine alias dereferencing within search operations. .TP .B LDAP_OPT_DESC Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. .TP .B LDAP_OPT_DIAGNOSTIC_MESSAGE Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as .BR LDAP_OPT_ERROR_STRING . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_HOST_NAME Sets/gets a space-separated list of hosts to be contacted by the library when trying to establish a connection. This is now deprecated in favor of .BR LDAP_OPT_URI . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_MATCHED_DN Sets/gets a string containing the matched DN associated to the LDAP handle. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after which .BR poll (2)/ select (2) following a .BR connect (2) returns in case of no activity. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "const struct timeval *" . They cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_PROTOCOL_VERSION Sets/gets the protocol version. .BR outvalue and .BR invalue must be .BR "int *" . .TP .B LDAP_OPT_REFERRAL_URLS Sets/gets an array containing the referral URIs associated to the LDAP handle. .BR outvalue must be a .BR "char ***" , and the caller is responsible of freeing the returned string by calling .BR ldap_memvfree (3), while .BR invalue must be a NULL-terminated .BR "char *const *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .\".TP .\".B LDAP_OPT_REFHOPLIMIT .\"This option is OpenLDAP specific. .\"It is not currently implemented. .TP .B LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME). .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This option was formerly known as .BR LDAP_OPT_ERROR_NUMBER . .BR invalue must be a .BR "const int *" . .BR outvalue must be a .BR "int *" . .TP .B LDAP_OPT_SERVER_CONTROLS Sets/gets the server-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts server-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_SESSION_REFCNT Returns the reference count associated with the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_SIZELIMIT Sets/gets the value that defines the maximum number of entries to be returned by a search operation. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" ; They cannot be NULL. .TP .B LDAP_OPT_SOCKBUF Returns a pointer to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "Sockbuf **" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_TIMELIMIT Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" , and they cannot be NULL. .TP .B LDAP_OPT_TIMEOUT Sets/gets a timeout value for the synchronous API calls. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "struct timeval *" , and they cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_URI Sets/gets a comma- or space-separated list of URIs to be contacted by the library when trying to establish a connection. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library parses the string into a list of .BR LDAPURLDesc structures, so the invocation of .BR ldap_set_option (3) may fail if URL parsing fails. URIs may only contain the .BR schema , the .BR host , and the .BR port fields. This option is OpenLDAP specific. .SH SASL OPTIONS The SASL options are OpenLDAP specific. .TP .B LDAP_OPT_X_SASL_AUTHCID Gets the SASL authentication identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_AUTHZID Gets the SASL authorization identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MAXBUFSIZE Gets/sets SASL maximum buffer size; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_MECH Gets the SASL mechanism; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MECHLIST Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; .BR outvalue must be .BR "char ***" . The caller must not free or otherwise muck with it. .TP .B LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonicalized. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_SASL_REALM Gets the SASL realm; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_SECPROPS Sets the SASL secprops; .BR invalue must be a .BR "char *" , containing a comma-separated list of properties. Legal values are: .BR none , .BR nodict , .BR noplain , .BR noactive , .BR passcred , .BR forwardsec , .BR noanonymous , .BR minssf=<minssf> , .BR maxssf=<maxssf> , .BR maxbufsize=<maxbufsize> . .TP .B LDAP_OPT_X_SASL_SSF Gets the SASL SSF; .BR outvalue must be a .BR "ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_EXTERNAL Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism; .BR invalue must be a .BR "const ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_MAX Gets/sets SASL maximum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_USERNAME Gets the SASL username; .BR outvalue must be a .BR "char **" . Its content needs to be freed by the caller using .BR ldap_memfree (3). .SH TCP OPTIONS The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable. .TP .B LDAP_OPT_X_KEEPALIVE_IDLE Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_PROBES Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_INTERVAL Sets/gets the interval in seconds between individual keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .SH TLS OPTIONS The TLS options are OpenLDAP specific. .\".TP .\".B LDAP_OPT_X_TLS .\"Sets/gets the TLS mode. .TP .B LDAP_OPT_X_TLS_CACERTDIR Sets/gets the path of the directory containing CA certificates. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CACERTFILE Sets/gets the full-path of the CA certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CERTFILE Sets/gets the full-path of the certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CIPHER_SUITE Sets/gets the allowed cipher suite. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CONNECT_ARG Sets/gets the connection callback argument. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . .TP .B LDAP_OPT_X_TLS_CONNECT_CB Sets/gets the connection callback handle. .BR invalue must be .BR "const LDAP_TLS_CONNECT_CB *" ; .BR outvalue must be .BR "LDAP_TLS_CONNECT_CB **" . .TP .B LDAP_OPT_X_TLS_CRLCHECK Sets/gets the CRL evaluation strategy, one of .BR LDAP_OPT_X_TLS_CRL_NONE , .BR LDAP_OPT_X_TLS_CRL_PEER , or .BR LDAP_OPT_X_TLS_CRL_ALL . .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . Requires OpenSSL. .TP .B LDAP_OPT_X_TLS_CRLFILE Sets/gets the full-path of the CRL file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). This option is only valid for GnuTLS. .TP .B LDAP_OPT_X_TLS_CTX Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL_CTX*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option or attempt to manipulate this structure. .TP .B LDAP_OPT_X_TLS_DHFILE Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS and Mozilla NSS. .TP .B LDAP_OPT_X_TLS_KEYFILE Sets/gets the full-path of the certificate key file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_NEWCTX Instructs the library to create a new TLS library context. .BR invalue must be .BR "const int *" . A non-zero value pointed to by .BR invalue tells the library to create a context for a server. .TP .B LDAP_OPT_X_TLS_PROTOCOL_MIN Sets/gets the minimum protocol version. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_TLS_RANDOM_FILE Sets/gets the random file when .B /dev/random and .B /dev/urandom are not available. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS. .TP .B LDAP_OPT_X_TLS_REQUIRE_CERT Sets/gets the peer certificate checking strategy, one of .BR LDAP_OPT_X_TLS_NEVER , .BR LDAP_OPT_X_TLS_HARD , .BR LDAP_OPT_X_TLS_DEMAND , .BR LDAP_OPT_X_TLS_ALLOW , .BR LDAP_OPT_X_TLS_TRY . .TP .B LDAP_OPT_X_TLS_SSL_CTX Gets the TLS session context associated with this handle. .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option. .SH ERRORS On success, the functions return .BR LDAP_OPT_SUCCESS , while they may return .B LDAP_OPT_ERROR to indicate a generic option handling error. Occasionally, more specific errors can be returned, like .B LDAP_NO_MEMORY to indicate a failure in memory allocation. .SH NOTES The LDAP libraries with the .B LDAP_OPT_REFERRALS option set to .B LDAP_OPT_ON (default value) automatically follow referrals using an anonymous bind. Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chasing by setting that option to .BR LDAP_OPT_OFF . .P The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to the .B LDAP_VERSION2 macro. Application developers are encouraged to explicitly set .B LDAP_OPT_PROTOCOL_VERSION to LDAPv3, using the .B LDAP_VERSION3 macro, or to allow users to select the protocol version. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .B RFC 4422 (http://www.rfc-editor.org), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 811 stdin ber_next_element.3 0000644 00000030566 15152554704 0010171 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_str2matchingrule.3 0000644 00000021442 15152554704 0011140 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ber_get_bitstring.3 0000644 00000030566 15152554704 0010346 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_dn2ufn.3 0000644 00000015161 15152554704 0007040 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ber_put_null.3 0000644 00000022113 15152554704 0007331 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_add_s.3 0000644 00000005232 15152554704 0006714 0 ustar 00 .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ldap_extended_operation_s.3 0000644 00000004746 15152554704 0012055 0 ustar 00 .lf 1 stdin .TH LDAP_EXTENDED_OPERATION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_extended_operation, ldap_extended_operation_s \- Extends the LDAP operations to the LDAP server. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_extended_operation( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_extended_operation_s( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, char **\fIretoidp\fB, struct berval **\fIretdatap\fB ); .RE .SH DESCRIPTION The .B ldap_extended_operation_s() routine is used to synchronously perform an LDAP extended operation. It takes \fIrequestoid\fP, which points to a dotted-decimal OID string identifying the extended operation to perform. \fIrequestdata\fP is the data required for the request, \fIsctrls\fP is an array of LDAPControl structures to use with this extended operation, \fIcctrls\fP is an array of LDAPControl structures that list the client controls to use with this extended operation. .LP The output parameter \fIretoidp\fP points to a dotted-decimal OID string returned by the LDAP server. The memory used by the string should be freed with the .BR ldap_memfree (3) function. The output parameter \fIretdatap\fP points to a pointer to a berval structure that contains the returned data. If no data is returned by the server, the pointer is set this to NULL. The memory used by this structure should be freed with the .BR ber_bvfree (3) function. .LP The .B ldap_extended_operation() works just like .BR ldap_extended_operation_s() , but the operation is asynchronous. It provides the message id of the request it initiated in the integer pointed to be \fImsgidp\fP. The result of this operation can be obtained by calling .BR ldap_result(3). .SH SEE ALSO .BR ber_bvfree (3), .BR ldap_memfree (3), .BR ldap_parse_extended_result (3), .BR ldap_result (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 76 stdin ldap_control_dup.3 0000644 00000005675 15152554704 0010205 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ldap_controls.3 0000644 00000005675 15152554704 0007520 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ldap_schema.3 0000644 00000021442 15152554704 0007103 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_strdup.3 0000644 00000003060 15152554704 0007160 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ber_bvdup.3 0000644 00000014606 15152554704 0006617 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_sync.3 0000644 00000023012 15152554704 0006612 0 ustar 00 .lf 1 stdin .TH LDAP_SYNC 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2006-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ");" .LP .BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ");" .LP .BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls ");" .LP .BI "int ldap_sync_poll(ldap_sync_t *" ls ");" .LP .BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");" .LP .BI "void ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");" .LP .BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ", struct berval *" entryUUID "," .BI "ldap_sync_refresh_t " phase ");" .RE .LP .BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ");" .RE .LP .BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ", BerVarray " syncUUIDs "," .BI "ldap_sync_refresh_t " phase ");" .RE .LP .BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ", int " refreshDeletes ");" .RE .SH DESCRIPTION .LP These routines provide an interface to the LDAP Content Synchronization operation (RFC 4533). They require an .BR ldap_sync_t structure to be set up with parameters required for various phases of the operation; this includes setting some handlers for special events. All handlers take a pointer to the \fBldap_sync_t\fP structure as the first argument, and a pointer to the \fBLDAPMessage\fP structure as received from the server by the client library, plus, occasionally, other specific arguments. The members of the \fBldap_sync_t\fP structure are: .TP .BI "char *" ls_base The search base; by default, the .B BASE option in .BR ldap.conf (5). .TP .BI "int " ls_scope The search scope (one of .BR LDAP_SCOPE_BASE , .BR LDAP_SCOPE_ONELEVEL , .BR LDAP_SCOPE_SUBORDINATE or .BR LDAP_SCOPE_SUBTREE ; see .B ldap.h for details). .TP .BI "char *" ls_filter The filter (RFC 4515); by default, .BR (objectClass=*) . .TP .BI "char **" ls_attrs The requested attributes; by default .BR NULL , indicating all user attributes. .TP .BI "int " ls_timelimit The requested time limit (in seconds); by default .BR 0 , to indicate no limit. .TP .BI "int " ls_sizelimit The requested size limit (in entries); by default .BR 0 , to indicate no limit. .TP .BI "int " ls_timeout The desired timeout during polling with .BR ldap_sync_poll (3). A value of .BR \-1 means that polling is blocking, so .BR ldap_sync_poll (3) will not return until a message is received; a value of .BR 0 means that polling returns immediately, no matter if any response is available or not; a positive value represents the timeout the .BR ldap_sync_poll (3) function will wait for response before returning, unless a message is received; in that case, .BR ldap_sync_poll (3) returns as soon as the message is available. .TP .BI "ldap_sync_search_entry_f " ls_search_entry A function that is called whenever an entry is returned. The .BR msg argument is the .BR LDAPMessage that contains the searchResultEntry; it can be parsed using the regular client API routines, like .BR ldap_get_dn (3), .BR ldap_first_attribute (3), and so on. The .BR entryUUID argument contains the entryUUID of the entry. The .BR phase argument indicates the type of operation: one of .BR LDAP_SYNC_CAPI_PRESENT , .BR LDAP_SYNC_CAPI_ADD , .BR LDAP_SYNC_CAPI_MODIFY , .BR LDAP_SYNC_CAPI_DELETE ; in case of .BR LDAP_SYNC_CAPI_PRESENT or .BR LDAP_SYNC_CAPI_DELETE , only the DN is contained in the .IR LDAPMessage ; in case of .BR LDAP_SYNC_CAPI_MODIFY , the whole entry is contained in the .IR LDAPMessage , and the application is responsible of determining the differences between the new view of the entry provided by the caller and the data already known. .TP .BI "ldap_sync_search_reference_f " ls_search_reference A function that is called whenever a search reference is returned. The .BR msg argument is the .BR LDAPMessage that contains the searchResultReference; it can be parsed using the regular client API routines, like .BR ldap_parse_reference (3). .TP .BI "ldap_sync_intermediate_f " ls_intermediate A function that is called whenever something relevant occurs during the refresh phase of the search, which is marked by an \fIintermediateResponse\fP message type. The .BR msg argument is the .BR LDAPMessage that contains the intermediate response; it can be parsed using the regular client API routines, like .BR ldap_parse_intermediate (3). The .BR syncUUIDs argument contains an array of UUIDs of the entries that depends on the value of the .BR phase argument. In case of .BR LDAP_SYNC_CAPI_PRESENTS , the "present" phase is being entered; this means that the following sequence of results will consist in entries in "present" sync state. In case of .BR LDAP_SYNC_CAPI_DELETES , the "deletes" phase is being entered; this means that the following sequence of results will consist in entries in "delete" sync state. In case of .BR LDAP_SYNC_CAPI_PRESENTS_IDSET , the message contains a set of UUIDs of entries that are present; it replaces a "presents" phase. In case of .BR LDAP_SYNC_CAPI_DELETES_IDSET , the message contains a set of UUIDs of entries that have been deleted; it replaces a "deletes" phase. In case of .BR LDAP_SYNC_CAPI_DONE, a "presents" phase with "refreshDone" set to "TRUE" has been returned to indicate that the refresh phase of refreshAndPersist is over, and the client should start polling. Except for the .BR LDAP_SYNC_CAPI_PRESENTS_IDSET and .BR LDAP_SYNC_CAPI_DELETES_IDSET cases, .BR syncUUIDs is NULL. .BR .TP .BI "ldap_sync_search_result_f " ls_search_result A function that is called whenever a searchResultDone is returned. In refreshAndPersist this can only occur when the server decides that the search must be interrupted. The .BR msg argument is the .BR LDAPMessage that contains the response; it can be parsed using the regular client API routines, like .BR ldap_parse_result (3). The .BR refreshDeletes argument is not relevant in this case; it should always be \-1. .TP .BI "void *" ls_private A pointer to private data. The client may register here a pointer to data the handlers above may need. .TP .BI "LDAP *" ls_ld A pointer to a LDAP structure that is used to connect to the server. It is the responsibility of the client to initialize the structure and to provide appropriate authentication and security in place. .SH "GENERAL USE" A .B ldap_sync_t structure is initialized by calling .BR ldap_sync_initialize(3). This simply clears out the contents of an already existing .B ldap_sync_t structure, and sets appropriate values for some members. After that, the caller is responsible for setting up the connection (member .BR ls_ld ), eventually setting up transport security (TLS), for binding and any other initialization. The caller must also fill all the documented search-related fields of the .B ldap_sync_t structure. At the end of a session, the structure can be cleaned up by calling .BR ldap_sync_destroy (3), which takes care of freeing all data assuming it was allocated by .BR ldap_mem* (3) routines. Otherwise, the caller should take care of destroying and zeroing out the documented search-related fields, and call .BR ldap_sync_destroy (3) to free undocumented members set by the API. .SH "REFRESH ONLY" The .BR refreshOnly functionality is obtained by periodically calling .BR ldap_sync_init (3) with mode set to .BR LDAP_SYNC_REFRESH_ONLY , or, which is equivalent, by directly calling .BR ldap_sync_init_refresh_only (3). The state of the search, and the consistency of the search parameters, is preserved across calls by passing the .B ldap_sync_t structure as left by the previous call. .SH "REFRESH AND PERSIST" The .BR refreshAndPersist functionality is obtained by calling .BR ldap_sync_init (3) with mode set to .BR LDAP_SYNC_REFRESH_AND_PERSIST , or, which is equivalent, by directly calling .BR ldap_sync_init_refresh_and_persist (3) and, after a successful return, by repeatedly polling with .BR ldap_sync_poll (3) according to the desired pattern. A client may insert a call to .BR ldap_sync_poll (3) into an external loop to check if any modification was returned; in this case, it might be appropriate to set .BR ls_timeout to 0, or to set it to a finite, small value. Otherwise, if the client's main purpose consists in waiting for responses, a timeout of \-1 is most suitable, so that the function only returns after some data has been received and handled. .SH ERRORS All routines return any LDAP error resulting from a lower-level error in the API calls they are based on, or LDAP_SUCCESS in case of success. .BR ldap_sync_poll (3) may return .BR LDAP_SYNC_REFRESH_REQUIRED if a full refresh is requested by the server. In this case, it is appropriate to call .BR ldap_sync_init (3) again, passing the same .B ldap_sync_t structure as resulted from any previous call. .SH NOTES .SH SEE ALSO .BR ldap (3), .BR ldap_search_ext (3), .BR ldap_result (3) ; .B RFC 4533 (http://www.rfc-editor.org), .SH AUTHOR Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by syncrepl code in .BR slapd (8). .SH ACKNOWLEDGEMENTS Initially developed by .BR "SysNet s.n.c." .B OpenLDAP is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). .B OpenLDAP is derived from University of Michigan LDAP 3.3 Release. ldap_install_tls.3 0000644 00000003237 15152554704 0010175 0 ustar 00 .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin ldap_search_ext_s.3 0000644 00000012165 15152554704 0010314 0 ustar 00 .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin ldap_url.3 0000644 00000006031 15152554704 0006442 0 ustar 00 .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin ldap_sasl_bind.3 0000644 00000027376 15152554704 0007615 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_count_references.3 0000644 00000004455 15152554704 0011201 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_references( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) .SH DESCRIPTION .LP These routines are used to step through the continuation references in a result chain received from .BR ldap_result (3) or the synchronous LDAP search operation routines. .LP The .B ldap_first_reference() routine is used to retrieve the first reference message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first reference message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_reference() to get the next reference message, the result of which should be supplied to the next call to .BR ldap_next_reference() , etc. .B ldap_next_reference() will return NULL when there are no more reference messages. The reference messages returned from these calls are used by .BR ldap_parse_reference (3) to extract referrals and controls. .LP A count of the number of reference messages in the search result can be obtained by calling .BR ldap_count_references() . It can also be used to count the number of reference messages remaining in a result chain. .SH ERRORS If an error occurs in .B ldap_first_reference() or .BR ldap_next_reference() , NULL is returned. If an error occurs in .BR ldap_count_references() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_parse_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 72 stdin ldap_extended_operation.3 0000644 00000004746 15152554704 0011533 0 ustar 00 .lf 1 stdin .TH LDAP_EXTENDED_OPERATION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_extended_operation, ldap_extended_operation_s \- Extends the LDAP operations to the LDAP server. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_extended_operation( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_extended_operation_s( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, char **\fIretoidp\fB, struct berval **\fIretdatap\fB ); .RE .SH DESCRIPTION The .B ldap_extended_operation_s() routine is used to synchronously perform an LDAP extended operation. It takes \fIrequestoid\fP, which points to a dotted-decimal OID string identifying the extended operation to perform. \fIrequestdata\fP is the data required for the request, \fIsctrls\fP is an array of LDAPControl structures to use with this extended operation, \fIcctrls\fP is an array of LDAPControl structures that list the client controls to use with this extended operation. .LP The output parameter \fIretoidp\fP points to a dotted-decimal OID string returned by the LDAP server. The memory used by the string should be freed with the .BR ldap_memfree (3) function. The output parameter \fIretdatap\fP points to a pointer to a berval structure that contains the returned data. If no data is returned by the server, the pointer is set this to NULL. The memory used by this structure should be freed with the .BR ber_bvfree (3) function. .LP The .B ldap_extended_operation() works just like .BR ldap_extended_operation_s() , but the operation is asynchronous. It provides the message id of the request it initiated in the integer pointed to be \fImsgidp\fP. The result of this operation can be obtained by calling .BR ldap_result(3). .SH SEE ALSO .BR ber_bvfree (3), .BR ldap_memfree (3), .BR ldap_parse_extended_result (3), .BR ldap_result (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 76 stdin ldap_modify_ext_s.3 0000644 00000010711 15152554704 0010331 0 ustar 00 .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary. For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the attribute if no values remain. If the entire attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_dn2ad_canonical.3 0000644 00000015161 15152554704 0010643 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_scherr2str.3 0000644 00000021442 15152554704 0007744 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_modify.3 0000644 00000010711 15152554704 0007127 0 ustar 00 .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary. For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the attribute if no values remain. If the entire attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_abandon.3 0000644 00000004455 15152554704 0007252 0 ustar 00 .lf 1 stdin .TH LDAP_ABANDON 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_abandon_ext \- Abandon an LDAP operation in progress .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .ft B int ldap_abandon_ext( .RS .ft B LDAP *\fIld\fB, Bint \fImsgid\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_abandon_ext() routine is used to send a LDAP Abandon request for an operation in progress. The \fImsgid\fP passed should be the message id of an outstanding LDAP operation, such as returned by .BR ldap_search_ext (3). .LP .BR ldap_abandon_ext () checks to see if the result of the operation has already come in. If it has, it deletes it from the queue of pending messages. If not, it sends an LDAP abandon request to the LDAP server. .LP The caller can expect that the result of an abandoned operation will not be returned from a future call to .BR ldap_result (3). .LP .B ldap_abandon_ext() allows server and client controls to be passed in via the .I sctrls and .I cctrls parameters, respectively. .LP .B ldap_abandon_ext() returns a code indicating success or, in the case of failure, the nature of the failure. See .BR ldap_error (3) for details. .SH DEPRECATED INTERFACES The .B ldap_abandon() routine is deprecated in favor of the .B ldap_abandon_ext() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 61 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_result (3), .BR ldap_search_ext (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 69 stdin ldap_set_option.3 0000644 00000046074 15152554704 0010036 0 ustar 00 .lf 1 stdin .TH LDAP_GET_OPTION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_option, ldap_set_option \- LDAP option handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");" .LP .BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");" .SH DESCRIPTION .LP These routines provide access to options stored either in a LDAP handle or as global options, where applicable. They make use of a neutral interface, where the type of the value either retrieved by .BR ldap_get_option (3) or set by .BR ldap_set_option (3) is cast to .BR "void *" . The actual type is determined based on the value of the .B option argument. Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles inherit their default settings from the global options in effect at the time the handle is created. .TP .B LDAP_OPT_API_FEATURE_INFO Fills-in a .BR "LDAPAPIFeatureInfo" ; .BR outvalue must be a .BR "LDAPAPIFeatureInfo *" , pointing to an already allocated struct. The .B ldapaif_info_version field of the struct must be initialized to .B LDAP_FEATURE_INFO_VERSION before making the call. The .B ldapaif_name field must be set to the name of a feature to query. This is a read-only option. .TP .B LDAP_OPT_API_INFO Fills-in a .BR "LDAPAPIInfo" ; .BR outvalue must be a .BR "LDAPAPIInfo *" , pointing to an already allocated struct. The .B ldapai_info_version field of the struct must be initialized to .B LDAP_API_INFO_VERSION before making the call. If the version passed in does not match the current library version, the expected version number will be stored in the struct and the call will fail. The caller is responsible for freeing the elements of the .B ldapai_extensions array and the array itself using .BR ldap_memfree (3). The caller must also free the .BR ldapi_vendor_name . This is a read-only option. .TP .B LDAP_OPT_CLIENT_CONTROLS Sets/gets the client-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts client-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag. .BR invalue should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON ; .BR outvalue must be .BR "int *" . When set, the library will call .BR connect (2) and return, without waiting for response. This leaves the handle in a connecting state. Subsequent calls to library routines will poll for completion of the connect before performing further operations. As a consequence, library calls that need to establish a connection with a DSA do not block even for the network timeout (option .BR LDAP_OPT_NETWORK_TIMEOUT ). This option is OpenLDAP specific. .TP .B LDAP_OPT_CONNECT_CB This option allows to set a connect callback. .B invalue must be a .BR "const struct ldap_conncb *" . Callbacks are executed in last in-first served order. Handle-specific callbacks are executed first, followed by global ones. Right before freeing the callback structure, the .B lc_del callback handler is passed a .B NULL .BR Sockbuf . Calling .BR ldap_get_option (3) for this option removes the callback whose pointer matches .BR outvalue . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEBUG_LEVEL Sets/gets the debug level of the client library. .BR invalue must be a .BR "const int *" ; .BR outvalue must be a .BR "int *" . Valid debug levels are .BR LDAP_DEBUG_ANY , .BR LDAP_DEBUG_ARGS , .BR LDAP_DEBUG_BER , .BR LDAP_DEBUG_CONNS , .BR LDAP_DEBUG_NONE , .BR LDAP_DEBUG_PACKETS , .BR LDAP_DEBUG_PARSE , and .BR LDAP_DEBUG_TRACE . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEFBASE Sets/gets a string containing the DN to be used as default base for search operations. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_DEREF Sets/gets the value that defines when alias dereferencing must occur. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . They cannot be NULL. The value of .BR *invalue should be one of .BR LDAP_DEREF_NEVER (the default), .BR LDAP_DEREF_SEARCHING , .BR LDAP_DEREF_FINDING , or .BR LDAP_DEREF_ALWAYS . Note that this has ever been the only means to determine alias dereferencing within search operations. .TP .B LDAP_OPT_DESC Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. .TP .B LDAP_OPT_DIAGNOSTIC_MESSAGE Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as .BR LDAP_OPT_ERROR_STRING . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_HOST_NAME Sets/gets a space-separated list of hosts to be contacted by the library when trying to establish a connection. This is now deprecated in favor of .BR LDAP_OPT_URI . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_MATCHED_DN Sets/gets a string containing the matched DN associated to the LDAP handle. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after which .BR poll (2)/ select (2) following a .BR connect (2) returns in case of no activity. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "const struct timeval *" . They cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_PROTOCOL_VERSION Sets/gets the protocol version. .BR outvalue and .BR invalue must be .BR "int *" . .TP .B LDAP_OPT_REFERRAL_URLS Sets/gets an array containing the referral URIs associated to the LDAP handle. .BR outvalue must be a .BR "char ***" , and the caller is responsible of freeing the returned string by calling .BR ldap_memvfree (3), while .BR invalue must be a NULL-terminated .BR "char *const *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .\".TP .\".B LDAP_OPT_REFHOPLIMIT .\"This option is OpenLDAP specific. .\"It is not currently implemented. .TP .B LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME). .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This option was formerly known as .BR LDAP_OPT_ERROR_NUMBER . .BR invalue must be a .BR "const int *" . .BR outvalue must be a .BR "int *" . .TP .B LDAP_OPT_SERVER_CONTROLS Sets/gets the server-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts server-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_SESSION_REFCNT Returns the reference count associated with the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_SIZELIMIT Sets/gets the value that defines the maximum number of entries to be returned by a search operation. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" ; They cannot be NULL. .TP .B LDAP_OPT_SOCKBUF Returns a pointer to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "Sockbuf **" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_TIMELIMIT Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" , and they cannot be NULL. .TP .B LDAP_OPT_TIMEOUT Sets/gets a timeout value for the synchronous API calls. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "struct timeval *" , and they cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_URI Sets/gets a comma- or space-separated list of URIs to be contacted by the library when trying to establish a connection. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library parses the string into a list of .BR LDAPURLDesc structures, so the invocation of .BR ldap_set_option (3) may fail if URL parsing fails. URIs may only contain the .BR schema , the .BR host , and the .BR port fields. This option is OpenLDAP specific. .SH SASL OPTIONS The SASL options are OpenLDAP specific. .TP .B LDAP_OPT_X_SASL_AUTHCID Gets the SASL authentication identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_AUTHZID Gets the SASL authorization identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MAXBUFSIZE Gets/sets SASL maximum buffer size; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_MECH Gets the SASL mechanism; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MECHLIST Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; .BR outvalue must be .BR "char ***" . The caller must not free or otherwise muck with it. .TP .B LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonicalized. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_SASL_REALM Gets the SASL realm; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_SECPROPS Sets the SASL secprops; .BR invalue must be a .BR "char *" , containing a comma-separated list of properties. Legal values are: .BR none , .BR nodict , .BR noplain , .BR noactive , .BR passcred , .BR forwardsec , .BR noanonymous , .BR minssf=<minssf> , .BR maxssf=<maxssf> , .BR maxbufsize=<maxbufsize> . .TP .B LDAP_OPT_X_SASL_SSF Gets the SASL SSF; .BR outvalue must be a .BR "ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_EXTERNAL Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism; .BR invalue must be a .BR "const ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_MAX Gets/sets SASL maximum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_USERNAME Gets the SASL username; .BR outvalue must be a .BR "char **" . Its content needs to be freed by the caller using .BR ldap_memfree (3). .SH TCP OPTIONS The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable. .TP .B LDAP_OPT_X_KEEPALIVE_IDLE Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_PROBES Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_INTERVAL Sets/gets the interval in seconds between individual keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .SH TLS OPTIONS The TLS options are OpenLDAP specific. .\".TP .\".B LDAP_OPT_X_TLS .\"Sets/gets the TLS mode. .TP .B LDAP_OPT_X_TLS_CACERTDIR Sets/gets the path of the directory containing CA certificates. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CACERTFILE Sets/gets the full-path of the CA certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CERTFILE Sets/gets the full-path of the certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CIPHER_SUITE Sets/gets the allowed cipher suite. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CONNECT_ARG Sets/gets the connection callback argument. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . .TP .B LDAP_OPT_X_TLS_CONNECT_CB Sets/gets the connection callback handle. .BR invalue must be .BR "const LDAP_TLS_CONNECT_CB *" ; .BR outvalue must be .BR "LDAP_TLS_CONNECT_CB **" . .TP .B LDAP_OPT_X_TLS_CRLCHECK Sets/gets the CRL evaluation strategy, one of .BR LDAP_OPT_X_TLS_CRL_NONE , .BR LDAP_OPT_X_TLS_CRL_PEER , or .BR LDAP_OPT_X_TLS_CRL_ALL . .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . Requires OpenSSL. .TP .B LDAP_OPT_X_TLS_CRLFILE Sets/gets the full-path of the CRL file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). This option is only valid for GnuTLS. .TP .B LDAP_OPT_X_TLS_CTX Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL_CTX*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option or attempt to manipulate this structure. .TP .B LDAP_OPT_X_TLS_DHFILE Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS and Mozilla NSS. .TP .B LDAP_OPT_X_TLS_KEYFILE Sets/gets the full-path of the certificate key file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_NEWCTX Instructs the library to create a new TLS library context. .BR invalue must be .BR "const int *" . A non-zero value pointed to by .BR invalue tells the library to create a context for a server. .TP .B LDAP_OPT_X_TLS_PROTOCOL_MIN Sets/gets the minimum protocol version. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_TLS_RANDOM_FILE Sets/gets the random file when .B /dev/random and .B /dev/urandom are not available. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS. .TP .B LDAP_OPT_X_TLS_REQUIRE_CERT Sets/gets the peer certificate checking strategy, one of .BR LDAP_OPT_X_TLS_NEVER , .BR LDAP_OPT_X_TLS_HARD , .BR LDAP_OPT_X_TLS_DEMAND , .BR LDAP_OPT_X_TLS_ALLOW , .BR LDAP_OPT_X_TLS_TRY . .TP .B LDAP_OPT_X_TLS_SSL_CTX Gets the TLS session context associated with this handle. .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option. .SH ERRORS On success, the functions return .BR LDAP_OPT_SUCCESS , while they may return .B LDAP_OPT_ERROR to indicate a generic option handling error. Occasionally, more specific errors can be returned, like .B LDAP_NO_MEMORY to indicate a failure in memory allocation. .SH NOTES The LDAP libraries with the .B LDAP_OPT_REFERRALS option set to .B LDAP_OPT_ON (default value) automatically follow referrals using an anonymous bind. Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chasing by setting that option to .BR LDAP_OPT_OFF . .P The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to the .B LDAP_VERSION2 macro. Application developers are encouraged to explicitly set .B LDAP_OPT_PROTOCOL_VERSION to LDAPv3, using the .B LDAP_VERSION3 macro, or to allow users to select the protocol version. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .B RFC 4422 (http://www.rfc-editor.org), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 811 stdin ldap_sort_strcasecmp.3 0000644 00000002350 15152554704 0011053 0 ustar 00 .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin ber_get_null.3 0000644 00000030566 15152554704 0007313 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_delete_s.3 0000644 00000004767 15152554705 0007443 0 ustar 00 .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin ber_put_seq.3 0000644 00000022113 15152554705 0007150 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin lber-sockbuf.3 0000644 00000013336 15152554705 0007225 0 ustar 00 .lf 1 stdin .TH LBER_SOCKBUF 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io, ber_sockbuf_remove_io, Sockbuf_IO \- OpenLDAP LBER I/O infrastructure .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .B Sockbuf *ber_sockbuf_alloc( void ); .LP .BI "void ber_sockbuf_free(Sockbuf *" sb ");" .LP .BI "int ber_sockbuf_ctrl(Sockbuf *" sb ", int " opt ", void *" arg ");" .LP .BI "int ber_sockbuf_add_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ", void *" arg ");" .LP .BI "int ber_sockbuf_remove_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ");" .LP .nf .B typedef struct sockbuf_io_desc { .BI "int " sbiod_level ";" .BI "Sockbuf *" sbiod_sb ";" .BI "Sockbuf_IO *" sbiod_io ";" .BI "void *" sbiod_pvt ";" .BI "struct sockbuf_io_desc *" sbiod_next ";" .B } Sockbuf_IO_Desc; .LP .B typedef struct sockbuf_io { .BI "int (*" sbi_setup ")(Sockbuf_IO_Desc *" sbiod ", void *" arg ");" .BI "int (*" sbi_remove ")(Sockbuf_IO_Desc *" sbiod ");" .BI "int (*" sbi_ctrl ")(Sockbuf_IO_Desc *" sbiod ", int " opt ", void *" arg ");" .BI "ber_slen_t (*" sbi_read ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" .BI "ber_slen_t (*" sbi_write ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" .BI "int (*" sbi_close ")(Sockbuf_IO_Desc *" sbiod ");" .B } Sockbuf_IO; .SH DESCRIPTION .LP These routines are used to manage the low level I/O operations performed by the Lightweight BER library. They are called implicitly by the other libraries and usually do not need to be called directly from applications. The I/O framework is modularized and new transport layers can be supported by appropriately defining a .B Sockbuf_IO structure and installing it onto an existing .BR Sockbuf . .B Sockbuf structures are allocated and freed by .BR ber_sockbuf_alloc () and .BR ber_sockbuf_free (), respectively. The .BR ber_sockbuf_ctrl () function is used to get and set options related to a .B Sockbuf or to a specific I/O layer of the .BR Sockbuf . The .BR ber_sockbuf_add_io () and .BR ber_sockbuf_remove_io () functions are used to add and remove specific I/O layers on a .BR Sockbuf . Options for .BR ber_sockbuf_ctrl () include: .TP .B LBER_SB_OPT_HAS_IO Takes a .B Sockbuf_IO * argument and returns 1 if the given handler is installed on the .BR Sockbuf , otherwise returns 0. .TP .B LBER_SB_OPT_GET_FD Retrieves the file descriptor associated to the .BR Sockbuf ; .B arg must be a .BR "ber_socket_t *" . The return value will be 1 if a valid descriptor was present, \-1 otherwise. .TP .B LBER_SB_OPT_SET_FD Sets the file descriptor of the .B Sockbuf to the descriptor pointed to by .BR arg ; .B arg must be a .BR "ber_socket_t *" . The return value will always be 1. .TP .B LBER_SB_OPT_SET_NONBLOCK Toggles the non-blocking state of the file descriptor associated to the .BR Sockbuf . .B arg should be NULL to disable and non-NULL to enable the non-blocking state. The return value will be 1 for success, \-1 otherwise. .TP .B LBER_SB_OPT_DRAIN Flush (read and discard) all available input on the .BR Sockbuf . The return value will be 1. .TP .B LBER_SB_OPT_NEEDS_READ Returns non-zero if input is waiting to be read. .TP .B LBER_SB_OPT_NEEDS_WRITE Returns non-zero if the .B Sockbuf is ready to be written. .TP .B LBER_SB_OPT_GET_MAX_INCOMING Returns the maximum allowed size of an incoming message; .B arg must be a .BR "ber_len_t *" . The return value will be 1. .TP .B LBER_SB_OPT_SET_MAX_INCOMING Sets the maximum allowed size of an incoming message; .B arg must be a .BR "ber_len_t *" . The return value will be 1. .LP Options not in this list will be passed down to each .B Sockbuf_IO handler in turn until one of them processes it. If the option is not handled .BR ber_sockbuf_ctrl () will return 0. .LP Multiple .B Sockbuf_IO handlers can be stacked in multiple layers to provide various functionality. Currently defined layers include .TP .B LBER_SBIOD_LEVEL_PROVIDER the lowest layer, talking directly to a network .TP .B LBER_SBIOD_LEVEL_TRANSPORT an intermediate layer .TP .B LBER_SBIOD_LEVEL_APPLICATION a higher layer .LP Currently defined .B Sockbuf_IO handlers in liblber include .TP .B ber_sockbuf_io_tcp The default stream-oriented provider .TP .B ber_sockbuf_io_fd A stream-oriented provider for local IPC sockets .TP .B ber_sockbuf_io_dgram A datagram-oriented provider. This handler is only present if the liblber library was built with LDAP_CONNECTIONLESS defined. .TP .B ber_sockbuf_io_readahead A buffering layer, usually used with a datagram provider to hide the datagram semantics from upper layers. .TP .B ber_sockbuf_io_debug A generic handler that outputs hex dumps of all traffic. This handler may be inserted multiple times at arbitrary layers to show the flow of data between other handlers. .LP Additional handlers may be present in libldap if support for them was enabled: .TP .B ldap_pvt_sockbuf_io_sasl An application layer handler for SASL encoding/decoding. .TP .B sb_tls_sbio A transport layer handler for SSL/TLS encoding/decoding. Note that this handler is private to the library and is not exposed in the API. .LP The provided handlers are all instantiated implicitly by libldap, and applications generally will not need to directly manipulate them. .SH SEE ALSO .BR lber-decode (3), .BR lber-encode (3), .BR lber-types (3), .BR ldap_get_option (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 200 stdin ldap_result.3 0000644 00000010641 15152554705 0007161 0 ustar 00 .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) LDAP_RES_SEARCH_RESULT (0x65) LDAP_RES_MODIFY (0x67) LDAP_RES_ADD (0x69) LDAP_RES_DELETE (0x6b) LDAP_RES_MODDN (0x6d) LDAP_RES_COMPARE (0x6f) LDAP_RES_EXTENDED (0x78) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_first_message.3 0000644 00000005117 15152554705 0010500 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_MESSAGE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_messages( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) .SH DESCRIPTION .LP These routines are used to step through the messages in a result chain received from .BR ldap_result (3) . For search operations, the result chain can contain referral, entry and result messages. The .BR ldap_msgtype (3) function can be used to distinguish between the different message types. .LP The .B ldap_first_message() routine is used to retrieve the first message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_message() to get the next message, the result of which should be supplied to the next call to .BR ldap_next_message() , etc. .B ldap_next_message() will return NULL when there are no more messages. .LP These functions are useful when using routines like .BR ldap_parse_result (3) that only operate on the first result in the chain. .LP A count of the number of messages in the result chain can be obtained by calling .BR ldap_count_messages() . It can also be used to count the number of remaining messages in a chain if called with a message, entry or reference returned by .B ldap_first_message() , .B ldap_next_message() , .BR ldap_first_entry (3) , .BR ldap_next_entry (3) , .BR ldap_first_reference (3) , .BR ldap_next_reference (3) . .SH ERRORS If an error occurs in .B ldap_first_message() or .BR ldap_next_message() , NULL is returned. If an error occurs in .BR ldap_count_messages() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_result (3), .BR ldap_parse_result (3), .BR ldap_first_entry (3), .BR ldap_first_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 83 stdin ldap_memalloc.3 0000644 00000003060 15152554705 0007431 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ldap_simple_bind.3 0000644 00000027376 15152554705 0010145 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_modrdn_s.3 0000644 00000004420 15152554705 0007446 0 ustar 00 .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ber_free.3 0000644 00000014606 15152554705 0006421 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_next_reference.3 0000644 00000004455 15152554705 0010645 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_references( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) .SH DESCRIPTION .LP These routines are used to step through the continuation references in a result chain received from .BR ldap_result (3) or the synchronous LDAP search operation routines. .LP The .B ldap_first_reference() routine is used to retrieve the first reference message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first reference message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_reference() to get the next reference message, the result of which should be supplied to the next call to .BR ldap_next_reference() , etc. .B ldap_next_reference() will return NULL when there are no more reference messages. The reference messages returned from these calls are used by .BR ldap_parse_reference (3) to extract referrals and controls. .LP A count of the number of reference messages in the search result can be obtained by calling .BR ldap_count_references() . It can also be used to count the number of reference messages remaining in a result chain. .SH ERRORS If an error occurs in .B ldap_first_reference() or .BR ldap_next_reference() , NULL is returned. If an error occurs in .BR ldap_count_references() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_parse_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 72 stdin ldap_search_s.3 0000644 00000012165 15152554705 0007435 0 ustar 00 .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin ldap_search_ext.3 0000644 00000012165 15152554705 0007773 0 ustar 00 .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin ldap_compare.3 0000644 00000005343 15152554705 0007274 0 ustar 00 .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin ber_bvarray_free.3 0000644 00000014606 15152554705 0010147 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_objectclass2name.3 0000644 00000021442 15152554705 0011063 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ber_str2bv.3 0000644 00000014606 15152554705 0006722 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_sort.3 0000644 00000002350 15152554705 0006630 0 ustar 00 .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin ldap_modify_ext.3 0000644 00000010711 15152554705 0010010 0 ustar 00 .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary. For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the attribute if no values remain. If the entire attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_get_values_len.3 0000644 00000005350 15152554705 0010640 0 ustar 00 .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin ldap_msgfree.3 0000644 00000010641 15152554705 0007273 0 ustar 00 .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) LDAP_RES_SEARCH_RESULT (0x65) LDAP_RES_MODIFY (0x67) LDAP_RES_ADD (0x69) LDAP_RES_DELETE (0x6b) LDAP_RES_MODDN (0x6d) LDAP_RES_COMPARE (0x6f) LDAP_RES_EXTENDED (0x78) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_str2attributetype.3 0000644 00000021442 15152554705 0011364 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_count_messages.3 0000644 00000005117 15152554705 0010664 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_MESSAGE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_messages( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) .SH DESCRIPTION .LP These routines are used to step through the messages in a result chain received from .BR ldap_result (3) . For search operations, the result chain can contain referral, entry and result messages. The .BR ldap_msgtype (3) function can be used to distinguish between the different message types. .LP The .B ldap_first_message() routine is used to retrieve the first message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_message() to get the next message, the result of which should be supplied to the next call to .BR ldap_next_message() , etc. .B ldap_next_message() will return NULL when there are no more messages. .LP These functions are useful when using routines like .BR ldap_parse_result (3) that only operate on the first result in the chain. .LP A count of the number of messages in the result chain can be obtained by calling .BR ldap_count_messages() . It can also be used to count the number of remaining messages in a chain if called with a message, entry or reference returned by .B ldap_first_message() , .B ldap_next_message() , .BR ldap_first_entry (3) , .BR ldap_next_entry (3) , .BR ldap_first_reference (3) , .BR ldap_next_reference (3) . .SH ERRORS If an error occurs in .B ldap_first_message() or .BR ldap_next_message() , NULL is returned. If an error occurs in .BR ldap_count_messages() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_result (3), .BR ldap_parse_result (3), .BR ldap_first_entry (3), .BR ldap_first_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 83 stdin ldap_controls_free.3 0000644 00000005675 15152554705 0010522 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ber_scanf.3 0000644 00000030566 15152554705 0006575 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_matchingrule2str.3 0000644 00000021442 15152554705 0011141 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_objectclass_free.3 0000644 00000021442 15152554705 0011141 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ber_put_ostring.3 0000644 00000022113 15152554705 0010045 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_rename.3 0000644 00000005211 15152554705 0007107 0 ustar 00 .lf 1 stdin .TH LDAP_RENAME 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_rename, ldap_rename_s \- Renames the specified entry. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_rename( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[], msgidp ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; int *msgidp); .LP .ft B int ldap_rename_s( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[] ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; .SH DESCRIPTION These routines are used to perform a LDAP rename operation. The function changes the leaf component of an entry's distinguished name and optionally moves the entry to a new parent container. The .B ldap_rename_s performs a rename operation synchronously. The method takes \fIdn\fP, which points to the distinguished name of the entry whose attribute is being compared, \fInewparent\fP,the distinguished name of the entry's new parent. If this parameter is NULL, only the RDN is changed. The root DN is specified by passing a zero length string, "". \fIdeleteoldrdn\fP specifies whether the old RDN should be retained or deleted. Zero indicates that the old RDN should be retained. If you choose this option, the attribute will contain both names (the old and the new). Non-zero indicates that the old RDN should be deleted. \fIserverctrls\fP points to an array of LDAPControl structures that list the client controls to use with this extended operation. Use NULL to specify no client controls. \fIclientctrls\fP points to an array of LDAPControl structures that list the client controls to use with the search. .LP .B ldap_rename works just like .B ldap_rename_s, but the operation is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result(3). .SH ERRORS .B ldap_rename() returns \-1 in case of error initiating the request, and will set the \fIld_errno\fP field in the \fIld\fP parameter to indicate the error. .BR ldap_rename_s() returns the LDAP error code resulting from the rename operation. .SH SEE ALSO .BR ldap (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 67 stdin ldap_attributetype_free.3 0000644 00000021442 15152554705 0011552 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_set_rebind_proc.3 0000644 00000027376 15152554705 0011021 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_value_free_len.3 0000644 00000005350 15152554705 0010617 0 ustar 00 .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin ber_printf.3 0000644 00000022113 15152554705 0006772 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_dn2str.3 0000644 00000015161 15152554706 0007062 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_matchingrule_free.3 0000644 00000021442 15152554706 0011330 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_sasl_bind_s.3 0000644 00000027376 15152554706 0010141 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_open.3 0000644 00000013727 15152554706 0006615 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin ldap_search.3 0000644 00000012165 15152554706 0007114 0 ustar 00 .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin ber_get_stringb.3 0000644 00000030566 15152554706 0010013 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_set_urllist_proc.3 0000644 00000013727 15152554706 0011250 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin ldap_perror.3 0000644 00000015044 15152554706 0007157 0 ustar 00 .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin ldap_start_tls_s.3 0000644 00000003237 15152554706 0010210 0 ustar 00 .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin ldap_error.3 0000644 00000015044 15152554706 0006777 0 ustar 00 .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin ldap_value_free.3 0000644 00000005350 15152554706 0007762 0 ustar 00 .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin ber_bvecfree.3 0000644 00000014606 15152554706 0007262 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_delete_ext.3 0000644 00000004767 15152554706 0010002 0 ustar 00 .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin ldap_bind_s.3 0000644 00000027376 15152554706 0007117 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_msgtype.3 0000644 00000010641 15152554706 0007334 0 ustar 00 .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) LDAP_RES_SEARCH_RESULT (0x65) LDAP_RES_MODIFY (0x67) LDAP_RES_ADD (0x69) LDAP_RES_DELETE (0x6b) LDAP_RES_MODDN (0x6d) LDAP_RES_COMPARE (0x6f) LDAP_RES_EXTENDED (0x78) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_compare_ext_s.3 0000644 00000005343 15152554706 0010477 0 ustar 00 .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin ldap_first_attribute.3 0000644 00000004466 15152554706 0011066 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_ATTRIBUTE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **berptr ) .LP .ft B char *ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ber ) .SH DESCRIPTION The .B ldap_first_attribute() and .B ldap_next_attribute() routines are used to step through the attributes in an LDAP entry. .B ldap_first_attribute() takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a pointer to character string containing the first attribute description in the entry. .B ldap_next_attribute() returns the next attribute description in the entry. .LP It also returns, in \fIberptr\fP, a pointer to a BerElement it has allocated to keep track of its current position. This pointer should be passed to subsequent calls to .B ldap_next_attribute() and is used to effectively step through the entry's attributes. The caller is solely responsible for freeing the BerElement pointed to by \fIberptr\fP when it is no longer needed by calling .BR ber_free (3). When calling .BR ber_free (3) in this instance, be sure the second argument is 0. .LP The attribute names returned are suitable for inclusion in a call to .BR ldap_get_values (3) to retrieve the attribute's values. .SH ERRORS If an error occurs, NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES The .B ldap_first_attribute() and .B ldap_next_attribute() return dynamically allocated memory that must be freed by the caller via .BR ldap_memfree (3). .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_get_values (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 74 stdin ber_put_set.3 0000644 00000022113 15152554706 0007154 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_mods_free.3 0000644 00000010711 15152554706 0007605 0 ustar 00 .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary. For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the attribute if no values remain. If the entire attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ber_start_set.3 0000644 00000022113 15152554706 0007501 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_str2syntax.3 0000644 00000021442 15152554706 0010006 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_result2error.3 0000644 00000015044 15152554706 0010320 0 ustar 00 .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin ldap_msgid.3 0000644 00000010641 15152554706 0006747 0 ustar 00 .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) LDAP_RES_SEARCH_RESULT (0x65) LDAP_RES_MODIFY (0x67) LDAP_RES_ADD (0x69) LDAP_RES_DELETE (0x6b) LDAP_RES_MODDN (0x6d) LDAP_RES_COMPARE (0x6f) LDAP_RES_EXTENDED (0x78) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin ldap_destroy.3 0000644 00000007056 15152554706 0007343 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_dup( .RS .ft B LDAP *\fIold\fB ); .RE .LP .ft B int ldap_destroy( .RS .ft B LDAP *\fIold\fB ); .RE .SH DESCRIPTION .LP .B ldap_dup() duplicates an existing LDAP .RB ( "LDAP *" ) session handle. The new session handle may be used concurrently with the original session handle. In a threaded environment, different threads may execute concurrent requests on the same connection/session without fear of contamination. Each session handle manages its own private error results. .LP .B ldap_destroy() destroys an existing session handle. .LP The .B ldap_dup() and .B ldap_destroy() functions are used in conjunction with a "thread safe" version of .B libldap .RB ( libldap_r ) to enable operation thread safe API calls, so that a single session may be simultaneously used across multiple threads with consistent error handling. .LP When a session is created through the use of one of the session creation functions including .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3) or .BR ldap_init_fd (3) an .B "LDAP *" session handle is returned to the application. The session handle may be shared amongst threads, however the error codes are unique to a session handle. Multiple threads performing different operations using the same session handle will result in inconsistent error codes and return values. .LP To prevent this confusion, .B ldap_dup() is used duplicate an existing session handle so that multiple threads can share the session, and maintain consistent error information and results. .LP The message queues for a session are shared between sibling session handles. Results of operations on a sibling session handles are accessible to all the sibling session handles. Applications desiring results associated with a specific operation should provide the appropriate msgid to .BR ldap_result() . Applications should avoid calling .B ldap_result() with .B LDAP_RES_ANY as that may "steal" and return results in the calling thread that another operation in a different thread, using a different session handle, may require to complete. .LP When .B ldap_unbind() is called on a session handle with siblings, all the siblings become invalid. .LP Siblings must be destroyed using .BR ldap_destroy() . Session handle resources associated with the original .RB ( "LDAP *" ) will be freed when the last session handle is destroyed or when .B ldap_unbind() is called, if no other session handles currently exist. .SH ERRORS If an error occurs, .B ldap_dup() will return NULL and .I errno should be set appropriately. .B ldap_destroy() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .SH SEE ALSO .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3), .BR ldap_init_fd (3), .BR errno (3) .SH ACKNOWLEDGEMENTS This work is based on the previously proposed .B LDAP C API Concurrency Extensions draft .BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) effort. .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 127 stdin ldap_get_dn.3 0000644 00000015161 15152554706 0007106 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_unbind.3 0000644 00000027376 15152554706 0007140 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_init.3 0000644 00000013727 15152554706 0006617 0 ustar 00 .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin ldap_next_message.3 0000644 00000005117 15152554706 0010330 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_MESSAGE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_messages( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) .SH DESCRIPTION .LP These routines are used to step through the messages in a result chain received from .BR ldap_result (3) . For search operations, the result chain can contain referral, entry and result messages. The .BR ldap_msgtype (3) function can be used to distinguish between the different message types. .LP The .B ldap_first_message() routine is used to retrieve the first message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_message() to get the next message, the result of which should be supplied to the next call to .BR ldap_next_message() , etc. .B ldap_next_message() will return NULL when there are no more messages. .LP These functions are useful when using routines like .BR ldap_parse_result (3) that only operate on the first result in the chain. .LP A count of the number of messages in the result chain can be obtained by calling .BR ldap_count_messages() . It can also be used to count the number of remaining messages in a chain if called with a message, entry or reference returned by .B ldap_first_message() , .B ldap_next_message() , .BR ldap_first_entry (3) , .BR ldap_next_entry (3) , .BR ldap_first_reference (3) , .BR ldap_next_reference (3) . .SH ERRORS If an error occurs in .B ldap_first_message() or .BR ldap_next_message() , NULL is returned. If an error occurs in .BR ldap_count_messages() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_result (3), .BR ldap_parse_result (3), .BR ldap_first_entry (3), .BR ldap_first_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 83 stdin ldap_first_reference.3 0000644 00000004455 15152554706 0011017 0 ustar 00 .lf 1 stdin .TH LDAP_FIRST_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_references( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) .SH DESCRIPTION .LP These routines are used to step through the continuation references in a result chain received from .BR ldap_result (3) or the synchronous LDAP search operation routines. .LP The .B ldap_first_reference() routine is used to retrieve the first reference message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first reference message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_reference() to get the next reference message, the result of which should be supplied to the next call to .BR ldap_next_reference() , etc. .B ldap_next_reference() will return NULL when there are no more reference messages. The reference messages returned from these calls are used by .BR ldap_parse_reference (3) to extract referrals and controls. .LP A count of the number of reference messages in the search result can be obtained by calling .BR ldap_count_references() . It can also be used to count the number of reference messages remaining in a result chain. .SH ERRORS If an error occurs in .B ldap_first_reference() or .BR ldap_next_reference() , NULL is returned. If an error occurs in .BR ldap_count_references() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_parse_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 72 stdin ldap_add_ext.3 0000644 00000005232 15152554706 0007254 0 ustar 00 .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ldap_err2string.3 0000644 00000015044 15152554706 0007747 0 ustar 00 .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin ldap_attributetype2str.3 0000644 00000021442 15152554706 0011365 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_matchingrule2name.3 0000644 00000021442 15152554706 0011252 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_parse_sort_control.3 0000644 00000003223 15152554706 0011563 0 ustar 00 .lf 1 stdin .TH LDAP_PARSE_SORT-CONTROL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_sort_control \- Decode the information returned from a search operation that used a server-side sort control .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_sort_control(ld, ctrls, returnCode, attribute) .ft LDAP *ld; LDAPControl **ctrls; unsigned long *returnCode; char **attribute; .SH DESCRIPTION This function is used to parse the results returned in a search operation that uses a server-side sort control. .LP It takes a null terminated array of LDAPControl structures usually obtained by a call to the .BR ldap_parse_result function. A returncode which points to the sort control result code,and an array of LDAPControl structures that list the client controls to use with the search. The function also takes an out parameter \fIattribute\fP and if the sort operation fails, the server may return a string that indicates the first attribute in the sortKey list that caused the failure. If this parameter is NULL, no string is returned. If a string is returned, the memory should be freed by calling the ldap_memfree function. .SH NOTES .SH SEE ALSO .BR ldap_result (3), .BR ldap_controls_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 41 stdin ber_get_int.3 0000644 00000030566 15152554706 0007135 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_is_ldap_url.3 0000644 00000006031 15152554706 0010137 0 ustar 00 .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin ldap_parse_extended_result.3 0000644 00000007704 15152554706 0012242 0 ustar 00 .lf 1 stdin .TH LDAP_PARSE_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_result \- Parsing results .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_result( LDAP *ld, LDAPMessage *result, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .LP .ft B int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, struct berval **servercredp, int freeit ) .LP .ft B int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, char **retoidp, struct berval **retdatap, int freeit ) .SH DESCRIPTION .LP These routines are used to extract information from a result message. They will operate on the first result message in a chain of search results (skipping past other message types). They take the \fIresult\fP as returned by a call to .BR ldap_result (3), .BR ldap_search_s (3) or .BR ldap_search_st (3). In addition to .BR ldap_parse_result() , the routines .B ldap_parse_sasl_bind_result() and .B ldap_parse_extended_result() are used to get all the result information from SASL bind and extended operations. .LP The \fIerrcodep\fP parameter will be filled in with the result code from the result message. .LP The server might supply a matched DN string in the message indicating how much of a name in a request was recognized. The \fImatcheddnp\fP parameter will be filled in with this string if supplied, else it will be NULL. If a string is returned, it should be freed using .BR ldap_memfree (3). .LP The \fIerrmsgp\fP parameter will be filled in with the error message field from the parsed message. This string should be freed using .BR ldap_memfree (3). .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of referral strings from the parsed message. This array should be freed using .BR ldap_memvfree (3). If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed using .BR ldap_controls_free (3). If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .LP For SASL bind results, the \fIservercredp\fP parameter will be filled in with an allocated berval structure containing the credentials from the server if present. The structure should be freed using .BR ber_bvfree (3). .LP For extended results, the \fIretoidp\fP parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. The string should be freed using .BR ldap_memfree (3). If no OID was returned, \fI*retoidp\fP is set to NULL. .LP For extended results, the \fIretdatap\fP parameter will be filled in with a pointer to a berval structure containing the data from the extended operation response. The structure should be freed using .BR ber_bvfree (3). If no data were returned, \fI*retdatap\fP is set to NULL. .LP For all the above result parameters, NULL values can be used in calls in order to ignore certain fields. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the result parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_memfree (3), .BR ldap_memvfree (3), .BR ldap_get_values (3), .BR ldap_controls_free (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 108 stdin lber-decode.3 0000644 00000030566 15152554706 0007021 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ber_get_enum.3 0000644 00000030566 15152554706 0007307 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin ldap_control_free.3 0000644 00000005675 15152554706 0010340 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ber_bvstr.3 0000644 00000014606 15152554706 0006641 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_delete.3 0000644 00000004767 15152554706 0007122 0 ustar 00 .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin ber_bvstrdup.3 0000644 00000014606 15152554706 0007352 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_dcedn2dn.3 0000644 00000015161 15152554706 0007327 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_tls_inplace.3 0000644 00000003237 15152554706 0010144 0 ustar 00 .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin ldap_memvfree.3 0000644 00000003060 15152554706 0007447 0 ustar 00 .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin ldap_syntax_free.3 0000644 00000021442 15152554706 0010174 0 ustar 00 .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin ldap_modrdn2.3 0000644 00000004420 15152554707 0007210 0 ustar 00 .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin ber_alloc_t.3 0000644 00000022113 15152554707 0007107 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_bind.3 0000644 00000027376 15152554707 0006576 0 ustar 00 .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin ldap_parse_result.3 0000644 00000007704 15152554707 0010363 0 ustar 00 .lf 1 stdin .TH LDAP_PARSE_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_result \- Parsing results .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_result( LDAP *ld, LDAPMessage *result, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .LP .ft B int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, struct berval **servercredp, int freeit ) .LP .ft B int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, char **retoidp, struct berval **retdatap, int freeit ) .SH DESCRIPTION .LP These routines are used to extract information from a result message. They will operate on the first result message in a chain of search results (skipping past other message types). They take the \fIresult\fP as returned by a call to .BR ldap_result (3), .BR ldap_search_s (3) or .BR ldap_search_st (3). In addition to .BR ldap_parse_result() , the routines .B ldap_parse_sasl_bind_result() and .B ldap_parse_extended_result() are used to get all the result information from SASL bind and extended operations. .LP The \fIerrcodep\fP parameter will be filled in with the result code from the result message. .LP The server might supply a matched DN string in the message indicating how much of a name in a request was recognized. The \fImatcheddnp\fP parameter will be filled in with this string if supplied, else it will be NULL. If a string is returned, it should be freed using .BR ldap_memfree (3). .LP The \fIerrmsgp\fP parameter will be filled in with the error message field from the parsed message. This string should be freed using .BR ldap_memfree (3). .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of referral strings from the parsed message. This array should be freed using .BR ldap_memvfree (3). If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed using .BR ldap_controls_free (3). If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .LP For SASL bind results, the \fIservercredp\fP parameter will be filled in with an allocated berval structure containing the credentials from the server if present. The structure should be freed using .BR ber_bvfree (3). .LP For extended results, the \fIretoidp\fP parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. The string should be freed using .BR ldap_memfree (3). If no OID was returned, \fI*retoidp\fP is set to NULL. .LP For extended results, the \fIretdatap\fP parameter will be filled in with a pointer to a berval structure containing the data from the extended operation response. The structure should be freed using .BR ber_bvfree (3). If no data were returned, \fI*retdatap\fP is set to NULL. .LP For all the above result parameters, NULL values can be used in calls in order to ignore certain fields. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the result parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_memfree (3), .BR ldap_memvfree (3), .BR ldap_get_values (3), .BR ldap_controls_free (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 108 stdin ber_first_element.3 0000644 00000030566 15152554707 0010345 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin lber-encode.3 0000644 00000022113 15152554707 0007021 0 ustar 00 .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin ldap_explode_rdn.3 0000644 00000015161 15152554707 0010152 0 ustar 00 .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin ldap_control_find.3 0000644 00000005675 15152554707 0010340 0 ustar 00 .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin ber_skip_tag.3 0000644 00000030566 15152554707 0007306 0 ustar 00 .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin lber-types.3 0000644 00000014606 15152554707 0006740 0 ustar 00 .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin ldap_errlist.3 0000644 00000015044 15152554707 0007333 0 ustar 00 .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin