ldap_init()

Purpose

Create and initialize an LDAP handle for an SSL or non-SSL connection

Format

#include <ldap.h> 

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

Parameters

Input

host: Specifies the location of the LDAP server as a null-terminated string in the local EBCDIC code page or UTF-8, as determined by the LDAP_LIBASCII compiler variable. This location can be a blank-separated host list or a single LDAP URL. Specify NULL for this parameter to connect to an LDAP server on the local system using the IPv4 loopback address (127.0.0.1).
port: Specifies the port for the LDAP server when an explicit port is not specified in the host list. The value must be between 1 and 65535. Specify 0 to use the default LDAP port (389).

Usage

The ldap_init() routine creates and initializes an LDAP handle. The routine does not establish a connection with the LDAP server. A connection is established when the first server request using the handle is issued. The handle is initialized for a non-SSL connection unless an LDAP URL is specified for the host parameter and the URL scheme is ldaps instead of ldap. The application should call the ldap_unbind() or ldap_unbind_s() routine to release the handle when it is no longer needed. The location of the LDAP server can be explicitly specified by using a host list or an LDAP URL containing a host name. The location of the LDAP server can be implicitly specified by using an LDAP URL that does not contain a host name.

A host list consists of one or more blank-separated host:port values. The host specification is a DNS resource name (for example, dcesec4.endicott.ibm.com), a dotted decimal IPv4 address (for example, 9.130.25.34), or a colon-separated IPv6 address enclosed in square brackets (for example, [1080::8:800:200C:417A]. The port, if specified, must be a decimal number between 1 and 65535. The value of the port parameter can be used if a port is not specified. The hosts are tried in the order specified until a connection is established with an LDAP server.

An LDAP URL has the following format:

[<][URL:]scheme://[host[:port]][/dn[?attributes[?scope[?filter]]]][>]

where:

scheme: Specifies the value ldap for a non-SSL connection and ldaps for an SSL connection.
host:port: Specifies the location of the LDAP server. The host specification can be a DNS resource name (for example, dcesec4.endicott.ibm.com), a dotted decimal IPv4 address (for example, 9.130.25.34), or a colon-separated IPv6 address enclosed in square brackets (for example, [1080::8:800:200C:417A]). The port, if specified, must be a decimal number between 1 and 65535. The port defaults to 389 for a non-SSL connection and 636 for an SSL connection.
dn: Specifies the distinguished name (DN) for the request. The DN can be used as a filter when the ldap_server_locate() routine should be called to locate the LDAP server.
attributes: Consists of one or more comma-separated search attributes. This value is not used by the ldap_init() routine.
scope: Specifies the search scope and can be "base", "one", or "sub". This value is not used by the ldap_init() routine.
filter: Specifies the search filter. This value is not used by the ldap_init() routine.

The URL can be optionally enclosed in angle brackets or prefixed with URL: or both.

The ldap_init() routine calls the ldap_server_locate() routine to locate the LDAP server when the LDAP URL does not contain a host name. The default server information file /etc/ldap/ldap_server_info.conf can be used unless the LDAP_SERVER_INFO_CONF environment variable is defined. The ldap_server_locate() routine uses the default values for everything except the DN filter. The DN filter is set to the DN specified in the URL. (No DN filtering is done if a DN is not specified in the URL.) The scheme specified in the URL can be used to select servers from the list returned by the ldap_server_locate() routine. A server entry is selected if the scheme is ldap and the security type is LDAP_LSI_NOSSL or if the scheme is ldaps and the security type is LDAP_LSI_SSL. A server entry is not selected if the security type is not defined.

The ldap_ssl_client_init() routine must be called before the ldap_init() routine if the LDAP URL specifies an SSL connection.

The LDAP handle is initialized with the following default values. The ldap_set_option() or ldap_set_option_np() routine can be called to set different values upon completion of the ldap_init() routine.

The LDAP protocol version is set based on the LDAP_VERSION environment variable. If the LDAP_VERSION environment variable is not defined, the protocol version is set to 3.
The LDAP version 2 wire format is set based on the LDAP_V2_WIRE_FORMAT environment variable. If the LDAP_V2_WIRE_FORMAT environment variable is not defined, the LDAP version 2 wire format is set to UTF-8.
Referral processing is enabled and the referral hop limit is set to 10.

Function return value

The function return value is the new LDAP handle if no error is detected. Otherwise, the return value is NULL.