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. SpecifyNULL
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
and65535
. Specify0
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.
[<][URL:]scheme://[host[:port]][/dn[?attributes[?scope[?filter]]]][>]
where:- scheme
- Specifies the value
ldap
for a non-SSL connection andldaps
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 between1
and65535
. The port defaults to389
for a non-SSL connection and636
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.
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 protocol version is set based on the
LDAP_VERSION
environment variable. If theLDAP_VERSION
environment variable is not defined, the protocol version is set to3
. - The LDAP version 2 wire format is set based on the
LDAP_V2_WIRE_FORMAT
environment variable. If theLDAP_V2_WIRE_FORMAT
environment variable is not defined, the LDAP version 2 wire format is set toUTF-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
.