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

   1 .TH LDAP 3 "21 July 2000" "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 part of a distributed directory service.  This API supports
  18 LDAP over TCP, LDAP over SSL, and LDAP over IPC (UNIX domain
  19 sockets).
  20 .LP
  21 The OpenLDAP LDAP 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 .SH UTILITY ROUTINES
 100 Also provided are various utility routines.  The
 101 .BR ldap_sort (3)
 102 routines are used to sort the entries and values returned via
 103 the ldap search routines.  The
 104 .BR ldap_friendly (3)
 105 routines are
 106 used to map from short two letter country codes (or other strings)
 107 to longer "friendlier" names.
 108 .SH BER LIBRARY
 109 Also included in the distribution is a set of lightweight Basic
 110 Encoding Rules routines.  These routines are used by the LDAP library
 111 routines to encode and decode LDAP protocol elements using the
 112 (slightly simplified) Basic Encoding Rules defined by LDAP.  They are
 113 not normally used directly by an LDAP application program excepting
 114 in the handling of controls and extended operations.  The
 115 routines provide a printf and scanf-like interface, as well as
 116 lower-level access.  These routines are found in the -llber
 117 library.
 118 .SH INDEX
 119 .TP 20
 120 .SM ldap_open(3)
 121 open a connection to an LDAP server
 122 .TP
 123 .SM ldap_init(3)
 124 initialize the LDAP library without opening a connection to a server
 125 .TP
 126 .SM ldap_result(3)
 127 wait for the result from an asynchronous operation
 128 .TP
 129 .SM ldap_abandon(3)
 130 abandon (abort) an asynchronous operation
 131 .TP
 132 .SM ldap_add(3)
 133 asynchronously add an entry
 134 .TP
 135 .SM ldap_add_s(3)
 136 synchronously add an entry
 137 .TP
 138 .SM ldap_bind(3)
 139 asynchronously bind to the directory
 140 .TP
 141 .SM ldap_bind_s(3)
 142 synchronously bind to the directory
 143 .TP
 144 .SM ldap_simple_bind(3)
 145 asynchronously bind to the directory using simple authentication
 146 .TP
 147 .SM ldap_simple_bind_s(3)
 148 synchronously bind to the directory using simple authentication
 149 .TP
 150 .SM ldap_kerberos_bind_s(3)
 151 synchronously bind to the directory using kerberos authentication
 152 .TP
 153 .SM ldap_kerberos_bind1(3)
 154 asynchronously bind to the LDAP server using kerberos authentication
 155 .TP
 156 .SM ldap_kerberos_bind1_s(3)
 157 synchronously bind to the LDAP server using kerberos authentication
 158 .TP
 159 .SM ldap_kerberos_bind2(3)
 160 asynchronously bind to the DSA using kerberos authentication
 161 .TP
 162 .SM ldap_kerberos_bind2_s(3)
 163 synchronously bind to the DSA using kerberos authentication
 164 .TP
 165 .SM ldap_unbind(3)
 166 synchronously unbind from the LDAP server and close the connection
 167 .TP
 168 .SM ldap_unbind_s(3)
 169 equivalent to
 170 .BR ldap_unbind (3)
 171 .TP
 172 .SM ldap_memfree (3)
 173 dispose of memory allocated by LDAP routines.
 174 .TP
 175 .SM ldap_enable_cache(3)
 176 enable LDAP client caching
 177 .TP
 178 .SM ldap_disable_cache(3)
 179 disable LDAP client caching
 180 .TP
 181 .SM ldap_destroy_cache(3)
 182 disable LDAP client caching and destroy cache contents
 183 .TP
 184 .SM ldap_flush_cache(3)
 185 flush LDAP client cache
 186 .TP
 187 .SM ldap_uncache_entry(3)
 188 uncache requests pertaining to an entry
 189 .TP
 190 .SM ldap_uncache_request(3)
 191 uncache a request
 192 .TP
 193 .SM ldap_set_cache_options(3)
 194 set cache options
 195 .TP
 196 .SM ldap_compare(3)
 197 asynchronous compare to a directory entry
 198 .TP
 199 .SM ldap_compare_s(3)
 200 synchronous compare to a directory entry
 201 .TP
 202 .SM ldap_delete(3)
 203 asynchronously delete an entry
 204 .TP
 205 .SM ldap_delete_s(3)
 206 synchronously delete an entry
 207 .TP
 208 .SM ldap_init_templates(3)
 209 initialize display template routines from a file
 210 .TP
 211 .SM ldap_init_templates_buf(3)
 212 initialize display template routines from a buffer
 213 .TP
 214 .SM ldap_free_templates(3)
 215 free display template routine memory
 216 .TP
 217 .SM ldap_first_disptmpl(3)
 218 get first display template
 219 .TP
 220 .SM ldap_next_disptmpl(3)
 221 get next display template
 222 .TP
 223 .SM ldap_oc2template(3)
 224 return template appropriate for objectclass
 225 .TP
 226 .SM ldap_name2template(3)
 227 return named template
 228 .TP
 229 .SM ldap_tmplattrs(3)
 230 return attributes needed by template
 231 .TP
 232 .SM ldap_first_tmplrow(3)
 233 return first row of displayable items in a template
 234 .TP
 235 .SM ldap_next_tmplrow(3)
 236 return next row of displayable items in a template
 237 .TP
 238 .SM ldap_first_tmplcol(3)
 239 return first column of displayable items in a template
 240 .TP
 241 .SM ldap_next_tmplcol(3)
 242 return next column of displayable items in a template
 243 .TP
 244 .SM ldap_entry2text(3)
 245 display an entry as text using a display template
 246 .TP
 247 .SM ldap_entry2text_search(3)
 248 search for and display an entry as text using a display template
 249 .TP
 250 .SM ldap_vals2text(3)
 251 display values as text
 252 .TP
 253 .SM ldap_entry2html(3)
 254 display an entry as HTML (HyperText Markup Language) using a display template
 255 .TP
 256 .SM ldap_entry2html_search(3)
 257 search for and display an entry as HTML using a display template
 258 .TP
 259 .SM ldap_vals2html(3)
 260 display values as HTML
 261 .TP
 262 .SM ldap_perror(3)
 263 print an LDAP error indication to standard error
 264 .TP
 265 .SM ld_errno(3)
 266 LDAP error indication
 267 .TP
 268 .SM ldap_result2error(3)
 269 extract LDAP error indication from LDAP result
 270 .TP
 271 .SM ldap_errlist(3)
 272 list of ldap errors and their meanings
 273 .TP
 274 .SM ldap_err2string(3)
 275 convert LDAP error indication to a string
 276 .TP
 277 .SM ldap_first_attribute(3)
 278 return first attribute name in an entry
 279 .TP
 280 .SM ldap_next_attribute(3)
 281 return next attribute name in an entry
 282 .TP
 283 .SM ldap_first_entry(3)
 284 return first entry in a chain of search results
 285 .TP
 286 .SM ldap_next_entry(3)
 287 return next entry in a chain of search results
 288 .TP
 289 .SM ldap_count_entries(3)
 290 return number of entries in a search result
 291 .TP
 292 .SM ldap_friendly_name(3)
 293 map from unfriendly to friendly names
 294 .TP
 295 .SM ldap_free_friendlymap(3)
 296 free resources used by ldap_friendly(3)
 297 .TP
 298 .SM ldap_get_dn(3)
 299 extract the DN from an entry
 300 .TP
 301 .SM ldap_explode_dn(3)
 302 convert a DN into its component parts
 303 .TP
 304 .SM ldap_explode_rdn(3)
 305 convert a RDN into its component parts
 306 .TP
 307 .SM ldap_get_values(3)
 308 return an attribute's values
 309 .TP
 310 .SM ldap_get_values_len(3)
 311 return an attribute values with lengths
 312 .TP
 313 .SM ldap_value_free(3)
 314 free memory allocated by ldap_get_values(3)
 315 .TP
 316 .SM ldap_value_free_len(3)
 317 free memory allocated by ldap_get_values_len(3)
 318 .TP
 319 .SM ldap_count_values(3)
 320 return number of values
 321 .TP
 322 .SM ldap_count_values_len(3)
 323 return number of values
 324 .TP
 325 .SM ldap_init_getfilter(3)
 326 initialize getfilter routines from a file
 327 .TP
 328 .SM ldap_init_getfilter_buf(3)
 329 initialize getfilter routines from a buffer
 330 .TP
 331 .SM ldap_getfilter_free(3)
 332 free resources allocated by ldap_init_getfilter(3)
 333 .TP
 334 .SM ldap_getfirstfilter(3)
 335 return first search filter
 336 .TP
 337 .SM ldap_getnextfilter(3)
 338 return next search filter
 339 .TP
 340 .SM ldap_build_filter(3)
 341 construct an LDAP search filter from a pattern
 342 .TP
 343 .SM ldap_setfilteraffixes(3)
 344 set prefix and suffix for search filters
 345 .TP
 346 .SM ldap_modify(3)
 347 asynchronously modify an entry
 348 .TP
 349 .SM ldap_modify_s(3)
 350 synchronously modify an entry
 351 .TP
 352 .SM ldap_mods_free(3)
 353 free array of pointers to mod structures used by ldap_modify(3)
 354 .TP
 355 .SM ldap_modrdn2(3)
 356 asynchronously modify the RDN of an entry
 357 .TP
 358 .SM ldap_modrdn2_s(3)
 359 synchronously modify the RDN of an entry
 360 .TP
 361 .SM ldap_modrdn(3)
 362 depreciated - use ldap_modrdn2(3)
 363 .TP
 364 .SM ldap_modrdn_s(3)
 365 depreciated - use ldap_modrdn2_s(3)
 366 .TP
 367 .SM ldap_msgfree(3)
 368 free results allocated by ldap_result(3)
 369 .TP
 370 .SM ldap_msgtype(3)
 371 return the message type of a message from ldap_result(3)
 372 .TP
 373 .SM ldap_msgid(3)
 374 return the message id of a message from ldap_result(3)
 375 .TP
 376 .SM ldap_search(3)
 377 asynchronously search the directory
 378 .TP
 379 .SM ldap_search_s(3)
 380 synchronously search the directory
 381 .TP
 382 .SM ldap_search_st(3)
 383 synchronously search the directory with timeout
 384 .TP
 385 .SM ldap_is_ldap_url(3)
 386 check a URL string to see if it is an LDAP URL
 387 .TP
 388 .SM ldap_url_parse(3)
 389 break up an LDAP URL string into its components
 390 .TP
 391 .SM ldap_url_search(3)
 392 asynchronously search using an LDAP URL
 393 .TP
 394 .SM ldap_url_search_s(3)
 395 synchronously search using an LDAP URL
 396 .TP
 397 .SM ldap_url_search_st(3)
 398 synchronously search using an LDAP URL and a timeout
 399 .TP
 400 .SM ldap_init_searchprefs(3)
 401 initialize searchprefs routines from a file
 402 .TP
 403 .SM ldap_init_searchprefs_buf(3)
 404 initialize searchprefs routines from a buffer
 405 .TP
 406 .SM ldap_free_searchprefs(3)
 407 free memory allocated by searchprefs routines
 408 .TP
 409 .SM ldap_first_searchobj(3)
 410 return first searchpref object
 411 .TP
 412 .SM ldap_next_searchobj(3)
 413 return next searchpref object
 414 .TP
 415 .SM ldap_sort_entries(3)
 416 sort a list of search results
 417 .TP
 418 .SM ldap_sort_values(3)
 419 sort a list of attribute values
 420 .TP
 421 .SM ldap_sort_strcasecmp(3)
 422 case insensitive string comparison
 423 .SH SEE ALSO
 424 .BR slapd (8)
 425 .SH ACKNOWLEDGEMENTS
 426 .B      OpenLDAP
 427 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 428 .B      OpenLDAP
 429 is derived from University of Michigan LDAP 3.3 Release.