From: Pierangelo Masarati Date: Fri, 3 Mar 2006 09:47:12 +0000 (+0000) Subject: add ldap_initialize(); trim description of LDAP structure (now opaque) X-Git-Tag: OPENLDAP_REL_ENG_2_4_BP~153 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=9d697d50f03b418a09bdf6a9395a5af28b24f92f;p=openldap add ldap_initialize(); trim description of LDAP structure (now opaque) --- diff --git a/doc/man/man3/ldap_open.3 b/doc/man/man3/ldap_open.3 index 9cc34aef4b..6f9a720d80 100644 --- a/doc/man/man3/ldap_open.3 +++ b/doc/man/man3/ldap_open.3 @@ -3,7 +3,7 @@ .\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME -ldap_init, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server +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 @@ -22,6 +22,12 @@ LDAP *ldap_init(host, port) .ft char *host; int port; +.LP +.ft B +int ldap_initialize(ldp, uri) +.ft +LDAP **ldp; +char *uri; .SH DESCRIPTION .LP .B ldap_open() @@ -29,8 +35,10 @@ 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. One -of these two routines must be called before any operations are attempted. +of these three routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is @@ -44,38 +52,17 @@ parameter to Upon successfully making a connection to an LDAP server, .B ldap_open() -returns a pointer to an LDAP structure (defined below), which -should be passed to subsequent calls to +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. See -for more details. -.LP -.nf -.ft tt - typedef struct ldap { - /* ... other stuff you should not mess with ... */ - char ld_lberoptions; - int ld_deref; - #define LDAP_DEREF_NEVER 0 - #define LDAP_DEREF_SEARCHING 1 - #define LDAP_DEREF_FINDING 2 - #define LDAP_DEREF_ALWAYS 3 - int ld_timelimit; - int ld_sizelimit; - #define LDAP_NO_LIMIT 0 - int ld_errno; - char *ld_error; - char *ld_matched; - int ld_refhoplimit; - unsigned long ld_options; - #define LDAP_OPT_REFERRALS 0x00000002 /* set by default */ - #define LDAP_OPT_RESTART 0x00000004 - /* ... other stuff you should not mess with ... */ - } LDAP; -.ft -.fi +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() @@ -83,37 +70,39 @@ 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. At this time, -.B ldap_init() -is preferred. -.B ldap_open() will be depreciated in a later release. -.SH ERRORS -If an error occurs, these routines will return NULL and errno should be -set appropriately. -.SH OPTIONS -Options that affect a particular LDAP instance may be set by modifying -the \fIld_options\fP field in the LDAP structure. This field is set -to \fILDAP_OPT_REFERRALS\fP in -.B ldap_open() and -.B ldap_init(), -which causes the library to automatically follow referrals -to other servers that may be returned in response to an LDAP operation. +first operation is attempted. .LP -The other supported option is \fILDAP_OPT_RESTART\fP, which if set will -cause the LDAP library to restart the -.BR select (2) -system call when it is interrupted by the system (i.e., errno is set to -EINTR). This option is not supported on the Macintosh and under MS-DOS. +.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. .LP -An option can be turned off by clearing the appropriate bit in the -\fIld_options\fP field. -.SH NOTES -There are other elements in the LDAP structure that you should not -change. You should not make any assumptions about the order of elements -in the LDAP structure. +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. +.SH ERRORS +If an error occurs, +.B ldap_open() +and +.B ldap_init() +will return NULL and errno should be set appropriately. +.B ldap_initialize() +will directly return the LDAP code associated to the error (or +.I LDAP_SUCCESS +in case of success); +errno should be set as well whenever appropriate. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), +.BR ldap_get_option (3), +.BR ldap_set_option (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .B OpenLDAP diff --git a/doc/man/man3/ldap_open.3.links b/doc/man/man3/ldap_open.3.links index 163bb14cca..d2f912c0b2 100644 --- a/doc/man/man3/ldap_open.3.links +++ b/doc/man/man3/ldap_open.3.links @@ -1 +1,2 @@ ldap_init.3 +ldap_initialize.3