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

   1 .TH LDAP 3 "13 May 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 USER FRIENDLY NAMING
  95 The
  96 .BR ldap_ufn (3)
  97 routines implement a user friendly naming
  98 scheme via LDAP.  This scheme allows you to look up entries
  99 using fuzzy, untyped names like "john smith, example corp, ca, us".
 100 .SH CACHING
 101 The
 102 .BR ldap_cache (3)
 103 routines implement a local client caching scheme,
 104 providing a substantial performance increase for repeated queries.
 105 .SH UTILITY ROUTINES
 106 Also provided are various utility routines.  The
 107 .BR ldap_sort (3)
 108 routines are used to sort the entries and values returned via
 109 the ldap search routines.  The
 110 .BR ldap_friendly (3)
 111 routines are
 112 used to map from short two letter country codes (or other strings)
 113 to longer "friendlier" names.
 114 .SH CONNECTIONLESS ACCESS
 115 The
 116 .BR cldap_search_s (3)
 117 routine allows you to access the directory
 118 via Connectionless LDAP (CLDAP), which is similar to LDAP but
 119 operates over UDP, obviating the need to set up and tear down
 120 a connection by calling
 121 .BR ldap_open (3),
 122 .BR ldap_bind (3),
 123 and
 124 .BR ldap_unbind (3).
 125 .BR cldap_open (3)
 126 should be called before using
 127 .BR cldap_search_s (3).
 128 All the same getfilter, parsing, and display that can be used
 129 with regular LDAP routines can be used with the CLDAP routines.
 130 .SH BER LIBRARY
 131 Also included in the distribution is a set of lightweight Basic
 132 Encoding Rules routines.  These routines are used by the LDAP library
 133 routines to encode and decode LDAP protocol elements using the
 134 (slightly simplified) Basic Encoding Rules defined by LDAP.  They are
 135 not normally used directly by an LDAP application program excepting
 136 in the handling of controls and extended operations.  The
 137 routines provide a printf and scanf-like interface, as well as
 138 lower-level access.  These routines are found in the -llber
 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_dn2ufn(3)
 330 convert a DN into user friendly form
 331 .TP
 332 .SM ldap_get_values(3)
 333 return an attribute's values
 334 .TP
 335 .SM ldap_get_values_len(3)
 336 return an attribute values with lengths
 337 .TP
 338 .SM ldap_value_free(3)
 339 free memory allocated by ldap_get_values(3)
 340 .TP
 341 .SM ldap_value_free_len(3)
 342 free memory allocated by ldap_get_values_len(3)
 343 .TP
 344 .SM ldap_count_values(3)
 345 return number of values
 346 .TP
 347 .SM ldap_count_values_len(3)
 348 return number of values
 349 .TP
 350 .SM ldap_init_getfilter(3)
 351 initialize getfilter routines from a file
 352 .TP
 353 .SM ldap_init_getfilter_buf(3)
 354 initialize getfilter routines from a buffer
 355 .TP
 356 .SM ldap_getfilter_free(3)
 357 free resources allocated by ldap_init_getfilter(3)
 358 .TP
 359 .SM ldap_getfirstfilter(3)
 360 return first search filter
 361 .TP
 362 .SM ldap_getnextfilter(3)
 363 return next search filter
 364 .TP
 365 .SM ldap_build_filter(3)
 366 construct an LDAP search filter from a pattern
 367 .TP
 368 .SM ldap_setfilteraffixes(3)
 369 set prefix and suffix for search filters
 370 .TP
 371 .SM ldap_modify(3)
 372 asynchronously modify an entry
 373 .TP
 374 .SM ldap_modify_s(3)
 375 synchronously modify an entry
 376 .TP
 377 .SM ldap_mods_free(3)
 378 free array of pointers to mod structures used by ldap_modify(3)
 379 .TP
 380 .SM ldap_modrdn2(3)
 381 asynchronously modify the RDN of an entry
 382 .TP
 383 .SM ldap_modrdn2_s(3)
 384 synchronously modify the RDN of an entry
 385 .TP
 386 .SM ldap_modrdn(3)
 387 depreciated - use ldap_modrdn2(3)
 388 .TP
 389 .SM ldap_modrdn_s(3)
 390 depreciated - use ldap_modrdn2_s(3)
 391 .TP
 392 .SM ldap_msgfree(3)
 393 free results allocated by ldap_result(3)
 394 .TP
 395 .SM ldap_msgtype(3)
 396 return the message type of a message from ldap_result(3)
 397 .TP
 398 .SM ldap_msgid(3)
 399 return the message id of a message from 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 cldap_open(3)
 468 open a connectionless LDAP (CLDAP) session
 469 .TP
 470 .SM cldap_search_s(3)
 471 perform a search using connectionless LDAP
 472 .TP
 473 .SM cldap_setretryinfo(3)
 474 set retry and timeout information using connectionless LDAP
 475 .TP
 476 .SM cldap_close(3)
 477 terminate a connectionless LDAP session
 478 .SH SEE ALSO
 479 .BR slapd (8)
 480 .SH ACKNOWLEDGEMENTS
 481 .B      OpenLDAP
 482 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 483 .B      OpenLDAP
 484 is derived from University of Michigan LDAP 3.3 Release.