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

   1 .TH LDAP 3  "13 November 1995" "U-M LDAP 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 University of Michigan 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 (this is only used on the
 196 Microsoft Windows platforms; use
 197 .BR free (3)
 198 on all other platforms).
 199 .TP
 200 .SM ldap_enable_cache(3)
 201 enable LDAP client caching
 202 .TP
 203 .SM ldap_disable_cache(3)
 204 disable LDAP client caching
 205 .TP
 206 .SM ldap_destroy_cache(3)
 207 disable LDAP client caching and destroy cache contents
 208 .TP
 209 .SM ldap_flush_cache(3)
 210 flush LDAP client cache
 211 .TP
 212 .SM ldap_uncache_entry(3)
 213 uncache requests pertaining to an entry
 214 .TP
 215 .SM ldap_uncache_request(3)
 216 uncache a request
 217 .TP
 218 .SM ldap_set_cache_options(3)
 219 set cache options
 220 .TP
 221 .SM ldap_compare(3)
 222 asynchronous compare to a directory entry
 223 .TP
 224 .SM ldap_compare_s(3)
 225 synchronous compare to a directory entry
 226 .TP
 227 .SM ldap_delete(3)
 228 asynchronously delete an entry
 229 .TP
 230 .SM ldap_delete_s(3)
 231 synchronously delete an entry
 232 .TP
 233 .SM ldap_init_templates(3)
 234 initialize display template routines from a file
 235 .TP
 236 .SM ldap_init_templates_buf(3)
 237 initialize display template routines from a buffer
 238 .TP
 239 .SM ldap_free_templates(3)
 240 free display template routine memory
 241 .TP
 242 .SM ldap_first_disptmpl(3)
 243 get first display template
 244 .TP
 245 .SM ldap_next_disptmpl(3)
 246 get next display template
 247 .TP
 248 .SM ldap_oc2template(3)
 249 return template appropriate for objectclass
 250 .TP
 251 .SM ldap_name2template(3)
 252 return named template
 253 .TP
 254 .SM ldap_tmplattrs(3)
 255 return attributes needed by template
 256 .TP
 257 .SM ldap_first_tmplrow(3)
 258 return first row of displayable items in a template
 259 .TP
 260 .SM ldap_next_tmplrow(3)
 261 return next row of displayable items in a template
 262 .TP
 263 .SM ldap_first_tmplcol(3)
 264 return first column of displayable items in a template
 265 .TP
 266 .SM ldap_next_tmplcol(3)
 267 return next column of displayable items in a template
 268 .TP
 269 .SM ldap_entry2text(3)
 270 display an entry as text using a display template
 271 .TP
 272 .SM ldap_entry2text_search(3)
 273 search for and display an entry as text using a display template
 274 .TP
 275 .SM ldap_vals2text(3)
 276 display values as text
 277 .TP
 278 .SM ldap_entry2html(3)
 279 display an entry as HTML (HyperText Markup Language) using a display template
 280 .TP
 281 .SM ldap_entry2html_search(3)
 282 search for and display an entry as HTML using a display template
 283 .TP
 284 .SM ldap_vals2html(3)
 285 display values as HTML
 286 .TP
 287 .SM ldap_perror(3)
 288 print an LDAP error indication to standard error
 289 .TP
 290 .SM ld_errno(3)
 291 LDAP error indication
 292 .TP
 293 .SM ldap_result2error(3)
 294 extract LDAP error indication from LDAP result
 295 .TP
 296 .SM ldap_errlist(3)
 297 list of ldap errors and their meanings
 298 .TP
 299 .SM ldap_err2string(3)
 300 convert LDAP error indication to a string
 301 .TP
 302 .SM ldap_first_attribute(3)
 303 return first attribute name in an entry
 304 .TP
 305 .SM ldap_next_attribute(3)
 306 return next attribute name in an entry
 307 .TP
 308 .SM ldap_first_entry(3)
 309 return first entry in a chain of search results
 310 .TP
 311 .SM ldap_next_entry(3)
 312 return next entry in a chain of search results
 313 .TP
 314 .SM ldap_count_entries(3)
 315 return number of entries in a search result
 316 .TP
 317 .SM ldap_friendly_name(3)
 318 map from unfriendly to friendly names
 319 .TP
 320 .SM ldap_free_friendlymap(3)
 321 free resources used by ldap_friendly(3)
 322 .TP
 323 .SM ldap_get_dn(3)
 324 extract the DN from an entry
 325 .TP
 326 .SM ldap_explode_dn(3)
 327 convert a DN 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_search(3)
 402 asynchronously search the directory
 403 .TP
 404 .SM ldap_search_s(3)
 405 synchronously search the directory
 406 .TP
 407 .SM ldap_search_st(3)
 408 synchronously search the directory with timeout
 409 .TP
 410 .SM ldap_ufn_search_s(3)
 411 user friendly search the directory
 412 .TP
 413 .SM ldap_ufn_search_c(3)
 414 user friendly search the directory with cancel
 415 .TP
 416 .SM ldap_ufn_search_ct(3)
 417 user friendly search the directory with cancel and timeout
 418 .TP
 419 .SM ldap_ufn_setfilter(3)
 420 set filter file used by ldap_ufn(3) routines
 421 .TP
 422 .SM ldap_ufn_setprefix(3)
 423 set prefix used by ldap_ufn(3) routines
 424 .TP
 425 .SM ldap_ufn_timeout(3)
 426 set timeout used by ldap_ufn(3) routines
 427 .TP
 428 .SM ldap_is_ldap_url(3)
 429 check a URL string to see if it is an LDAP URL
 430 .TP
 431 .SM ldap_url_parse(3)
 432 break up an LDAP URL string into its components
 433 .TP
 434 .SM ldap_url_search(3)
 435 asynchronously search using an LDAP URL
 436 .TP
 437 .SM ldap_url_search_s(3)
 438 synchronously search using an LDAP URL
 439 .TP
 440 .SM ldap_url_search_st(3)
 441 synchronously search using an LDAP URL and a timeout
 442 .TP
 443 .SM ldap_init_searchprefs(3)
 444 initialize searchprefs routines from a file
 445 .TP
 446 .SM ldap_init_searchprefs_buf(3)
 447 initialize searchprefs routines from a buffer
 448 .TP
 449 .SM ldap_free_searchprefs(3)
 450 free memory allocated by searchprefs routines
 451 .TP
 452 .SM ldap_first_searchobj(3)
 453 return first searchpref object
 454 .TP
 455 .SM ldap_next_searchobj(3)
 456 return next searchpref object
 457 .TP
 458 .SM ldap_sort_entries(3)
 459 sort a list of search results
 460 .TP
 461 .SM ldap_sort_values(3)
 462 sort a list of attribute values
 463 .TP
 464 .SM ldap_sort_strcasecmp(3)
 465 case insensitive string comparison
 466 .TP
 467 .SM ldap_set_string_translators(3)
 468 set character set translation routines used by LDAP library
 469 .TP
 470 .SM ldap_t61_to_8859(3)
 471 translate from ISO-8859 characters to the T.61 characters
 472 .TP
 473 .SM ldap_8859_to_t61(3)
 474 translate from T.61 characters to the ISO-8859 characters
 475 .TP
 476 .SM ldap_translate_from_t61(3)
 477 translate from the T.61 character set to another character set
 478 .TP
 479 .SM ldap_translate_to_t61(3)
 480 translate to the T.61 character set from another character set
 481 .TP
 482 .SM ldap_enable_translation(3)
 483 enable or disable character translation for an LDAP entry result
 484 .TP
 485 .SM cldap_open(3)
 486 open a connectionless LDAP (CLDAP) session
 487 .TP
 488 .SM cldap_search_s(3)
 489 perform a search using connectionless LDAP
 490 .TP
 491 .SM cldap_setretryinfo(3)
 492 set retry and timeout information using connectionless LDAP
 493 .TP
 494 .SM cldap_close(3)
 495 terminate a connectionless LDAP session
 496 .SH SEE ALSO
 497 .BR ldapd (8),
 498 .BR slapd (8)
 499 .SH AUTHORS
 500 Tim Howes, Mark Smith, Gordon Good, Lance Sloan, and Steve Rothwell from
 501 the University of Michigan, along with help from lots of others.