<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>ldap_init()--Perform an LDAP Initialization Operation</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- File Edited March 2001 --> <!-- This file has undergone html cleanup on 2/19/02 by JET --> <!-- End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <a name="Top_Of_Page"></a> <h2>ldap_init()--Perform an LDAP Initialization Operation</h2> <div class="box" style="width: 70%;"> <br> Syntax<br> <pre> #include <ldap.h> LDAP *ldap_init( char *<em>host</em>, int <em>port</em>) </pre> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Library Name/Service Program: QSYS/QGLDCLNT<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>ldap_init()</strong> API is used to allocate an LDAP structure, which is used to identify the connection and to maintain per-connection information.</p> <p>The <strong>ldap_init()</strong> API 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().</p> <p><strong>ldap_init()</strong> initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization, but before actually contacting the host. It allocates an LDAP structure which is used to identify the connection and maintain per-connection information. Although still supported, the use of <a href="ldap_open.htm">ldap_open()</a> is deprecated. Use of <strong>ldap_init()</strong> instead of <a href="ldap_open.htm"> ldap_open()</a> is recommended.</p> <br> <h3>Authorities and Locks</h3> <p>No i5/OS authority is required.</p> <br> <h3>Parameters</h3> <dl> <dt><strong>host</strong></dt> <dd>(Input) Several methods are supported for specifying one or more target LDAP servers, including the following:<br> <br> <table> <tr> <td width="15%" valign="top"><em>Explicit Host List</em></td> <td width="85%" valign="top">Specifies the name of the host on which the LDAP server is running. The <em>host</em> parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form <em>host:port</em>. If present, the <em>:port</em> overrides the <em>port</em> parameter.<br> <br> The following are typical examples:<br> <br> <pre> ld=ldap_init ("server1", ldap_port); ld=ldap_init ("server2:1200", ldap_port); ld=ldap_init ("server1:800 server2:2000 server3", ldap_port); </pre> <br> <br> </td> </tr> <tr> <td valign="top"><em>Localhost</em></td> <td valign="top">If the <em>host</em> parameter is <strong>NULL</strong>, the LDAP server will be assumed to be running on the local host.<br> <br> <br> </td> </tr> <tr> <td valign="top"><em>Default Hosts</em></td> <td valign="top">If the <em>host</em> parameter is set to <strong> LDAP_URL_PREFIX</strong> ("ldap://") the LDAP library will attempt to locate one or more default LDAP servers, with non-SSL ports, using the SecureWay <a href="ldap_server_locate.htm">ldap_server_locate()</a> function. The port specified on the call is ignored, since <strong>ldap_server_locate()</strong> returns the port.<br> <br> <p>For example, the following two are equivalent:</p> <pre> ld=ldap_init ("ldap://", ldap_port); ld=ldap_init (LDAP_URL_PREFIX, LDAP_PORT); </pre> <br> <p>If more than one default server is located, the list is processed in sequence, until an active server is found.</p> <p>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:</p> <pre> ld=ldap_init ("ldap:///cn=fred, dc=austin, dc=ibm, dc=com", LDAP_PORT); </pre> <br> <p>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.</p> <p>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.</p> <p>For example, the following two are equivalent:</p> <pre> ld=ldap_init ("ldap://myserver", LDAP_PORT); ld=ldap_init ("myserver", LDAP_PORT); </pre> <br> <br> </td> </tr> <tr> <td valign="top"><em>Local Socket</em></td> <td valign="top">If the <em>host</em> parameter is prefixed with "/", the <em> host</em> parameter is assumed to be the name of a UNIX socket (that is, socket family is AF_UNIX) and <em>port</em> 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 <strong>/tmp/s.slapd</strong> local socket, in addition to any configured TCP/IP ports.<br> <br> <p>For example:</p> <pre> ld=ldap_init ("/tmp/s.slapd", ldap_port); </pre> <br> <br> </td> </tr> </table> <br> </dd> <dt><strong>port</strong></dt> <dd>Specifies the port number to which to connect. If the default IANA-assigned port of 389 is desired, <strong>LDAP_PORT</strong> should be specified.</dd> </dl> <br> <br> <h3>Return Value</h3> <dl> <dt><strong>Pointer to an LDAP structure</strong></dt> <dd>if the request was successful.<br> <br> </dd> <dt><strong>NULL</strong></dt> <dd>if the request was not successful.</dd> </dl> <br> <h3>Error Conditions</h3> <p>The <strong>ldap_init()</strong> API will return NULL if not successful.</p> <br> <h3>Error Messages</h3> <p>The following message may be sent from this function.</p> <table width="100%" cellpadding="3"> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td width="15%" valign="top">CPF3CF2 E</td> <td width="85%" valign="top">Error(s) occurred during running of ldap_init API.</td> </tr> </table> <br> <br> <h3>Related Information</h3> <ul> <li><a href="ldap_open.htm">ldap_open()</a> -- Open a connection to an LDAP server (deprecated).</li> <li><a href="ldap_ssl_init.htm">ldap_ssl_init()</a> -- Initializes an SSL Connection</li> <li><a href="ldap_set_option.htm">ldap_set_option()</a> -- Set an option associated with an LDAP descriptor.</li> <li><a href="ldap_get_option.htm">ldap_get_option()</a> -- Get an option associated with an LDAP descriptor.</li> <li><a href="ldap_version.htm">ldap_version()</a> -- Obtain LDAP version and SSL cipher information.</li> </ul> <hr> API introduced: V4R3 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "dirserv1.htm">LDAP APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>