git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_open.3

   1 .TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2014 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, \-lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <ldap.h>
  13 .LP
  14 .ft B
  15 LDAP *ldap_open(host, port)
  16 .ft
  17 char *host;
  18 int port;
  19 .LP
  20 .ft B
  21 LDAP *ldap_init(host, port)
  22 .ft
  23 char *host;
  24 int port;
  25 .LP
  26 .ft B
  27 int ldap_initialize(ldp, uri)
  28 .ft
  29 LDAP **ldp;
  30 char *uri;
  31 .LP
  32 .ft B
  33 int ldap_set_urllist_proc(ld, proc, params)
  34 .ft
  35 LDAP *ld;
  36 LDAP_URLLIST_PROC *proc;
  37 void *params;
  38 .LP
  39 .ft B
  40 int (LDAP_URLLIST_PROC)(ld, urllist, url, params);
  41 .ft
  42 LDAP *ld;
  43 LDAPURLDesc **urllist;
  44 LDAPURLDesc **url;
  45 void *params;
  46 .LP
  47 .ft B
  48 #include <ldap_pvt.h>
  49 .LP
  50 .ft B
  51 int ldap_init_fd(fd, proto, uri, ldp)
  52 .ft
  53 ber_socket_t fd;
  54 int proto;
  55 char *uri;
  56 LDAP **ldp;
  57 .SH DESCRIPTION
  58 .LP
  59 .B ldap_open()
  60 opens a connection to an LDAP server and allocates an LDAP
  61 structure which is used to identify
  62 the connection and to maintain per-connection information.
  63 .B ldap_init()
  64 allocates an LDAP structure but does not open an initial connection.
  65 .B ldap_initialize()
  66 allocates an LDAP structure but does not open an initial connection.
  67 .B ldap_init_fd()
  68 allocates an LDAP structure using an existing connection on the
  69 provided socket.
  70 One
  71 of these routines must be called before any operations are attempted.
  72 .LP
  73 .B ldap_open()
  74 takes \fIhost\fP, the hostname on which the LDAP server is
  75 running, and \fIport\fP, the port number to which to connect.  If the default
  76 IANA-assigned port of 389 is desired, LDAP_PORT should be specified for
  77 \fIport\fP.  The \fIhost\fP parameter may contain a blank-separated list
  78 of hosts to try to connect to, and each host may optionally by of the form
  79 \fIhost:port\fP.  If present, the \fI:port\fP overrides the \fIport\fP
  80 parameter to
  81 .BR ldap_open() .
  82 Upon successfully making a connection to an
  83 LDAP server,
  84 .B ldap_open()
  85 returns a pointer to an opaque LDAP structure, which should be passed
  86 to subsequent calls to
  87 .BR ldap_bind() ,
  88 .BR ldap_search() ,
  89 etc. Certain fields in the LDAP structure can be set to indicate size limit,
  90 time limit, and how aliases are handled during operations; read and write access
  91 to those fields must occur by calling
  92 .BR ldap_get_option (3)
  93 and
  94 .BR ldap_set_option (3)
  95 respectively, whenever possible.
  96 .LP
  97 .B
  98 ldap_init()
  99 acts just like
 100 .BR ldap_open() ,
 101 but does not open a connection
 102 to the LDAP server.  The actual connection open will occur when the
 103 first operation is attempted.
 104 .LP
 105 .B ldap_initialize()
 106 acts like
 107 .BR ldap_init() ,
 108 but it returns an integer indicating either success or the failure reason,
 109 and it allows to specify details for the connection in the schema portion
 110 of the URI.
 111 The
 112 .I uri
 113 parameter may be a comma- or whitespace-separated list of URIs
 114 containing only the
 115 .IR schema ,
 116 the
 117 .IR host ,
 118 and the
 119 .I port
 120 fields.
 121 Apart from
 122 .BR ldap ,
 123 other (non-standard) recognized values of the
 124 .I schema
 125 field are
 126 .B ldaps
 127 (LDAP over TLS),
 128 .B ldapi
 129 (LDAP over IPC),
 130 and
 131 .B cldap
 132 (connectionless LDAP).
 133 If other fields are present, the behavior is undefined.
 134 .LP
 135 At this time,
 136 .B ldap_open()
 137 and
 138 .B ldap_init()
 139 are deprecated in favor of
 140 .BR ldap_initialize() ,
 141 essentially because the latter allows to specify a schema in the URI
 142 and it explicitly returns an error code.
 143 .LP
 144 .B ldap_init_fd()
 145 allows an LDAP structure to be initialized using an already-opened
 146 connection. The
 147 .I proto
 148 parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP,
 149 or LDAP_PROTO_IPC
 150 for a connection using TCP, UDP, or IPC, respectively. The value
 151 LDAP_PROTO_EXT
 152 may also be specified if user-supplied sockbuf handlers are going to
 153 be used. Note that support for UDP is not implemented unless libldap
 154 was built with LDAP_CONNECTIONLESS defined.
 155 The
 156 .I uri
 157 parameter may optionally be provided for informational purposes.
 158 .LP
 159 .B ldap_set_urllist_proc()
 160 allows to set a function
 161 .I proc
 162 of type
 163 .I LDAP_URLLIST_PROC
 164 that is called when a successful connection can be established.
 165 This function receives the list of URIs parsed from the
 166 .I uri
 167 string originally passed to
 168 .BR ldap_initialize() ,
 169 and the one that successfully connected.
 170 The function may manipulate the URI list; the typical use consists
 171 in moving the successful URI to the head of the list,
 172 so that subsequent attempts to connect to one of the URIs using the same LDAP handle
 173 will try it first.
 174 If
 175 .I ld
 176 is null,
 177 .I proc
 178 is set as a global parameter that is inherited by all handlers
 179 within the process that are created after the call to
 180 .BR ldap_set_urllist_proc() .
 181 By default, no
 182 .I LDAP_URLLIST_PROC
 183 is set.
 184 In a multithreaded environment,
 185 .B ldap_set_urllist_proc()
 186 must be called before any concurrent operation using the LDAP handle is started.
 187
 188 Note: the first call into the LDAP library also initializes the global
 189 options for the library. As such the first call should be single-threaded
 190 or otherwise protected to insure that only one call is active. It is
 191 recommended that
 192 .BR ldap_get_option ()
 193 or
 194 .BR ldap_set_option ()
 195 be used in the program's main thread before any additional threads are created.
 196 See
 197 .BR ldap_get_option (3).
 198
 199 .SH ERRORS
 200 If an error occurs,
 201 .B ldap_open()
 202 and
 203 .B ldap_init()
 204 will return NULL and
 205 .I errno
 206 should be set appropriately.
 207 .B ldap_initialize()
 208 and
 209 .B ldap_init_fd()
 210 will directly return the LDAP code associated to the error (or
 211 .I LDAP_SUCCESS
 212 in case of success);
 213 .I errno
 214 should be set as well whenever appropriate.
 215 .B ldap_set_urllist_proc()
 216 returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success.
 217 .SH SEE ALSO
 218 .BR ldap (3),
 219 .BR ldap_bind (3),
 220 .BR ldap_get_option (3),
 221 .BR ldap_set_option (3),
 222 .BR lber-sockbuf (3),
 223 .BR errno (3)
 224 .SH ACKNOWLEDGEMENTS
 225 .so ../Project