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

   1 .TH LDAP 3 "1 August 2001" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap - OpenLDAP Lightweight Directory Access Protocol API
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <ldap.h>
  11 .ft
  12 .fi
  13 .SH DESCRIPTION
  14 .LP
  15 The Lightweight Directory Access Protocol provides access to
  16 X.500 directory services.  The services may be stand\-alone
  17 or part of a distributed directory service.  This API supports
  18 LDAP over TCP (RFC2251), LDAP over SSL, and LDAP over IPC (UNIX domain
  19 sockets).  This API supports SASL (RFC2829) and Start TLS (RFC2830).
  20 .LP
  21 The OpenLDAP Software package includes a stand-alone server in
  22 .BR slapd (8),
  23 various LDAP clients, and an LDAP client library used to provide
  24 programmatic access to the LDAP protocol. This man page gives an
  25 overview of the LDAP library routines.
  26 .LP
  27 Both synchronous and asynchronous APIs are provided.  Also included are
  28 various routines to parse the results returned from these routines.
  29 These routines are found in the \-lldap library.
  30 .LP
  31 The basic interaction is as follows.  A session handle associated
  32 with created using
  33 .BR ldap_init (3).
  34 The underlying session is established upon first use which is
  35 commonly an LDAP bind operation.  The LDAP bind operation is
  36 performed by calling one of
  37 .BR ldap_sasl_bind (3)
  38 and friends.  Next, other operations are performed
  39 by calling one of the synchronous or asynchronous routines (e.g.,
  40 .BR ldap_search_ext_s (3)
  41 or
  42 .BR ldap_search_ext (3)
  43 followed by
  44 .BR ldap_result (3)).
  45 Results returned from these routines are interpreted by calling the
  46 LDAP parsing routines such as
  47 .BR ldap_parse_result (3).
  48 The LDAP association and underlying connection is terminated by calling
  49 .BR ldap_unbind_ext (3).
  50 Errors can be interpreted by calling
  51 .BR ldap_err2string (3).
  52 .SH SEARCH FILTERS
  53 Search filters to be passed to the ldap search routines can be
  54 constructed by hand, or by calling the
  55 .BR ldap_getfilter (3)
  56 routines, which use the
  57 .BR ldapgetfilter.conf (5)
  58 file to turn a string (presumably that a user has typed) into a series
  59 of search filters.
  60 .SH DISPLAYING RESULTS
  61 Results obtained from the ldap search routines can be output by hand,
  62 by calling
  63 .BR ldap_first_entry (3)
  64 and
  65 .BR ldap_next_entry (3)
  66 to step through
  67 the entries returned,
  68 .BR ldap_first_attribute (3)
  69 and
  70 .BR ldap_next_attribute (3)
  71 to step through an entry's attributes, and
  72 .BR ldap_get_values (3)
  73 to retrieve a given attribute's value.  Attribute values
  74 may or may not be displayable.
  75 .LP
  76 Alternatively, the entry can be output automatically by calling
  77 the
  78 .BR ldap_entry2text (3),
  79 .BR ldap_entry2text_search (3),
  80 .BR ldap_entry2html (3),
  81 or
  82 .BR ldap_entry2html_search (3)
  83 routines.  These routines look up the object
  84 class of the entry they are passed in the
  85 .BR ldaptemplates.conf (5)
  86 file to decide which attributes to display and how to display them.
  87 Output is handled via a routine passed in as a parameter.
  88 .SH UNIFORM RESOURCE LOCATORS (URLS)
  89 The
  90 .BR ldap_url (3)
  91 routines can be used test a URL to see if it is an LDAP URL, to parse LDAP
  92 URLs into their component pieces, and to initiate searches directly using
  93 an LDAP URL.
  94 .SH CACHING
  95 The
  96 .BR ldap_cache (3)
  97 routines implement a local client caching scheme,
  98 providing a substantial performance increase for repeated queries.
  99 Caching is experiemental.
 100 .SH UTILITY ROUTINES
 101 Also provided are various utility routines.  The
 102 .BR ldap_sort (3)
 103 routines are used to sort the entries and values returned via
 104 the ldap search routines.  The
 105 .BR ldap_friendly (3)
 106 routines are
 107 used to map from short two letter country codes (or other strings)
 108 to longer "friendlier" names.
 109 .SH BER LIBRARY
 110 Also included in the distribution is a set of lightweight Basic
 111 Encoding Rules routines.  These routines are used by the LDAP library
 112 routines to encode and decode LDAP protocol elements using the
 113 (slightly simplified) Basic Encoding Rules defined by LDAP.  They are
 114 not normally used directly by an LDAP application program except
 115 in the handling of controls and extended operations.  The
 116 routines provide a printf and scanf-like interface, as well as
 117 lower-level access.  These routines are found in the -llber
 118 library.
 119 .SH INDEX
 120 .TP 20
 121 .SM ldap_open(3)
 122 open a connection to an LDAP server
 123 .TP
 124 .SM ldap_init(3)
 125 initialize the LDAP library without opening a connection to a server
 126 .TP
 127 .SM ldap_result(3)
 128 wait for the result from an asynchronous operation
 129 .TP
 130 .SM ldap_abandon(3)
 131 abandon (abort) an asynchronous operation
 132 .TP
 133 .SM ldap_add(3)
 134 asynchronously add an entry
 135 .TP
 136 .SM ldap_add_s(3)
 137 synchronously add an entry
 138 .TP
 139 .SM ldap_bind(3)
 140 asynchronously bind to the directory
 141 .TP
 142 .SM ldap_bind_s(3)
 143 synchronously bind to the directory
 144 .TP
 145 .SM ldap_simple_bind(3)
 146 asynchronously bind to the directory using simple authentication
 147 .TP
 148 .SM ldap_simple_bind_s(3)
 149 synchronously bind to the directory using simple authentication
 150 .TP
 151 .SM ldap_unbind(3)
 152 synchronously unbind from the LDAP server and close the connection
 153 .TP
 154 .SM ldap_unbind_s(3)
 155 equivalent to
 156 .BR ldap_unbind (3)
 157 .TP
 158 .SM ldap_memfree (3)
 159 dispose of memory allocated by LDAP routines.
 160 .TP
 161 .SM ldap_enable_cache(3)
 162 enable LDAP client caching
 163 .TP
 164 .SM ldap_disable_cache(3)
 165 disable LDAP client caching
 166 .TP
 167 .SM ldap_destroy_cache(3)
 168 disable LDAP client caching and destroy cache contents
 169 .TP
 170 .SM ldap_flush_cache(3)
 171 flush LDAP client cache
 172 .TP
 173 .SM ldap_uncache_entry(3)
 174 uncache requests pertaining to an entry
 175 .TP
 176 .SM ldap_uncache_request(3)
 177 uncache a request
 178 .TP
 179 .SM ldap_set_cache_options(3)
 180 set cache options
 181 .TP
 182 .SM ldap_compare(3)
 183 asynchronous compare to a directory entry
 184 .TP
 185 .SM ldap_compare_s(3)
 186 synchronous compare to a directory entry
 187 .TP
 188 .SM ldap_delete(3)
 189 asynchronously delete an entry
 190 .TP
 191 .SM ldap_delete_s(3)
 192 synchronously delete an entry
 193 .TP
 194 .SM ldap_init_templates(3)
 195 initialize display template routines from a file
 196 .TP
 197 .SM ldap_init_templates_buf(3)
 198 initialize display template routines from a buffer
 199 .TP
 200 .SM ldap_free_templates(3)
 201 free display template routine memory
 202 .TP
 203 .SM ldap_first_disptmpl(3)
 204 get first display template
 205 .TP
 206 .SM ldap_next_disptmpl(3)
 207 get next display template
 208 .TP
 209 .SM ldap_oc2template(3)
 210 return template appropriate for objectclass
 211 .TP
 212 .SM ldap_name2template(3)
 213 return named template
 214 .TP
 215 .SM ldap_tmplattrs(3)
 216 return attributes needed by template
 217 .TP
 218 .SM ldap_first_tmplrow(3)
 219 return first row of displayable items in a template
 220 .TP
 221 .SM ldap_next_tmplrow(3)
 222 return next row of displayable items in a template
 223 .TP
 224 .SM ldap_first_tmplcol(3)
 225 return first column of displayable items in a template
 226 .TP
 227 .SM ldap_next_tmplcol(3)
 228 return next column of displayable items in a template
 229 .TP
 230 .SM ldap_entry2text(3)
 231 display an entry as text using a display template
 232 .TP
 233 .SM ldap_entry2text_search(3)
 234 search for and display an entry as text using a display template
 235 .TP
 236 .SM ldap_vals2text(3)
 237 display values as text
 238 .TP
 239 .SM ldap_entry2html(3)
 240 display an entry as HTML (HyperText Markup Language) using a display template
 241 .TP
 242 .SM ldap_entry2html_search(3)
 243 search for and display an entry as HTML using a display template
 244 .TP
 245 .SM ldap_vals2html(3)
 246 display values as HTML
 247 .TP
 248 .SM ldap_perror(3)
 249 print an LDAP error indication to standard error
 250 .TP
 251 .SM ld_errno(3)
 252 LDAP error indication
 253 .TP
 254 .SM ldap_result2error(3)
 255 extract LDAP error indication from LDAP result
 256 .TP
 257 .SM ldap_errlist(3)
 258 list of ldap errors and their meanings
 259 .TP
 260 .SM ldap_err2string(3)
 261 convert LDAP error indication to a string
 262 .TP
 263 .SM ldap_first_attribute(3)
 264 return first attribute name in an entry
 265 .TP
 266 .SM ldap_next_attribute(3)
 267 return next attribute name in an entry
 268 .TP
 269 .SM ldap_first_entry(3)
 270 return first entry in a chain of search results
 271 .TP
 272 .SM ldap_next_entry(3)
 273 return next entry in a chain of search results
 274 .TP
 275 .SM ldap_count_entries(3)
 276 return number of entries in a search result
 277 .TP
 278 .SM ldap_friendly_name(3)
 279 map from unfriendly to friendly names
 280 .TP
 281 .SM ldap_free_friendlymap(3)
 282 free resources used by ldap_friendly(3)
 283 .TP
 284 .SM ldap_get_dn(3)
 285 extract the DN from an entry
 286 .TP
 287 .SM ldap_explode_dn(3)
 288 convert a DN into its component parts
 289 .TP
 290 .SM ldap_explode_rdn(3)
 291 convert a RDN into its component parts
 292 .TP
 293 .SM ldap_get_values(3)
 294 return an attribute's values
 295 .TP
 296 .SM ldap_get_values_len(3)
 297 return an attribute values with lengths
 298 .TP
 299 .SM ldap_value_free(3)
 300 free memory allocated by ldap_get_values(3)
 301 .TP
 302 .SM ldap_value_free_len(3)
 303 free memory allocated by ldap_get_values_len(3)
 304 .TP
 305 .SM ldap_count_values(3)
 306 return number of values
 307 .TP
 308 .SM ldap_count_values_len(3)
 309 return number of values
 310 .TP
 311 .SM ldap_init_getfilter(3)
 312 initialize getfilter routines from a file
 313 .TP
 314 .SM ldap_init_getfilter_buf(3)
 315 initialize getfilter routines from a buffer
 316 .TP
 317 .SM ldap_getfilter_free(3)
 318 free resources allocated by ldap_init_getfilter(3)
 319 .TP
 320 .SM ldap_getfirstfilter(3)
 321 return first search filter
 322 .TP
 323 .SM ldap_getnextfilter(3)
 324 return next search filter
 325 .TP
 326 .SM ldap_build_filter(3)
 327 construct an LDAP search filter from a pattern
 328 .TP
 329 .SM ldap_setfilteraffixes(3)
 330 set prefix and suffix for search filters
 331 .TP
 332 .SM ldap_modify(3)
 333 asynchronously modify an entry
 334 .TP
 335 .SM ldap_modify_s(3)
 336 synchronously modify an entry
 337 .TP
 338 .SM ldap_mods_free(3)
 339 free array of pointers to mod structures used by ldap_modify(3)
 340 .TP
 341 .SM ldap_modrdn2(3)
 342 asynchronously modify the RDN of an entry
 343 .TP
 344 .SM ldap_modrdn2_s(3)
 345 synchronously modify the RDN of an entry
 346 .TP
 347 .SM ldap_modrdn(3)
 348 depreciated - use ldap_modrdn2(3)
 349 .TP
 350 .SM ldap_modrdn_s(3)
 351 depreciated - use ldap_modrdn2_s(3)
 352 .TP
 353 .SM ldap_msgfree(3)
 354 free results allocated by ldap_result(3)
 355 .TP
 356 .SM ldap_msgtype(3)
 357 return the message type of a message from ldap_result(3)
 358 .TP
 359 .SM ldap_msgid(3)
 360 return the message id of a message from ldap_result(3)
 361 .TP
 362 .SM ldap_search(3)
 363 asynchronously search the directory
 364 .TP
 365 .SM ldap_search_s(3)
 366 synchronously search the directory
 367 .TP
 368 .SM ldap_search_st(3)
 369 synchronously search the directory with timeout
 370 .TP
 371 .SM ldap_is_ldap_url(3)
 372 check a URL string to see if it is an LDAP URL
 373 .TP
 374 .SM ldap_url_parse(3)
 375 break up an LDAP URL string into its components
 376 .TP
 377 .SM ldap_init_searchprefs(3)
 378 initialize searchprefs routines from a file
 379 .TP
 380 .SM ldap_init_searchprefs_buf(3)
 381 initialize searchprefs routines from a buffer
 382 .TP
 383 .SM ldap_free_searchprefs(3)
 384 free memory allocated by searchprefs routines
 385 .TP
 386 .SM ldap_first_searchobj(3)
 387 return first searchpref object
 388 .TP
 389 .SM ldap_next_searchobj(3)
 390 return next searchpref object
 391 .TP
 392 .SM ldap_sort_entries(3)
 393 sort a list of search results
 394 .TP
 395 .SM ldap_sort_values(3)
 396 sort a list of attribute values
 397 .TP
 398 .SM ldap_sort_strcasecmp(3)
 399 case insensitive string comparison
 400 .SH SEE ALSO
 401 .BR slapd (8)
 402 .SH ACKNOWLEDGEMENTS
 403 .B      OpenLDAP
 404 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 405 .B      OpenLDAP
 406 is derived from University of Michigan LDAP 3.3 Release.