--- name: "ldap_initialize" section: "3" platform: "linux" package: "libldap" version: "2.7.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/ldap_open" --- # ldap\_initialize(3) Initialize the LDAP library and open a connection to an LDAP server Part of [ldap\_open(3)](/ldap_open/3.md). ## 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 \*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\_connect(ldp)** **LDAP \*ldp;** **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 \** **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 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. 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)](/ldap_get_option/3.md) **and** [**ldap\_set\_option**(3)](/ldap_set_option/3.md) **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 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\_connect()** **causes a handle created by** **ldap\_initialize()** **to connect to the server. This is useful in situations where a file** **descriptor is required before a request is performed.** **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.** **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 handle** **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)](/ldap_get_option/3.md). ## 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.** **ldap\_set\_urllist\_proc()** **returns LDAP\_OPT\_ERROR on error, and LDAP\_OPT\_SUCCESS on success.** ## SEE ALSO [**ldap**(3)](/ldap/3.md), [**ldap\_bind**(3)](/ldap_bind/3.md), [**ldap\_get\_option**(3)](/ldap_get_option/3.md), [**ldap\_set\_option**(3)](/ldap_set_option/3.md), [**lber-sockbuf**(3)](/lber-sockbuf/3.md), [**errno**(3)](/errno/3.md) ## ACKNOWLEDGEMENTS **OpenLDAP Software** **is developed and maintained by The OpenLDAP Project \.** **OpenLDAP Software** **is derived from the University of Michigan LDAP 3.3 Release.**