ldap_open()--Perform an LDAP Open Operation

 #include <ldap.h>

 LDAP *ldap_open(
                char  *host,
                int    port)

The ldap_open() function 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.

The ldap_open() function returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP functions such as ldap_bind() and ldap_search().

Although still supported, the use of ldap_open() is deprecated. The ldap_open() API allocates an LDAP structure and opens a connection to the LDAP server. Use of ldap_init() instead of ldap_open() is recommended.

As a rule of thumb, the LDAP application is typically running as LDAP version 2 when it uses ldap_open() to create the LDAP connection. The LDAP application is typically running as LDAP version 3 when it uses ldap_init() to create the LDAP connection. However, it was possible with the LDAP V2 API to call ldap_init() so that there may be cases where this rule of thumb is not true.

Authorities and Locks

No i5/OS authority is required.

Parameters

host

(Input) Several methods are supported for specifying one or more target LDAP servers, including the following:

Explicit Host List	Specifies the name of the host on which the LDAP server is running. The host parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If present, the :port overrides the port parameter. The following are typical examples: ld=ldap_open ("server1", ldap_port); ld=ldap_open ("server2:1200", ldap_port); ld=ldap_open ("server1:800 server2:2000 server3", ldap_port);
Localhost	If the host parameter is NULL, the LDAP server will be assumed to be running on the local host.
Default Hosts	If the host parameter is set to LDAP_URL_PREFIX ("ldap://") the LDAP library will attempt to locate one or more default LDAP servers, with non-SSL ports, using the SecureWay ldap_server_locate() function. The port specified on the call is ignored, since ldap_server_locate() returns the port. For example, the following two are equivalent: ld=ldap_open ("ldap://", ldap_port); ld=ldap_open (LDAP_URL_PREFIX, LDAP_PORT); If more than one default server is located, the list is processed in sequence, until an active server is found. The LDAP URL can include a Distinguished Name (DN), used as a filter for selecting candidate LDAP servers based on the server's suffix (or suffixes). If the most significant portion of the DN is an exact match with a server's suffix (after normalizing for case), the server is added to the list of candidate servers. For example, the following will only return default LDAP servers that have a suffix that supports the specified DN: ld=ldap_open ("ldap:///cn=fred, dc=austin, dc=ibm, dc=com", LDAP_PORT); In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" would match. If more than one default server is located, the list is processed in sequence, until an active server is found. If the LDAP URL contains a host name and optional port, the host is used to create the connection. No attempt is made to locate the default server(s), and the DN, if present, is ignored. For example, the following two are equivalent: ld=ldap_open ("ldap://myserver", LDAP_PORT); ld=ldap_open ("myserver", LDAP_PORT);
Local Socket	If the host parameter is prefixed with "/", the host parameter is assumed to be the name of a UNIX socket (that is, socket family is AF_UNIX) and port is ignored. Use of a UNIX socket requires the LDAP server to be running on the local host. In addition, the LDAP server must be listening on the specified UNIX socket. The i5/OS Secureway Directory Services server listens on the /tmp/s.slapd local socket, in addition to any configured TCP/IP ports. For example: ld=ldap_open ("/tmp/s.slapd", ldap_port);
Host with Privileged Port	If a specified host is prefixed with "privport://", then the LDAP library will use the rresvport() function to attempt to obtain one of the reserved ports (512 through 1023), instead of an "ephemeral" port. The search for a reserved port starts at 1023 and stops at 512. If a reserved port cannot be obtained, the function call will fail. For example: ld=ldap_open ("privport://server1,ldap_port"); ld=ldap_open ("privport://server2:1200", ldap_port); ld=ldap_open ("privport://server1:800 server2:2000 privport://server3", ldap_port);

port

(Input) Specifies the TCP port number the server is listening on. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified. To use the default SSL port 636 for SSL connections, use LDAPS_PORT.

Return Value

Pointer to an LDAP structure

if the request was successful.

NULL

if the request was not successful.

Error Conditions

The ldap_open() API will return NULL and set the ld_errno error code, if not successful. See LDAP Client API Error Conditions for possible LDAP error codes values.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_init() -- Initializes a session with an LDAP server.
• ldap_set_option() -- Set an option associated with an LDAP descriptor.
• ldap_get_option() -- Get an option associated with an LDAP descriptor.
• ldap_version() -- Obtain LDAP version and SSL cipher information.