Mac Developer Library Developer
Search

 

This manual page is part of Xcode Tools version 5.0

To obtain these tools:

If you are running a version of Xcode Tools other than 5.0, view the documentation locally:

  • In Xcode

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



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;

       int ldap_set_urllist_proc(ld, proc, params)
       LDAP *ld;
       LDAP_URLLIST_PROC *proc;
       void *params;

       int (LDAP_URLLIST_PROC)(ld, urllist, url, params);
       LDAP *ld;
       LDAPURLDesc **urllist;
       LDAPURLDesc **url;
       void *params;

       #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 provided socket.  One of these routines must be called before  any  operations  are
       attempted.

       ldap_open()  takes  host, the hostname on which the LDAP server is running, and port, the port number
       to which to connect.  If the default IANA-assigned port of 389 is desired, LDAP_PORT should be speci-fied specified
       fied  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.  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 ldap_get_option(3) and ldap_set_option(3) respectively, whenever possi-ble. possible.
       ble.

       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 specify details for the connection in the schema portion of the URI.
       The  uri  parameter  may be a comma- or whitespace-separated list of URIs containing only the schema,
       the host, and the port fields.  Apart from ldap, other (non-standard) recognized values of the schema
       field  are  ldaps  (LDAP over TLS), ldapi (LDAP over IPC), and cldap (connectionless LDAP).  If other
       fields are present, the behavior is undefined.

       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 infor-mational informational
       mational purposes.

       ldap_set_urllist_proc() allows to set a function proc of type LDAP_URLLIST_PROC that is called when a
       successful  connection  can  be established.  This function receives the list of URIs parsed from the
       uri string originally passed to 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  han-dle handle
       dle  will  try  it  first.  If ld is null, proc is set as a global parameter that is inherited by all
       handlers within the process that are created after the call to ldap_set_urllist_proc().  By  default,
       no  LDAP_URLLIST_PROC is set.  In a multithreaded environment, 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 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 appropri-ately. appropriately.
       ately.  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.
       ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success.

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 University of Michigan LDAP 3.3 Release.



OpenLDAP 2.4.28                                  2011/11/24                                     LDAP_OPEN(3)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback