diff options
Diffstat (limited to 'doc/man/man3')
71 files changed, 6201 insertions, 0 deletions
diff --git a/doc/man/man3/Deprecated b/doc/man/man3/Deprecated new file mode 100644 index 0000000..3b7f696 --- /dev/null +++ b/doc/man/man3/Deprecated @@ -0,0 +1,7 @@ +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. diff --git a/doc/man/man3/Makefile.in b/doc/man/man3/Makefile.in new file mode 100644 index 0000000..0a43c6e --- /dev/null +++ b/doc/man/man3/Makefile.in @@ -0,0 +1,16 @@ +# man3 Makefile.in for OpenLDAP +# $OpenLDAP$ +## This work is part of OpenLDAP Software <http://www.openldap.org/>. +## +## Copyright 1998-2022 The OpenLDAP Foundation. +## All rights reserved. +## +## Redistribution and use in source and binary forms, with or without +## modification, are permitted only as authorized by the OpenLDAP +## Public License. +## +## A copy of this license is available in the file LICENSE in the +## top-level directory of the distribution or, alternatively, at +## <http://www.OpenLDAP.org/license.html>. + +MANSECT=3 diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3 new file mode 100644 index 0000000..97d4932 --- /dev/null +++ b/doc/man/man3/lber-decode.3 @@ -0,0 +1,357 @@ +.TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/lber-decode.3.links b/doc/man/man3/lber-decode.3.links new file mode 100644 index 0000000..3ec9328 --- /dev/null +++ b/doc/man/man3/lber-decode.3.links @@ -0,0 +1,13 @@ +ber_get_next.3 +ber_skip_tag.3 +ber_peek_tag.3 +ber_scanf.3 +ber_get_int.3 +ber_get_stringa.3 +ber_get_stringb.3 +ber_get_null.3 +ber_get_enum.3 +ber_get_boolean.3 +ber_get_bitstring.3 +ber_first_element.3 +ber_next_element.3 diff --git a/doc/man/man3/lber-encode.3 b/doc/man/man3/lber-encode.3 new file mode 100644 index 0000000..0d2e44d --- /dev/null +++ b/doc/man/man3/lber-encode.3 @@ -0,0 +1,288 @@ +.TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/lber-encode.3.links b/doc/man/man3/lber-encode.3.links new file mode 100644 index 0000000..54cd0e9 --- /dev/null +++ b/doc/man/man3/lber-encode.3.links @@ -0,0 +1,11 @@ +ber_alloc_t.3 +ber_flush.3 +ber_printf.3 +ber_put_int.3 +ber_put_ostring.3 +ber_put_string.3 +ber_put_null.3 +ber_put_enum.3 +ber_start_set.3 +ber_put_seq.3 +ber_put_set.3 diff --git a/doc/man/man3/lber-memory.3 b/doc/man/man3/lber-memory.3 new file mode 100644 index 0000000..70679b5 --- /dev/null +++ b/doc/man/man3/lber-memory.3 @@ -0,0 +1,49 @@ +.TH LBER_MEMORY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/lber-sockbuf.3 b/doc/man/man3/lber-sockbuf.3 new file mode 100644 index 0000000..383ccda --- /dev/null +++ b/doc/man/man3/lber-sockbuf.3 @@ -0,0 +1,199 @@ +.TH LBER_SOCKBUF 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/lber-types.3 b/doc/man/man3/lber-types.3 new file mode 100644 index 0000000..29cfc2c --- /dev/null +++ b/doc/man/man3/lber-types.3 @@ -0,0 +1,188 @@ +.TH LBER_TYPES 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/lber-types.3.links b/doc/man/man3/lber-types.3.links new file mode 100644 index 0000000..89f90fb --- /dev/null +++ b/doc/man/man3/lber-types.3.links @@ -0,0 +1,11 @@ +ber_bvarray_add.3 +ber_bvarray_free.3 +ber_bvdup.3 +ber_bvecadd.3 +ber_bvecfree.3 +ber_bvfree.3 +ber_bvstr.3 +ber_bvstrdup.3 +ber_dupbv.3 +ber_free.3 +ber_str2bv.3 diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 new file mode 100644 index 0000000..25fa0f0 --- /dev/null +++ b/doc/man/man3/ldap.3 @@ -0,0 +1,278 @@ +.TH LDAP 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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). +.so Deprecated +.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 +.so ../Project +.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. + diff --git a/doc/man/man3/ldap_abandon.3 b/doc/man/man3/ldap_abandon.3 new file mode 100644 index 0000000..7beb37a --- /dev/null +++ b/doc/man/man3/ldap_abandon.3 @@ -0,0 +1,69 @@ +.TH LDAP_ABANDON 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so Deprecated + +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_result (3), +.BR ldap_search_ext (3) +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/doc/man/man3/ldap_abandon.3.links b/doc/man/man3/ldap_abandon.3.links new file mode 100644 index 0000000..3b7bc3f --- /dev/null +++ b/doc/man/man3/ldap_abandon.3.links @@ -0,0 +1 @@ +ldap_abandon_ext.3 diff --git a/doc/man/man3/ldap_add.3 b/doc/man/man3/ldap_add.3 new file mode 100644 index 0000000..9fdc695 --- /dev/null +++ b/doc/man/man3/ldap_add.3 @@ -0,0 +1,81 @@ +.TH LDAP_ADD 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_modify (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_add.3.links b/doc/man/man3/ldap_add.3.links new file mode 100644 index 0000000..8114ef1 --- /dev/null +++ b/doc/man/man3/ldap_add.3.links @@ -0,0 +1,3 @@ +ldap_add_s.3 +ldap_add_ext.3 +ldap_add_ext_s.3 diff --git a/doc/man/man3/ldap_bind.3 b/doc/man/man3/ldap_bind.3 new file mode 100644 index 0000000..7b9e2de --- /dev/null +++ b/doc/man/man3/ldap_bind.3 @@ -0,0 +1,334 @@ +.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_bind.3.links b/doc/man/man3/ldap_bind.3.links new file mode 100644 index 0000000..ffaedd5 --- /dev/null +++ b/doc/man/man3/ldap_bind.3.links @@ -0,0 +1,10 @@ +ldap_bind_s.3 +ldap_simple_bind.3 +ldap_simple_bind_s.3 +ldap_sasl_bind.3 +ldap_sasl_bind_s.3 +ldap_unbind.3 +ldap_unbind_ext.3 +ldap_unbind_s.3 +ldap_unbind_ext_s.3 +ldap_set_rebind_proc.3 diff --git a/doc/man/man3/ldap_compare.3 b/doc/man/man3/ldap_compare.3 new file mode 100644 index 0000000..86b3bdd --- /dev/null +++ b/doc/man/man3/ldap_compare.3 @@ -0,0 +1,79 @@ +.TH LDAP_COMPARE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_compare.3.links b/doc/man/man3/ldap_compare.3.links new file mode 100644 index 0000000..66821cc --- /dev/null +++ b/doc/man/man3/ldap_compare.3.links @@ -0,0 +1,3 @@ +ldap_compare_s.3 +ldap_compare_ext.3 +ldap_compare_ext_s.3 diff --git a/doc/man/man3/ldap_controls.3 b/doc/man/man3/ldap_controls.3 new file mode 100644 index 0000000..292bb0e --- /dev/null +++ b/doc/man/man3/ldap_controls.3 @@ -0,0 +1,84 @@ +.TH LDAP_CONTROLS 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_controls.3.links b/doc/man/man3/ldap_controls.3.links new file mode 100644 index 0000000..6c5248f --- /dev/null +++ b/doc/man/man3/ldap_controls.3.links @@ -0,0 +1,6 @@ +ldap_control_create.3 +ldap_control_find.3 +ldap_control_dup.3 +ldap_controls_dup.3 +ldap_control_free.3 +ldap_controls_free.3 diff --git a/doc/man/man3/ldap_delete.3 b/doc/man/man3/ldap_delete.3 new file mode 100644 index 0000000..5086a6d --- /dev/null +++ b/doc/man/man3/ldap_delete.3 @@ -0,0 +1,89 @@ +.TH LDAP_DELETE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_delete.3.links b/doc/man/man3/ldap_delete.3.links new file mode 100644 index 0000000..d4eac2f --- /dev/null +++ b/doc/man/man3/ldap_delete.3.links @@ -0,0 +1,3 @@ +ldap_delete_s.3 +ldap_delete_ext.3 +ldap_delete_ext_s.3 diff --git a/doc/man/man3/ldap_dup.3 b/doc/man/man3/ldap_dup.3 new file mode 100644 index 0000000..945ca54 --- /dev/null +++ b/doc/man/man3/ldap_dup.3 @@ -0,0 +1,125 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +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. +.so ../Project diff --git a/doc/man/man3/ldap_dup.3.links b/doc/man/man3/ldap_dup.3.links new file mode 100644 index 0000000..1d77f93 --- /dev/null +++ b/doc/man/man3/ldap_dup.3.links @@ -0,0 +1 @@ +ldap_destroy.3 diff --git a/doc/man/man3/ldap_error.3 b/doc/man/man3/ldap_error.3 new file mode 100644 index 0000000..bbe0b5d --- /dev/null +++ b/doc/man/man3/ldap_error.3 @@ -0,0 +1,224 @@ +.TH LDAP_ERROR 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so Deprecated + +.SH SEE ALSO +.BR ldap (3), +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_error.3.links b/doc/man/man3/ldap_error.3.links new file mode 100644 index 0000000..841370d --- /dev/null +++ b/doc/man/man3/ldap_error.3.links @@ -0,0 +1,5 @@ +ldap_perror.3 +ld_errno.3 +ldap_result2error.3 +ldap_errlist.3 +ldap_err2string.3 diff --git a/doc/man/man3/ldap_extended_operation.3 b/doc/man/man3/ldap_extended_operation.3 new file mode 100644 index 0000000..02ec882 --- /dev/null +++ b/doc/man/man3/ldap_extended_operation.3 @@ -0,0 +1,75 @@ +.TH LDAP_EXTENDED_OPERATION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_extended_operation.3.links b/doc/man/man3/ldap_extended_operation.3.links new file mode 100644 index 0000000..1c5dc67 --- /dev/null +++ b/doc/man/man3/ldap_extended_operation.3.links @@ -0,0 +1,2 @@ +ldap_extended_operation_s.3 + diff --git a/doc/man/man3/ldap_first_attribute.3 b/doc/man/man3/ldap_first_attribute.3 new file mode 100644 index 0000000..47e8b0c --- /dev/null +++ b/doc/man/man3/ldap_first_attribute.3 @@ -0,0 +1,97 @@ +.TH LDAP_FIRST_ATTRIBUTE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 ) +.LP +.ft B +int ldap_get_attribute_ber( + LDAP *ld, LDAPMessage *entry, BerElement *ber, + BerValue *attr, BerVarray *vals ) +.SH DESCRIPTION +The +.BR ldap_first_attribute() , +.B ldap_next_attribute() +and +.B ldap_get_attribute_ber() +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. +.LP +The +.B ldap_get_attribute_ber() +routine allows one to iterate over all attributes in-place, without +allocating memory to hold text for the attribute name or its values, +if requested. The use case is similar to +.B ldap_next_attribute() +except that the attribute name is returned into \fIattr\fP and, if +\fIvals\fP is non-NULL, the list of values is stored there. Both point +into the LDAP message and remain valid only while the entry is valid. +The caller is still responsible for freeing \fIvals\fP with +.BR ldap_memfree (3), +if used. +.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). +For +.BR ldap_get_attribute_ber() , +only the actual \fIvals\fP pointer needs to be freed with +.BR ldap_memfree (3), +other data is accounted for as part of \fIber\fP. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_entry (3), +.BR ldap_get_values (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_first_attribute.3.links b/doc/man/man3/ldap_first_attribute.3.links new file mode 100644 index 0000000..ce3981c --- /dev/null +++ b/doc/man/man3/ldap_first_attribute.3.links @@ -0,0 +1,2 @@ +ldap_next_attribute.3 +ldap_get_attribute_ber.3 diff --git a/doc/man/man3/ldap_first_entry.3 b/doc/man/man3/ldap_first_entry.3 new file mode 100644 index 0000000..b0eadd0 --- /dev/null +++ b/doc/man/man3/ldap_first_entry.3 @@ -0,0 +1,80 @@ +.TH LDAP_FIRST_ENTRY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_first_entry.3.links b/doc/man/man3/ldap_first_entry.3.links new file mode 100644 index 0000000..781590b --- /dev/null +++ b/doc/man/man3/ldap_first_entry.3.links @@ -0,0 +1,2 @@ +ldap_next_entry.3 +ldap_count_entries.3 diff --git a/doc/man/man3/ldap_first_message.3 b/doc/man/man3/ldap_first_message.3 new file mode 100644 index 0000000..4d62359 --- /dev/null +++ b/doc/man/man3/ldap_first_message.3 @@ -0,0 +1,82 @@ +.TH LDAP_FIRST_MESSAGE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_first_message.3.links b/doc/man/man3/ldap_first_message.3.links new file mode 100644 index 0000000..420c04f --- /dev/null +++ b/doc/man/man3/ldap_first_message.3.links @@ -0,0 +1,2 @@ +ldap_next_message.3 +ldap_count_messages.3 diff --git a/doc/man/man3/ldap_first_reference.3 b/doc/man/man3/ldap_first_reference.3 new file mode 100644 index 0000000..2bcba1a --- /dev/null +++ b/doc/man/man3/ldap_first_reference.3 @@ -0,0 +1,71 @@ +.TH LDAP_FIRST_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_first_reference.3.links b/doc/man/man3/ldap_first_reference.3.links new file mode 100644 index 0000000..a747bbb --- /dev/null +++ b/doc/man/man3/ldap_first_reference.3.links @@ -0,0 +1,2 @@ +ldap_next_reference.3 +ldap_count_references.3 diff --git a/doc/man/man3/ldap_get_dn.3 b/doc/man/man3/ldap_get_dn.3 new file mode 100644 index 0000000..6e052a3 --- /dev/null +++ b/doc/man/man3/ldap_get_dn.3 @@ -0,0 +1,246 @@ +.TH LDAP_GET_DN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_get_dn.3.links b/doc/man/man3/ldap_get_dn.3.links new file mode 100644 index 0000000..4c71aa5 --- /dev/null +++ b/doc/man/man3/ldap_get_dn.3.links @@ -0,0 +1,9 @@ +ldap_explode_dn.3 +ldap_explode_rdn.3 +ldap_dn2ufn.3 +ldap_str2dn.3 +ldap_dnfree.3 +ldap_dn2str.3 +ldap_dn2dcedn.3 +ldap_dcedn2dn.3 +ldap_dn2ad_canonical.3 diff --git a/doc/man/man3/ldap_get_option.3 b/doc/man/man3/ldap_get_option.3 new file mode 100644 index 0000000..b98ad60 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3 @@ -0,0 +1,932 @@ +.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +using +.BR ldap_memfree (3)), +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_SOCKET_BIND_ADDRESSES +Sets/gets a space-separated list of IP Addresses used as binding interface +to remote server when trying to establish a connection. Only one valid IPv4 +address and/or one valid IPv6 address are allowed in the list. +.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_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 +using +.BR ldap_memfree (3)), +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. +.TP +.B LDAP_OPT_KEEPCONN +Instructs +.BR ldap_result (3) +to keep the connection open on read error or if Notice of Disconnection is received. In these cases, the connection should be closed by the caller. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_TCP_USER_TIMEOUT +Allows to configure TCP_USER_TIMEOUT in milliseconds on the connection, overriding the operating system setting. +This option is OpenLDAP specific and supported only on Linux 2.6.37 or higher. +.B invalue +must be a +.BR "const unsigned int *" ; +.BR outvalue +must be an +.BR "unsigned int *" . + +.SH SASL OPTIONS +The SASL options are OpenLDAP specific and unless otherwise noted, require an LDAP handle to be passed. +.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. This option can be used globally. +.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). +.TP +.B LDAP_OPT_X_SASL_CBINDING +Sets/gets the channel-binding type to use in SASL, +one of +.BR LDAP_OPT_X_SASL_CBINDING_NONE +(the default), +.BR LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE +the "tls-unique" type from RFC 5929. +.BR LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT +the "tls-server-end-point" from RFC 5929, compatible with Windows. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.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 +Gets the cipher being used on an established TLS session. +.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). +.TP +.B LDAP_OPT_X_TLS_ECNAME +Gets/sets the name of the curve(s) used for +elliptic curve key exchanges. +.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. In GnuTLS a curve may be selected +in the cipher suite specification. +.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_PEERCERT +Gets the peer's certificate in DER format from an established TLS session. +.BR outvalue +must be +.BR "struct berval *" , +and the data it returns needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MAX +Sets/gets the maximum protocol version. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.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. +.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_REQUIRE_SAN +Sets/gets the peer certificate subjectAlternativeName 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. +.TP +.B LDAP_OPT_X_TLS_VERSION +Gets the TLS version being used on an established TLS session. +.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_PEERKEY_HASH +Sets the (public) key that the application expects the peer to be using. +.B invalue +must be +.BR "const char *" +containing the base64 encoding of the expected peer's key or in the format +.B "<hashalg>:<peerkey hash base64 encoded>" +where as a TLS session is established, the library will hash the peer's key +with the provided hash algorithm and compare it with value provided and will +only allow the session to continue if they match. This happens regardless of +certificate checking strategy. The list of supported +.B hashalg +values depends on the crypto library used, check its documentation to get +a list. +.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 +.so ../Project diff --git a/doc/man/man3/ldap_get_option.3.links b/doc/man/man3/ldap_get_option.3.links new file mode 100644 index 0000000..9105ef0 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3.links @@ -0,0 +1 @@ +ldap_set_option.3 diff --git a/doc/man/man3/ldap_get_values.3 b/doc/man/man3/ldap_get_values.3 new file mode 100644 index 0000000..a557c53 --- /dev/null +++ b/doc/man/man3/ldap_get_values.3 @@ -0,0 +1,102 @@ +.TH LDAP_GET_VALUES 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_get_values.3.links b/doc/man/man3/ldap_get_values.3.links new file mode 100644 index 0000000..ac2b454 --- /dev/null +++ b/doc/man/man3/ldap_get_values.3.links @@ -0,0 +1,5 @@ +ldap_get_values_len.3 +ldap_value_free.3 +ldap_value_free_len.3 +ldap_count_values.3 +ldap_count_values_len.3 diff --git a/doc/man/man3/ldap_memory.3 b/doc/man/man3/ldap_memory.3 new file mode 100644 index 0000000..b3b6bb0 --- /dev/null +++ b/doc/man/man3/ldap_memory.3 @@ -0,0 +1,50 @@ +.TH LDAP_MEMORY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_memory.3.links b/doc/man/man3/ldap_memory.3.links new file mode 100644 index 0000000..9351ff1 --- /dev/null +++ b/doc/man/man3/ldap_memory.3.links @@ -0,0 +1,6 @@ +ldap_memfree.3 +ldap_memvfree.3 +ldap_memalloc.3 +ldap_memcalloc.3 +ldap_memrealloc.3 +ldap_strdup.3 diff --git a/doc/man/man3/ldap_modify.3 b/doc/man/man3/ldap_modify.3 new file mode 100644 index 0000000..9ce3d74 --- /dev/null +++ b/doc/man/man3/ldap_modify.3 @@ -0,0 +1,134 @@ +.TH LDAP_MODIFY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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; + } 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. +.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 +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/doc/man/man3/ldap_modify.3.links b/doc/man/man3/ldap_modify.3.links new file mode 100644 index 0000000..81c6f2a --- /dev/null +++ b/doc/man/man3/ldap_modify.3.links @@ -0,0 +1,4 @@ +ldap_modify_s.3 +ldap_modify_ext.3 +ldap_modify_ext_s.3 +ldap_mods_free.3 diff --git a/doc/man/man3/ldap_modrdn.3 b/doc/man/man3/ldap_modrdn.3 new file mode 100644 index 0000000..3b2e77a --- /dev/null +++ b/doc/man/man3/ldap_modrdn.3 @@ -0,0 +1,81 @@ +.TH LDAP_MODRDN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_modrdn.3.links b/doc/man/man3/ldap_modrdn.3.links new file mode 100644 index 0000000..86063e2 --- /dev/null +++ b/doc/man/man3/ldap_modrdn.3.links @@ -0,0 +1,3 @@ +ldap_modrdn_s.3 +ldap_modrdn2.3 +ldap_modrdn2_s.3 diff --git a/doc/man/man3/ldap_open.3 b/doc/man/man3/ldap_open.3 new file mode 100644 index 0000000..994032c --- /dev/null +++ b/doc/man/man3/ldap_open.3 @@ -0,0 +1,236 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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_connect(ldp) +.ft +LDAP *ldp; +.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 <openldap.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_connect() +causes a handle created by +.B ldap_initialize() +to connect to the server. This is useful in situations where a file +descriptor is required before a request is performed. +.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 +.so ../Project diff --git a/doc/man/man3/ldap_open.3.links b/doc/man/man3/ldap_open.3.links new file mode 100644 index 0000000..aa34ab7 --- /dev/null +++ b/doc/man/man3/ldap_open.3.links @@ -0,0 +1,4 @@ +ldap_init.3 +ldap_initialize.3 +ldap_set_urllist_proc.3 +ldap_init_fd.3 diff --git a/doc/man/man3/ldap_parse_reference.3 b/doc/man/man3/ldap_parse_reference.3 new file mode 100644 index 0000000..21fd733 --- /dev/null +++ b/doc/man/man3/ldap_parse_reference.3 @@ -0,0 +1,61 @@ +.TH LDAP_PARSE_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_parse_result.3 b/doc/man/man3/ldap_parse_result.3 new file mode 100644 index 0000000..82c7710 --- /dev/null +++ b/doc/man/man3/ldap_parse_result.3 @@ -0,0 +1,114 @@ +.TH LDAP_PARSE_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 ) +.LP +.ft B +int ldap_parse_intermediate( LDAP *ld, LDAPMessage *result, + char **retoidp, struct berval **retdatap, + LDAPControl ***serverctrlsp, 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. To extract information from intermediate responses, +.B ldap_parse_intermediate() +can be used. +.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 and intermediate responses, 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 and intermediate responses, 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 +.so ../Project diff --git a/doc/man/man3/ldap_parse_result.3.links b/doc/man/man3/ldap_parse_result.3.links new file mode 100644 index 0000000..e2f4755 --- /dev/null +++ b/doc/man/man3/ldap_parse_result.3.links @@ -0,0 +1,3 @@ +ldap_parse_sasl_bind_result.3 +ldap_parse_extended_result.3 +ldap_parse_intermediate.3 diff --git a/doc/man/man3/ldap_parse_sort_control.3 b/doc/man/man3/ldap_parse_sort_control.3 new file mode 100644 index 0000000..56bf021 --- /dev/null +++ b/doc/man/man3/ldap_parse_sort_control.3 @@ -0,0 +1,40 @@ +.TH LDAP_PARSE_SORT-CONTROL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_parse_vlv_control.3 b/doc/man/man3/ldap_parse_vlv_control.3 new file mode 100644 index 0000000..be9efae --- /dev/null +++ b/doc/man/man3/ldap_parse_vlv_control.3 @@ -0,0 +1,49 @@ +.TH LDAP_PARSE_VLV_CONTROL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_rename.3 b/doc/man/man3/ldap_rename.3 new file mode 100644 index 0000000..497be46 --- /dev/null +++ b/doc/man/man3/ldap_rename.3 @@ -0,0 +1,66 @@ +.TH LDAP_RENAME 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_rename.3.links b/doc/man/man3/ldap_rename.3.links new file mode 100644 index 0000000..3281906 --- /dev/null +++ b/doc/man/man3/ldap_rename.3.links @@ -0,0 +1 @@ +ldap_rename_s.3 diff --git a/doc/man/man3/ldap_result.3 b/doc/man/man3/ldap_result.3 new file mode 100644 index 0000000..27f0805 --- /dev/null +++ b/doc/man/man3/ldap_result.3 @@ -0,0 +1,136 @@ +.TH LDAP_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_result.3.links b/doc/man/man3/ldap_result.3.links new file mode 100644 index 0000000..1394c6c --- /dev/null +++ b/doc/man/man3/ldap_result.3.links @@ -0,0 +1,3 @@ +ldap_msgfree.3 +ldap_msgtype.3 +ldap_msgid.3 diff --git a/doc/man/man3/ldap_schema.3 b/doc/man/man3/ldap_schema.3 new file mode 100644 index 0000000..1cae152 --- /dev/null +++ b/doc/man/man3/ldap_schema.3 @@ -0,0 +1,320 @@ +.TH LDAP_SCHEMA 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2000-2022 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 provide 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 provide 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 +.so ../Project diff --git a/doc/man/man3/ldap_schema.3.links b/doc/man/man3/ldap_schema.3.links new file mode 100644 index 0000000..05e1675 --- /dev/null +++ b/doc/man/man3/ldap_schema.3.links @@ -0,0 +1,17 @@ +ldap_str2syntax.3 +ldap_syntax2str.3 +ldap_syntax2name.3 +ldap_syntax_free.3 +ldap_str2matchingrule.3 +ldap_matchingrule2str.3 +ldap_matchingrule2name.3 +ldap_matchingrule_free.3 +ldap_str2attributetype.3 +ldap_attributetype2str.3 +ldap_attributetype2name.3 +ldap_attributetype_free.3 +ldap_str2objectclass.3 +ldap_objectclass2str.3 +ldap_objectclass2name.3 +ldap_objectclass_free.3 +ldap_scherr2str.3 diff --git a/doc/man/man3/ldap_search.3 b/doc/man/man3/ldap_search.3 new file mode 100644 index 0000000..dc58b6d --- /dev/null +++ b/doc/man/man3/ldap_search.3 @@ -0,0 +1,144 @@ +.TH LDAP_SEARCH 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_search.3.links b/doc/man/man3/ldap_search.3.links new file mode 100644 index 0000000..d85bf81 --- /dev/null +++ b/doc/man/man3/ldap_search.3.links @@ -0,0 +1,4 @@ +ldap_search_s.3 +ldap_search_st.3 +ldap_search_ext.3 +ldap_search_ext_s.3 diff --git a/doc/man/man3/ldap_sort.3 b/doc/man/man3/ldap_sort.3 new file mode 100644 index 0000000..75fe54c --- /dev/null +++ b/doc/man/man3/ldap_sort.3 @@ -0,0 +1,21 @@ +.TH LDAP_SORT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so Deprecated +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_sort.3.links b/doc/man/man3/ldap_sort.3.links new file mode 100644 index 0000000..7a4be53 --- /dev/null +++ b/doc/man/man3/ldap_sort.3.links @@ -0,0 +1,3 @@ +ldap_sort_entries.3 +ldap_sort_values.3 +ldap_sort_strcasecmp.3 diff --git a/doc/man/man3/ldap_sync.3 b/doc/man/man3/ldap_sync.3 new file mode 100644 index 0000000..8fb77f5 --- /dev/null +++ b/doc/man/man3/ldap_sync.3 @@ -0,0 +1,326 @@ +.TH LDAP_SYNC 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2006-2022 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. diff --git a/doc/man/man3/ldap_tls.3 b/doc/man/man3/ldap_tls.3 new file mode 100644 index 0000000..4170d42 --- /dev/null +++ b/doc/man/man3/ldap_tls.3 @@ -0,0 +1,41 @@ +.TH LDAP_TLS 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_tls.3.links b/doc/man/man3/ldap_tls.3.links new file mode 100644 index 0000000..d03e2bf --- /dev/null +++ b/doc/man/man3/ldap_tls.3.links @@ -0,0 +1,4 @@ +ldap_start_tls.3 +ldap_start_tls_s.3 +ldap_tls_inplace.3 +ldap_install_tls.3 diff --git a/doc/man/man3/ldap_url.3 b/doc/man/man3/ldap_url.3 new file mode 100644 index 0000000..ec7f343 --- /dev/null +++ b/doc/man/man3/ldap_url.3 @@ -0,0 +1,83 @@ +.TH LDAP_URL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 +.so ../Project diff --git a/doc/man/man3/ldap_url.3.links b/doc/man/man3/ldap_url.3.links new file mode 100644 index 0000000..90fe023 --- /dev/null +++ b/doc/man/man3/ldap_url.3.links @@ -0,0 +1,3 @@ +ldap_is_ldap_url.3 +ldap_url_parse.3 +ldap_free_urldesc.3 |