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

   1 .TH LDAP 3 "10 November 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldap - Lightweight Directory Access Protocol package
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <lber.h>
   8 #include <ldap.h>
   9 .ft
  10 .fi
  11 .SH DESCRIPTION
  12 .LP
  13 The Lightweight Directory Access Protocol provides TCP/IP access to
  14 the X.500 Directory or to a stand-alone LDAP server.
  15 The OpenLDAP LDAP package includes a stand-alone server in
  16 .BR slapd (8),
  17 an LDAP to X.500 gateway in
  18 .BR ldapd (8),
  19 various LDAP clients, and an LDAP client library used to provide
  20 programmatic access to the LDAP protocol. This man page gives an
  21 overview of the LDAP library routines.
  22 .LP
  23 Both synchronous and asynchronous APIs are provided.  Also included are
  24 various routines to parse the results returned from these routines.
  25 These routines are found in the libldap.a library.
  26 .LP
  27 The basic interaction is as follows.  A connection is made to an LDAP
  28 server by calling
  29 .BR ldap_open (3).
  30 An LDAP bind operation is performed by calling
  31 one of
  32 .BR ldap_bind (3)
  33 and friends.  Next, other operations are performed
  34 by calling one of the synchronous or asynchronous routines (e.g.,
  35 .BR ldap_search_s (3)
  36 or
  37 .BR ldap_search (3)
  38 followed by
  39 .BR ldap_result (3)).
  40 Results returned from these routines are interpreted by calling the
  41 LDAP parsing routines.  The LDAP association is terminated by calling
  42 .BR ldap_unbind (3).
  43 Errors can be interpreted by calling
  44 .BR ldap_perror (3).
  45 The
  46 .BR ldap_set_rebind_proc (3)
  47 routine can be used to set a routine to be called back when an LDAP bind
  48 operation needs to occur when handling a client referral.
  49 .SH SEARCH FILTERS
  50 Search filters to be passed to the ldap search routines can be
  51 constructed by hand, or by calling the
  52 .BR ldap_getfilter (3)
  53 routines, which use the
  54 .BR ldapgetfilter.conf (5)
  55 file to turn a string (presumably that a user has typed) into a series
  56 of search filters.
  57 .SH DISPLAYING RESULTS
  58 Results obtained from the ldap search routines can be output by hand,
  59 by calling
  60 .BR ldap_first_entry (3)
  61 and
  62 .BR ldap_next_entry (3)
  63 to step through
  64 the entries returned,
  65 .BR ldap_first_attribute (3)
  66 and
  67 .BR ldap_next_attribute (3)
  68 to step through an entry's attributes, and
  69 .BR ldap_get_values (3)
  70 to retrieve a given attribute's value, and then calling
  71 .BR printf (3)
  72 or whatever to display the values.
  73 .LP
  74 Alternatively, the entry can be output automatically by calling
  75 the
  76 .BR ldap_entry2text (3),
  77 .BR ldap_entry2text_search (3),
  78 .BR ldap_entry2html (3),
  79 or
  80 .BR ldap_entry2html_search (3)
  81 routines.  These routines look up the object
  82 class of the entry they are passed in the
  83 .BR ldaptemplates.conf (5)
  84 file to decide which attributes to display and how to display them.
  85 Output is handled via a routine passed in as a parameter.
  86 .SH UNIFORM RESOURCE LOCATORS (URLS)
  87 The
  88 .BR ldap_url (3)
  89 routines can be used test a URL to see if it is an LDAP URL, to parse LDAP
  90 URLs into their component pieces, and to initiate searches directly using
  91 an LDAP URL.
  92 .SH USER FRIENDLY NAMING
  93 The
  94 .BR ldap_ufn (3)
  95 routines implement a user friendly naming
  96 scheme via LDAP.  This scheme allows you to look up entries
  97 using fuzzy, untyped names like "mark smith, umich, us".
  98 .SH CACHING
  99 The
 100 .BR ldap_cache (3)
 101 routines implement a local client caching scheme,
 102 providing a substantial performance increase for repeated queries.
 103 .SH UTILITY ROUTINES
 104 Also provided are various utility routines.  The
 105 .BR ldap_sort (3)
 106 routines are used to sort the entries and values returned via
 107 the ldap search routines.  The
 108 .BR ldap_friendly (3)
 109 routines are
 110 used to map from short two letter country codes (or other strings)
 111 to longer "friendlier" names.  The
 112 .BR ldap_charset (3)
 113 routines can be used to translate to and from the T.61 character
 114 set used for many character strings in the LDAP protocol.
 115 .SH CONNECTIONLESS ACCESS
 116 The
 117 .BR cldap_search_s (3)
 118 routine allows you to access the directory
 119 via Connectionless LDAP (CLDAP), which is similar to LDAP but
 120 operates over UDP, obviating the need to set up and tear down
 121 a connection by calling
 122 .BR ldap_open (3),
 123 .BR ldap_bind (3),
 124 and
 125 .BR ldap_unbind (3).
 126 .BR cldap_open (3)
 127 should be called before using
 128 .BR cldap_search_s (3).
 129 All the same getfilter, parsing, and display that can be used
 130 with regular LDAP routines can be used with the CLDAP routines.
 131 .SH BER LIBRARY
 132 Also included in the distribution is a set of lightweight Basic
 133 Encoding Rules routines.  These routines are used by the LDAP library
 134 routines to encode and decode LDAP protocol elements using the
 135 (slightly simplified) Basic Encoding Rules defined by LDAP.  They are
 136 not normally used directly by an LDAP application program.  The
 137 routines provide a printf and scanf-like interface, as well as
 138 lower-level access.  These routines are found in the liblber.a
 139 library.
 140 .SH INDEX
 141 .TP 20
 142 .SM ldap_open(3)
 143 open a connection to an LDAP server
 144 .TP
 145 .SM ldap_init(3)
 146 initialize the LDAP library without opening a connection to a server
 147 .TP
 148 .SM ldap_result(3)
 149 wait for the result from an asynchronous operation
 150 .TP
 151 .SM ldap_abandon(3)
 152 abandon (abort) an asynchronous operation
 153 .TP
 154 .SM ldap_add(3)
 155 asynchronously add an entry
 156 .TP
 157 .SM ldap_add_s(3)
 158 synchronously add an entry
 159 .TP
 160 .SM ldap_bind(3)
 161 asynchronously bind to the directory
 162 .TP
 163 .SM ldap_bind_s(3)
 164 synchronously bind to the directory
 165 .TP
 166 .SM ldap_simple_bind(3)
 167 asynchronously bind to the directory using simple authentication
 168 .TP
 169 .SM ldap_simple_bind_s(3)
 170 synchronously bind to the directory using simple authentication
 171 .TP
 172 .SM ldap_kerberos_bind_s(3)
 173 synchronously bind to the directory using kerberos authentication
 174 .TP
 175 .SM ldap_kerberos_bind1(3)
 176 asynchronously bind to the LDAP server using kerberos authentication
 177 .TP
 178 .SM ldap_kerberos_bind1_s(3)
 179 synchronously bind to the LDAP server using kerberos authentication
 180 .TP
 181 .SM ldap_kerberos_bind2(3)
 182 asynchronously bind to the DSA using kerberos authentication
 183 .TP
 184 .SM ldap_kerberos_bind2_s(3)
 185 synchronously bind to the DSA using kerberos authentication
 186 .TP
 187 .SM ldap_unbind(3)
 188 synchronously unbind from the LDAP server and close the connection
 189 .TP
 190 .SM ldap_unbind_s(3)
 191 equivalent to
 192 .BR ldap_unbind (3)
 193 .TP
 194 .SM ldap_memfree (3)
 195 dispose of memory allocated by LDAP routines.
 196 .TP
 197 .SM ldap_enable_cache(3)
 198 enable LDAP client caching
 199 .TP
 200 .SM ldap_disable_cache(3)
 201 disable LDAP client caching
 202 .TP
 203 .SM ldap_destroy_cache(3)
 204 disable LDAP client caching and destroy cache contents
 205 .TP
 206 .SM ldap_flush_cache(3)
 207 flush LDAP client cache
 208 .TP
 209 .SM ldap_uncache_entry(3)
 210 uncache requests pertaining to an entry
 211 .TP
 212 .SM ldap_uncache_request(3)
 213 uncache a request
 214 .TP
 215 .SM ldap_set_cache_options(3)
 216 set cache options
 217 .TP
 218 .SM ldap_compare(3)
 219 asynchronous compare to a directory entry
 220 .TP
 221 .SM ldap_compare_s(3)
 222 synchronous compare to a directory entry
 223 .TP
 224 .SM ldap_delete(3)
 225 asynchronously delete an entry
 226 .TP
 227 .SM ldap_delete_s(3)
 228 synchronously delete an entry
 229 .TP
 230 .SM ldap_init_templates(3)
 231 initialize display template routines from a file
 232 .TP
 233 .SM ldap_init_templates_buf(3)
 234 initialize display template routines from a buffer
 235 .TP
 236 .SM ldap_free_templates(3)
 237 free display template routine memory
 238 .TP
 239 .SM ldap_first_disptmpl(3)
 240 get first display template
 241 .TP
 242 .SM ldap_next_disptmpl(3)
 243 get next display template
 244 .TP
 245 .SM ldap_oc2template(3)
 246 return template appropriate for objectclass
 247 .TP
 248 .SM ldap_name2template(3)
 249 return named template
 250 .TP
 251 .SM ldap_tmplattrs(3)
 252 return attributes needed by template
 253 .TP
 254 .SM ldap_first_tmplrow(3)
 255 return first row of displayable items in a template
 256 .TP
 257 .SM ldap_next_tmplrow(3)
 258 return next row of displayable items in a template
 259 .TP
 260 .SM ldap_first_tmplcol(3)
 261 return first column of displayable items in a template
 262 .TP
 263 .SM ldap_next_tmplcol(3)
 264 return next column of displayable items in a template
 265 .TP
 266 .SM ldap_entry2text(3)
 267 display an entry as text using a display template
 268 .TP
 269 .SM ldap_entry2text_search(3)
 270 search for and display an entry as text using a display template
 271 .TP
 272 .SM ldap_vals2text(3)
 273 display values as text
 274 .TP
 275 .SM ldap_entry2html(3)
 276 display an entry as HTML (HyperText Markup Language) using a display template
 277 .TP
 278 .SM ldap_entry2html_search(3)
 279 search for and display an entry as HTML using a display template
 280 .TP
 281 .SM ldap_vals2html(3)
 282 display values as HTML
 283 .TP
 284 .SM ldap_perror(3)
 285 print an LDAP error indication to standard error
 286 .TP
 287 .SM ld_errno(3)
 288 LDAP error indication
 289 .TP
 290 .SM ldap_result2error(3)
 291 extract LDAP error indication from LDAP result
 292 .TP
 293 .SM ldap_errlist(3)
 294 list of ldap errors and their meanings
 295 .TP
 296 .SM ldap_err2string(3)
 297 convert LDAP error indication to a string
 298 .TP
 299 .SM ldap_first_attribute(3)
 300 return first attribute name in an entry
 301 .TP
 302 .SM ldap_next_attribute(3)
 303 return next attribute name in an entry
 304 .TP
 305 .SM ldap_first_entry(3)
 306 return first entry in a chain of search results
 307 .TP
 308 .SM ldap_next_entry(3)
 309 return next entry in a chain of search results
 310 .TP
 311 .SM ldap_count_entries(3)
 312 return number of entries in a search result
 313 .TP
 314 .SM ldap_friendly_name(3)
 315 map from unfriendly to friendly names
 316 .TP
 317 .SM ldap_free_friendlymap(3)
 318 free resources used by ldap_friendly(3)
 319 .TP
 320 .SM ldap_get_dn(3)
 321 extract the DN from an entry
 322 .TP
 323 .SM ldap_explode_dn(3)
 324 convert a DN into its component parts
 325 .TP
 326 .SM ldap_explode_rdn(3)
 327 convert a RDN into its component parts
 328 .TP
 329 .SM ldap_explode_dns(3)
 330 convert a DNS-style DN into its component parts (experimental)
 331 .TP
 332 .SM ldap_is_dns_dn(3)
 333 check to see if a DN is a DNS-style DN (experimental)
 334 .TP
 335 .SM ldap_dn2ufn(3)
 336 convert a DN into user friendly form
 337 .TP
 338 .SM ldap_get_values(3)
 339 return an attribute's values
 340 .TP
 341 .SM ldap_get_values_len(3)
 342 return an attribute values with lengths
 343 .TP
 344 .SM ldap_value_free(3)
 345 free memory allocated by ldap_get_values(3)
 346 .TP
 347 .SM ldap_value_free_len(3)
 348 free memory allocated by ldap_get_values_len(3)
 349 .TP
 350 .SM ldap_count_values(3)
 351 return number of values
 352 .TP
 353 .SM ldap_count_values_len(3)
 354 return number of values
 355 .TP
 356 .SM ldap_init_getfilter(3)
 357 initialize getfilter routines from a file
 358 .TP
 359 .SM ldap_init_getfilter_buf(3)
 360 initialize getfilter routines from a buffer
 361 .TP
 362 .SM ldap_getfilter_free(3)
 363 free resources allocated by ldap_init_getfilter(3)
 364 .TP
 365 .SM ldap_getfirstfilter(3)
 366 return first search filter
 367 .TP
 368 .SM ldap_getnextfilter(3)
 369 return next search filter
 370 .TP
 371 .SM ldap_build_filter(3)
 372 construct an LDAP search filter from a pattern
 373 .TP
 374 .SM ldap_setfilteraffixes(3)
 375 set prefix and suffix for search filters
 376 .TP
 377 .SM ldap_modify(3)
 378 asynchronously modify an entry
 379 .TP
 380 .SM ldap_modify_s(3)
 381 synchronously modify an entry
 382 .TP
 383 .SM ldap_mods_free(3)
 384 free array of pointers to mod structures used by ldap_modify(3)
 385 .TP
 386 .SM ldap_modrdn2(3)
 387 asynchronously modify the RDN of an entry
 388 .TP
 389 .SM ldap_modrdn2_s(3)
 390 synchronously modify the RDN of an entry
 391 .TP
 392 .SM ldap_modrdn(3)
 393 depreciated - use ldap_modrdn2(3)
 394 .TP
 395 .SM ldap_modrdn_s(3)
 396 depreciated - use ldap_modrdn2_s(3)
 397 .TP
 398 .SM ldap_msgfree(3)
 399 free results allocated by ldap_result(3)
 400 .TP
 401 .SM ldap_msgtype(3)
 402 return the message type of a message from ldap_result(3)
 403 .TP
 404 .SM ldap_msgid(3)
 405 return the message id of a message from ldap_result(3)
 406 .TP
 407 .SM ldap_search(3)
 408 asynchronously search the directory
 409 .TP
 410 .SM ldap_search_s(3)
 411 synchronously search the directory
 412 .TP
 413 .SM ldap_search_st(3)
 414 synchronously search the directory with timeout
 415 .TP
 416 .SM ldap_ufn_search_s(3)
 417 user friendly search the directory
 418 .TP
 419 .SM ldap_ufn_search_c(3)
 420 user friendly search the directory with cancel
 421 .TP
 422 .SM ldap_ufn_search_ct(3)
 423 user friendly search the directory with cancel and timeout
 424 .TP
 425 .SM ldap_ufn_setfilter(3)
 426 set filter file used by ldap_ufn(3) routines
 427 .TP
 428 .SM ldap_ufn_setprefix(3)
 429 set prefix used by ldap_ufn(3) routines
 430 .TP
 431 .SM ldap_ufn_timeout(3)
 432 set timeout used by ldap_ufn(3) routines
 433 .TP
 434 .SM ldap_is_ldap_url(3)
 435 check a URL string to see if it is an LDAP URL
 436 .TP
 437 .SM ldap_url_parse(3)
 438 break up an LDAP URL string into its components
 439 .TP
 440 .SM ldap_url_search(3)
 441 asynchronously search using an LDAP URL
 442 .TP
 443 .SM ldap_url_search_s(3)
 444 synchronously search using an LDAP URL
 445 .TP
 446 .SM ldap_url_search_st(3)
 447 synchronously search using an LDAP URL and a timeout
 448 .TP
 449 .SM ldap_init_searchprefs(3)
 450 initialize searchprefs routines from a file
 451 .TP
 452 .SM ldap_init_searchprefs_buf(3)
 453 initialize searchprefs routines from a buffer
 454 .TP
 455 .SM ldap_free_searchprefs(3)
 456 free memory allocated by searchprefs routines
 457 .TP
 458 .SM ldap_first_searchobj(3)
 459 return first searchpref object
 460 .TP
 461 .SM ldap_next_searchobj(3)
 462 return next searchpref object
 463 .TP
 464 .SM ldap_sort_entries(3)
 465 sort a list of search results
 466 .TP
 467 .SM ldap_sort_values(3)
 468 sort a list of attribute values
 469 .TP
 470 .SM ldap_sort_strcasecmp(3)
 471 case insensitive string comparison
 472 .TP
 473 .SM ldap_set_string_translators(3)
 474 set character set translation routines used by LDAP library
 475 .TP
 476 .SM ldap_t61_to_8859(3)
 477 translate from ISO-8859 characters to the T.61 characters
 478 .TP
 479 .SM ldap_8859_to_t61(3)
 480 translate from T.61 characters to the ISO-8859 characters
 481 .TP
 482 .SM ldap_translate_from_t61(3)
 483 translate from the T.61 character set to another character set
 484 .TP
 485 .SM ldap_translate_to_t61(3)
 486 translate to the T.61 character set from another character set
 487 .TP
 488 .SM ldap_enable_translation(3)
 489 enable or disable character translation for an LDAP entry result
 490 .TP
 491 .SM cldap_open(3)
 492 open a connectionless LDAP (CLDAP) session
 493 .TP
 494 .SM cldap_search_s(3)
 495 perform a search using connectionless LDAP
 496 .TP
 497 .SM cldap_setretryinfo(3)
 498 set retry and timeout information using connectionless LDAP
 499 .TP
 500 .SM cldap_close(3)
 501 terminate a connectionless LDAP session
 502 .SH SEE ALSO
 503 .BR ldapd (8),
 504 .BR slapd (8)
 505 .SH AUTHORS
 506 Tim Howes, Mark Smith, Gordon Good, Lance Sloan, and Steve Rothwell from
 507 the University of Michigan, along with help from lots of others.
 508 .SH ACKNOWLEDGEMENTS
 509 .B      OpenLDAP
 510 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 511 .B      OpenLDAP
 512 is derived from University of Michigan LDAP 3.3 Release.