322 lines
9.0 KiB
HTML
322 lines
9.0 KiB
HTML
<!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>
|
|
|