ldap_open(3) - NetBSD Manual Pages

LDAP_OPEN(3)                                                      LDAP_OPEN(3)




NAME

       ldap_init, ldap_initialize, ldap_open - Initialize the LDAP library and
       open a connection to an LDAP server


LIBRARY

       OpenLDAP LDAP (libldap, -lldap)


SYNOPSIS

       #include <ldap.h>

       LDAP *ldap_open(host, port)
       char *host;
       int port;

       LDAP *ldap_init(host, port)
       char *host;
       int port;

       int ldap_initialize(ldp, uri)
       LDAP **ldp;
       char *uri;

       #include <ldap_pvt.h>

       int ldap_init_fd(fd, proto, uri, ldp)
       ber_socket_t fd;
       int proto;
       char *uri;
       LDAP **ldp;


DESCRIPTION

       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.  ldap_init() allocates an  LDAP  structure  but
       does  not  open  an initial connection.  ldap_initialize() allocates an
       LDAP structure but does not open an initial connection.  ldap_init_fd()
       allocates  an  LDAP  structure using an existing connection on the pro-
       vided socket.  One of these routines must be called before  any  opera-
       tions are attempted.

       ldap_open()  takes  host, the hostname on which the LDAP server is run-
       ning, and port, the port number to which to connect.   If  the  default
       IANA-assigned port of 389 is desired, LDAP_PORT should be specified for
       port.  The host parameter may contain a blank-separated list  of  hosts
       to  try  to  connect  to,  and  each host may optionally by of the form
       host:port.  If present, the  :port  overrides  the  port  parameter  to
       ldap_open().   Upon successfully making a connection to an LDAP server,
       ldap_open() returns a pointer to an opaque LDAP structure, which should
       be  passed to subsequent calls to ldap_bind(), ldap_search(), etc. Cer-
       tain 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  ldap_get_option(3)
       and ldap_set_option(3) respectively, whenever possible.

       ldap_init()  acts just like ldap_open(), but does not open a connection
       to the LDAP server.  The actual connection open  will  occur  when  the
       first operation is attempted.

       ldap_initialize()  acts  like  ldap_init(),  but  it returns an integer
       indicating either success or the failure reason, and it allows to spec-
       ify details for the connection in the schema portion of the URI.

       At  this  time,  ldap_open() and ldap_init() are deprecated in favor of
       ldap_initialize(), essentially because the latter allows to  specify  a
       schema in the URI and it explicitly returns an error code.

       ldap_init_fd()  allows  an  LDAP  structure  to be initialized using an
       already-opened  connection.  The  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 uri parameter may optionally be
       provided for informational purposes.

       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 ldap_get_option() or ldap_set_option() be used
       in the program's main thread before any additional threads are created.
       See ldap_get_option(3).



ERRORS

       If  an  error  occurs, ldap_open() and ldap_init() will return NULL and
       errno   should   be   set   appropriately.     ldap_initialize()    and
       ldap_init_fd()  will  directly  return  the LDAP code associated to the
       error (or LDAP_SUCCESS in case of success); errno should be set as well
       whenever appropriate.


SEE ALSO

       ldap(3),  ldap_bind(3),  ldap_get_option(3),  ldap_set_option(3), lber-
       sockbuf(3), errno(3)


ACKNOWLEDGEMENTS

       OpenLDAP Software is developed and maintained by The  OpenLDAP  Project
       <http://www.openldap.org/>.   OpenLDAP Software is derived from Univer-
       sity of Michigan LDAP 3.3 Release.



OpenLDAP 2.4.11                   2008/07/16                      LDAP_OPEN(3)