mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
154 lines
4.1 KiB
Groff
154 lines
4.1 KiB
Groff
.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server
|
|
.SH LIBRARY
|
|
OpenLDAP LDAP (libldap, -lldap)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <ldap.h>
|
|
.LP
|
|
.ft B
|
|
LDAP *ldap_open(host, port)
|
|
.ft
|
|
char *host;
|
|
int port;
|
|
.LP
|
|
.ft B
|
|
LDAP *ldap_init(host, port)
|
|
.ft
|
|
char *host;
|
|
int port;
|
|
.LP
|
|
.ft B
|
|
int ldap_initialize(ldp, uri)
|
|
.ft
|
|
LDAP **ldp;
|
|
char *uri;
|
|
.LP
|
|
.ft B
|
|
#include <ldap_pvt.h>
|
|
.LP
|
|
.ft B
|
|
int ldap_init_fd(fd, proto, uri, ldp)
|
|
.ft
|
|
ber_socket_t fd;
|
|
int proto;
|
|
char *uri;
|
|
LDAP **ldp;
|
|
.SH DESCRIPTION
|
|
.LP
|
|
.B ldap_open()
|
|
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.
|
|
.B ldap_init()
|
|
allocates an LDAP structure but does not open an initial connection.
|
|
.B ldap_initialize()
|
|
allocates an LDAP structure but does not open an initial connection.
|
|
.B ldap_init_fd()
|
|
allocates an LDAP structure using an existing connection on the
|
|
provided socket.
|
|
One
|
|
of these routines must be called before any operations are attempted.
|
|
.LP
|
|
.B ldap_open()
|
|
takes \fIhost\fP, the hostname on which the LDAP server is
|
|
running, and \fIport\fP, the port number to which to connect. If the default
|
|
IANA-assigned port of 389 is desired, LDAP_PORT should be specified for
|
|
\fIport\fP. The \fIhost\fP parameter may contain a blank-separated list
|
|
of hosts to try to connect to, and each host may optionally by of the form
|
|
\fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP
|
|
parameter to
|
|
.BR ldap_open() .
|
|
Upon successfully making a connection to an
|
|
LDAP server,
|
|
.B ldap_open()
|
|
returns a pointer to an opaque LDAP structure, which should be passed
|
|
to subsequent calls to
|
|
.BR ldap_bind() ,
|
|
.BR ldap_search() ,
|
|
etc. Certain fields in the LDAP structure can be set to indicate size limit,
|
|
time limit, and how aliases are handled during operations; read and write access
|
|
to those fields must occur by calling
|
|
.BR ldap_get_option (3)
|
|
and
|
|
.BR ldap_set_option (3)
|
|
respectively, whenever possible.
|
|
.LP
|
|
.B
|
|
ldap_init()
|
|
acts just like
|
|
.BR ldap_open() ,
|
|
but does not open a connection
|
|
to the LDAP server. The actual connection open will occur when the
|
|
first operation is attempted.
|
|
.LP
|
|
.B ldap_initialize()
|
|
acts like
|
|
.BR ldap_init() ,
|
|
but it returns an integer indicating either success or the failure reason,
|
|
and it allows to specify details for the connection in the schema portion
|
|
of the URI.
|
|
.LP
|
|
At this time,
|
|
.B ldap_open()
|
|
and
|
|
.B ldap_init()
|
|
are deprecated in favor of
|
|
.BR ldap_initialize() ,
|
|
essentially because the latter allows to specify a schema in the URI
|
|
and it explicitly returns an error code.
|
|
.LP
|
|
.B ldap_init_fd()
|
|
allows an LDAP structure to be initialized using an already-opened
|
|
connection. The
|
|
.I proto
|
|
parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP,
|
|
or LDAP_PROTO_IPC
|
|
for a connection using TCP, UDP, or IPC, respectively. The value
|
|
LDAP_PROTO_EXT
|
|
may also be specified if user-supplied sockbuf handlers are going to
|
|
be used. Note that support for UDP is not implemented unless libldap
|
|
was built with LDAP_CONNECTIONLESS defined.
|
|
The
|
|
.I uri
|
|
parameter may optionally be provided for informational purposes.
|
|
|
|
Note: the first call into the LDAP library also initializes the global
|
|
options for the library. As such the first call should be single-threaded
|
|
or otherwise protected to insure that only one call is active. It is
|
|
recommended that
|
|
.BR ldap_get_option ()
|
|
or
|
|
.BR ldap_set_option ()
|
|
be used in the program's main thread before any additional threads are created.
|
|
See
|
|
.BR ldap_get_option (3).
|
|
|
|
.SH ERRORS
|
|
If an error occurs,
|
|
.B ldap_open()
|
|
and
|
|
.B ldap_init()
|
|
will return NULL and errno should be set appropriately.
|
|
.B ldap_initialize()
|
|
and
|
|
.B ldap_init_fd()
|
|
will directly return the LDAP code associated to the error (or
|
|
.I LDAP_SUCCESS
|
|
in case of success);
|
|
errno should be set as well whenever appropriate.
|
|
.SH SEE ALSO
|
|
.BR ldap (3),
|
|
.BR ldap_bind (3),
|
|
.BR ldap_get_option (3),
|
|
.BR ldap_set_option (3),
|
|
.BR lber-sockbuf (3),
|
|
.BR errno (3)
|
|
.SH ACKNOWLEDGEMENTS
|
|
.so ../Project
|