<!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_open()--Perform an LDAP Open 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_open()--Perform an LDAP Open Operation</h2> <br> <div class="box" style="width: 60%;"> <br> Syntax<br> <pre> #include <ldap.h> LDAP *ldap_open( 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_open()</strong> 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.</p> <p>The <strong>ldap_open()</strong> function returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP functions such as <a href="ldap_bind.htm">ldap_bind()</a> and <a href="ldap_search.htm"> ldap_search()</a>.</p> <p>Although still supported, the use of <strong>ldap_open()</strong> is deprecated. The <strong>ldap_open()</strong> API allocates an LDAP structure and opens a connection to the LDAP server. Use of <a href="ldap_init.htm"> ldap_init()</a> instead of <strong>ldap_open()</strong> is recommended.</p> <p>As a rule of thumb, the LDAP application is typically running as LDAP version 2 when it uses <strong>ldap_open()</strong> to create the LDAP connection. The LDAP application is typically running as LDAP version 3 when it uses <strong>ldap_init()</strong> to create the LDAP connection. However, it was possible with the LDAP V2 API to call <strong>ldap_init()</strong> so that there may be cases where this rule of thumb is not true.</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_open ("server1", ldap_port); ld=ldap_open ("server2:1200", ldap_port); ld=ldap_open ("server1:800 server2:2000 server3", ldap_port); </pre> <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> </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_open ("ldap://", ldap_port); ld=ldap_open (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_open ("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_open ("ldap://myserver", LDAP_PORT); ld=ldap_open ("myserver", LDAP_PORT); </pre> <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_open ("/tmp/s.slapd", ldap_port); </pre> <br> </td> </tr> <tr> <td valign="top"><em>Host with Privileged Port</em></td> <td valign="top">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.<br> <br> <p>For example:</p> <pre> 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); </pre> </td> </tr> </table> <br> </dd> <dt><strong>port</strong></dt> <dd>(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.</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.<br> <br> </dd> </dl> <br> <h3>Error Conditions</h3> <p>The <strong>ldap_open()</strong> API will return NULL and set the <em> ld_errno</em> error code, if not successful. See <a href= "ldap_error_condt.htm">LDAP Client API Error Conditions</a> for possible LDAP error codes values.</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_open API.</td> </tr> </table> <br> <br> <h3>Related Information</h3> <ul> <li><a href="ldap_init.htm">ldap_init()</a> -- Initializes a session with an LDAP server.</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> <table align="center" 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> </body> </html>