[BACK]Return to ldap.3 CVS log [TXT] [DIR] Up to [OpenLDAP] / doc / man / man3

Diff for /doc/man/man3/ldap.3 between versions 1.7 and 1.26

version 1.7, 1999/09/12 02:41:47 version 1.26, 2002/06/21 05:32:54
Line 1 Line 1
 .TH LDAP 3 "10 November 1998" "OpenLDAP LDVERSION"  .TH LDAP 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$  .\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap.3,v 1.25 2002/06/13 01:59:24 kurt Exp $
 .\" Copyright 1998-1999 The OpenLDAP Foundation All Rights Reserved.  .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.  .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME  .SH NAME
 ldap - Lightweight Directory Access Protocol package  ldap - OpenLDAP Lightweight Directory Access Protocol API
   .SH LIBRARY
   OpenlDAP LDAP (libldap, -lldap)
 .SH SYNOPSIS  .SH SYNOPSIS
 .nf  .nf
 .ft B  .ft B
 #include <lber.h>  
 #include <ldap.h>  #include <ldap.h>
 .ft  .ft
 .fi  .fi
 .SH DESCRIPTION  .SH DESCRIPTION
 .LP  .LP
 The Lightweight Directory Access Protocol provides TCP/IP access to  The Lightweight Directory Access Protocol provides access to X.500
 the X.500 Directory or to a stand-alone LDAP server.  directory services.  The services may be stand\-alone or part of
 The OpenLDAP LDAP package includes a stand-alone server in  a distributed directory service.  This API supports LDAP over TCP
   (RFC2251), LDAP over SSL, and LDAP over IPC (UNIX domain sockets).
   This API supports SASL (RFC2829) and Start TLS (RFC2830).  This
   API is based upon IETF C LDAP API draft specification, a work in
   progress.
   .LP
   The OpenLDAP Software package includes a stand\-alone server in
 .BR slapd (8),  .BR slapd (8),
 an LDAP to X.500 gateway in  
 .BR ldapd (8),  
 various LDAP clients, and an LDAP client library used to provide  various LDAP clients, and an LDAP client library used to provide
 programmatic access to the LDAP protocol. This man page gives an  programmatic access to the LDAP protocol. This man page gives an
 overview of the LDAP library routines.  overview of the LDAP library routines.
 .LP  .LP
 Both synchronous and asynchronous APIs are provided.  Also included are  Both synchronous and asynchronous APIs are provided.  Also included are
 various routines to parse the results returned from these routines.  various routines to parse the results returned from these routines.
 These routines are found in the libldap.a library.  These routines are found in the \-lldap library.
 .LP  .LP
 The basic interaction is as follows.  A connection is made to an LDAP  The basic interaction is as follows.  A session handle is
 server by calling  created using
 .BR ldap_open (3).  .BR ldap_init (3)
 An LDAP bind operation is performed by calling  or
 one of  .BR ldap_initialize (3).
 .BR ldap_bind (3)  (The
 and friends.  Next, other operations are performed  .BR ldap_initialize (3)
   routine is preferred, but is not part of the draft specification.)
   The underlying session is established upon first use which is
   commonly an LDAP bind operation.  The LDAP bind operation is
   performed by calling
   .BR ldap_sasl_bind (3)
   or one of its friends.  Next, other operations are performed
 by calling one of the synchronous or asynchronous routines (e.g.,  by calling one of the synchronous or asynchronous routines (e.g.,
 .BR ldap_search_s (3)  .BR ldap_search_ext_s (3)
 or  or
 .BR ldap_search (3)  .BR ldap_search_ext (3)
 followed by  followed by
 .BR ldap_result (3)).  .BR ldap_result (3)).
 Results returned from these routines are interpreted by calling the  Results returned from these routines are interpreted by calling the
 LDAP parsing routines.  The LDAP association is terminated by calling  LDAP parsing routines such as
 .BR ldap_unbind (3).  .BR ldap_parse_result (3).
   The LDAP association and underlying connection is terminated by calling
   .BR ldap_unbind_ext (3).
 Errors can be interpreted by calling  Errors can be interpreted by calling
 .BR ldap_perror (3).  .BR ldap_err2string (3).
 The  
 .BR ldap_set_rebind_proc (3)  
 routine can be used to set a routine to be called back when an LDAP bind  
 operation needs to occur when handling a client referral.  
 .SH SEARCH FILTERS  .SH SEARCH FILTERS
 Search filters to be passed to the ldap search routines can be  Search filters to be passed to the ldap search routines are to be
 constructed by hand, or by calling the  constructed by hand and should conform to RFC 2254.
 .BR ldap_getfilter (3)  
 routines, which use the  
 .BR ldapgetfilter.conf (5)  
 file to turn a string (presumably that a user has typed) into a series  
 of search filters.  
 .SH DISPLAYING RESULTS  .SH DISPLAYING RESULTS
 Results obtained from the ldap search routines can be output by hand,  Results obtained from the ldap search routines can be output by hand,
 by calling  by calling
Line 70  and Line 74  and
 .BR ldap_next_attribute (3)  .BR ldap_next_attribute (3)
 to step through an entry's attributes, and  to step through an entry's attributes, and
 .BR ldap_get_values (3)  .BR ldap_get_values (3)
 to retrieve a given attribute's value, and then calling  to retrieve a given attribute's values.  Attribute values
 .BR printf (3)  may or may not be displayable.
 or whatever to display the values.  .SH CONTROLS
 .LP  This library supports both LDAP Version 2 and Version 3, with the Version 2
 Alternatively, the entry can be output automatically by calling  protocol selected by default.
 the  LDAP Version 3 operations can be extended through the use of controls. Controls
 .BR ldap_entry2text (3),  can be sent to a server or returned to the client with any LDAP message.
 .BR ldap_entry2text_search (3),  Extended versions of the standard routines are available for use with
 .BR ldap_entry2html (3),  controls. These routines are generally named by adding
 or  .BR _ext
 .BR ldap_entry2html_search (3)  to the regular routine's name.
 routines.  These routines look up the object  
 class of the entry they are passed in the  
 .BR ldaptemplates.conf (5)  
 file to decide which attributes to display and how to display them.  
 Output is handled via a routine passed in as a parameter.  
 .SH UNIFORM RESOURCE LOCATORS (URLS)  .SH UNIFORM RESOURCE LOCATORS (URLS)
 The  The
 .BR ldap_url (3)  .BR ldap_url (3)
 routines can be used test a URL to see if it is an LDAP URL, to parse LDAP  routines can be used to test a URL to see if it is an LDAP URL, to parse LDAP
 URLs into their component pieces, and to initiate searches directly using  URLs into their component pieces, and to initiate searches directly using
 an LDAP URL.  an LDAP URL.
 .SH USER FRIENDLY NAMING  
 The  
 .BR ldap_ufn (3)  
 routines implement a user friendly naming  
 scheme via LDAP.  This scheme allows you to look up entries  
 using fuzzy, untyped names like "mark smith, umich, us".  
 .SH CACHING  .SH CACHING
 The  The
 .BR ldap_cache (3)  .BR ldap_cache (3)
 routines implement a local client caching scheme,  routines implement a local client caching scheme,
 providing a substantial performance increase for repeated queries.  providing a substantial performance increase for repeated queries.
   Caching is experiemental.
 .SH UTILITY ROUTINES  .SH UTILITY ROUTINES
 Also provided are various utility routines.  The  Also provided are various utility routines.  The
 .BR ldap_sort (3)  .BR ldap_sort (3)
 routines are used to sort the entries and values returned via  routines are used to sort the entries and values returned via
 the ldap search routines.  The  the ldap search routines. 
 .BR ldap_friendly (3)  
 routines are  
 used to map from short two letter country codes (or other strings)  
 to longer "friendlier" names.  The  
 .BR ldap_charset (3)  
 routines can be used to translate to and from the T.61 character  
 set used for many character strings in the LDAP protocol.  
 .SH CONNECTIONLESS ACCESS  
 The  
 .BR cldap_search_s (3)  
 routine allows you to access the directory  
 via Connectionless LDAP (CLDAP), which is similar to LDAP but  
 operates over UDP, obviating the need to set up and tear down  
 a connection by calling  
 .BR ldap_open (3),  
 .BR ldap_bind (3),  
 and  
 .BR ldap_unbind (3).  
 .BR cldap_open (3)  
 should be called before using  
 .BR cldap_search_s (3).  
 All the same getfilter, parsing, and display that can be used  
 with regular LDAP routines can be used with the CLDAP routines.  
 .SH BER LIBRARY  .SH BER LIBRARY
 Also included in the distribution is a set of lightweight Basic  Also included in the distribution is a set of lightweight Basic
 Encoding Rules routines.  These routines are used by the LDAP library  Encoding Rules routines.  These routines are used by the LDAP library
 routines to encode and decode LDAP protocol elements using the  routines to encode and decode LDAP protocol elements using the
 (slightly simplified) Basic Encoding Rules defined by LDAP.  They are  (slightly simplified) Basic Encoding Rules defined by LDAP.  They are
 not normally used directly by an LDAP application program.  The  not normally used directly by an LDAP application program except
 routines provide a printf and scanf-like interface, as well as  in the handling of controls and extended operations.  The
 lower-level access.  These routines are found in the liblber.a  routines provide a printf and scanf\-like interface, as well as
 library.  lower\-level access.  These routines are discussed in
   .BR lber\-decode (3),
   .BR lber\-encode (3),
   .BR lber\-memory (3),
   and
   .BR lber\-types (3).
 .SH INDEX  .SH INDEX
 .TP 20  .TP 20
 .SM ldap_open(3)  .SM ldap_open(3)
 open a connection to an LDAP server  open a connection to an LDAP server (deprecated, use
   .BR ldap_init (3))
 .TP  .TP
 .SM ldap_init(3)  .SM ldap_init(3)
 initialize the LDAP library without opening a connection to a server  initialize the LDAP library without opening a connection to a server
 .TP  .TP
   .SM ldap_initialize(3)
   initialize the LDAP library without opening a connection to a server
   .TP
 .SM ldap_result(3)  .SM ldap_result(3)
 wait for the result from an asynchronous operation  wait for the result from an asynchronous operation
 .TP  .TP
Line 172  asynchronously bind to the directory usi Line 152  asynchronously bind to the directory usi
 .SM ldap_simple_bind_s(3)  .SM ldap_simple_bind_s(3)
 synchronously bind to the directory using simple authentication  synchronously bind to the directory using simple authentication
 .TP  .TP
 .SM ldap_kerberos_bind_s(3)  
 synchronously bind to the directory using kerberos authentication  
 .TP  
 .SM ldap_kerberos_bind1(3)  
 asynchronously bind to the LDAP server using kerberos authentication  
 .TP  
 .SM ldap_kerberos_bind1_s(3)  
 synchronously bind to the LDAP server using kerberos authentication  
 .TP  
 .SM ldap_kerberos_bind2(3)  
 asynchronously bind to the DSA using kerberos authentication  
 .TP  
 .SM ldap_kerberos_bind2_s(3)  
 synchronously bind to the DSA using kerberos authentication  
 .TP  
 .SM ldap_unbind(3)  .SM ldap_unbind(3)
 synchronously unbind from the LDAP server and close the connection  synchronously unbind from the LDAP server and close the connection
 .TP  .TP
Line 219  uncache a request Line 184  uncache a request
 set cache options  set cache options
 .TP  .TP
 .SM ldap_compare(3)  .SM ldap_compare(3)
 asynchronous compare to a directory entry  asynchronously compare to a directory entry
 .TP  .TP
 .SM ldap_compare_s(3)  .SM ldap_compare_s(3)
 synchronous compare to a directory entry  synchronously compare to a directory entry
 .TP  .TP
 .SM ldap_delete(3)  .SM ldap_delete(3)
 asynchronously delete an entry  asynchronously delete an entry
Line 230  asynchronously delete an entry Line 195  asynchronously delete an entry
 .SM ldap_delete_s(3)  .SM ldap_delete_s(3)
 synchronously delete an entry  synchronously delete an entry
 .TP  .TP
 .SM ldap_init_templates(3)  
 initialize display template routines from a file  
 .TP  
 .SM ldap_init_templates_buf(3)  
 initialize display template routines from a buffer  
 .TP  
 .SM ldap_free_templates(3)  
 free display template routine memory  
 .TP  
 .SM ldap_first_disptmpl(3)  
 get first display template  
 .TP  
 .SM ldap_next_disptmpl(3)  
 get next display template  
 .TP  
 .SM ldap_oc2template(3)  
 return template appropriate for objectclass  
 .TP  
 .SM ldap_name2template(3)  
 return named template  
 .TP  
 .SM ldap_tmplattrs(3)  
 return attributes needed by template  
 .TP  
 .SM ldap_first_tmplrow(3)  
 return first row of displayable items in a template  
 .TP  
 .SM ldap_next_tmplrow(3)  
 return next row of displayable items in a template  
 .TP  
 .SM ldap_first_tmplcol(3)  
 return first column of displayable items in a template  
 .TP  
 .SM ldap_next_tmplcol(3)  
 return next column of displayable items in a template  
 .TP  
 .SM ldap_entry2text(3)  
 display an entry as text using a display template  
 .TP  
 .SM ldap_entry2text_search(3)  
 search for and display an entry as text using a display template  
 .TP  
 .SM ldap_vals2text(3)  
 display values as text  
 .TP  
 .SM ldap_entry2html(3)  
 display an entry as HTML (HyperText Markup Language) using a display template  
 .TP  
 .SM ldap_entry2html_search(3)  
 search for and display an entry as HTML using a display template  
 .TP  
 .SM ldap_vals2html(3)  
 display values as HTML  
 .TP  
 .SM ldap_perror(3)  .SM ldap_perror(3)
 print an LDAP error indication to standard error  print an LDAP error indication to standard error
 .TP  .TP
Line 294  LDAP error indication Line 205  LDAP error indication
 extract LDAP error indication from LDAP result  extract LDAP error indication from LDAP result
 .TP  .TP
 .SM ldap_errlist(3)  .SM ldap_errlist(3)
 list of ldap errors and their meanings  list of LDAP errors and their meanings
 .TP  .TP
 .SM ldap_err2string(3)  .SM ldap_err2string(3)
 convert LDAP error indication to a string  convert LDAP error indication to a string
Line 314  return next entry in a chain of search r Line 225  return next entry in a chain of search r
 .SM ldap_count_entries(3)  .SM ldap_count_entries(3)
 return number of entries in a search result  return number of entries in a search result
 .TP  .TP
 .SM ldap_friendly_name(3)  
 map from unfriendly to friendly names  
 .TP  
 .SM ldap_free_friendlymap(3)  
 free resources used by ldap_friendly(3)  
 .TP  
 .SM ldap_get_dn(3)  .SM ldap_get_dn(3)
 extract the DN from an entry  extract the DN from an entry
 .TP  .TP
Line 327  extract the DN from an entry Line 232  extract the DN from an entry
 convert a DN into its component parts  convert a DN into its component parts
 .TP  .TP
 .SM ldap_explode_rdn(3)  .SM ldap_explode_rdn(3)
 convert a RDN into its component parts  convert an RDN into its component parts
 .TP  
 .SM ldap_explode_dns(3)  
 convert a DNS-style DN into its component parts (experimental)  
 .TP  
 .SM ldap_is_dns_dn(3)  
 check to see if a DN is a DNS-style DN (experimental)  
 .TP  
 .SM ldap_dn2ufn(3)  
 convert a DN into user friendly form  
 .TP  .TP
 .SM ldap_get_values(3)  .SM ldap_get_values(3)
 return an attribute's values  return an attribute's values
 .TP  .TP
 .SM ldap_get_values_len(3)  .SM ldap_get_values_len(3)
 return an attribute values with lengths  return an attribute's values with lengths
 .TP  .TP
 .SM ldap_value_free(3)  .SM ldap_value_free(3)
 free memory allocated by ldap_get_values(3)  free memory allocated by ldap_get_values(3)
Line 356  return number of values Line 252  return number of values
 .SM ldap_count_values_len(3)  .SM ldap_count_values_len(3)
 return number of values  return number of values
 .TP  .TP
 .SM ldap_init_getfilter(3)  
 initialize getfilter routines from a file  
 .TP  
 .SM ldap_init_getfilter_buf(3)  
 initialize getfilter routines from a buffer  
 .TP  
 .SM ldap_getfilter_free(3)  
 free resources allocated by ldap_init_getfilter(3)  
 .TP  
 .SM ldap_getfirstfilter(3)  
 return first search filter  
 .TP  
 .SM ldap_getnextfilter(3)  
 return next search filter  
 .TP  
 .SM ldap_build_filter(3)  
 construct an LDAP search filter from a pattern  
 .TP  
 .SM ldap_setfilteraffixes(3)  
 set prefix and suffix for search filters  
 .TP  
 .SM ldap_modify(3)  .SM ldap_modify(3)
 asynchronously modify an entry  asynchronously modify an entry
 .TP  .TP
Line 393  asynchronously modify the RDN of an entr Line 268  asynchronously modify the RDN of an entr
 synchronously modify the RDN of an entry  synchronously modify the RDN of an entry
 .TP  .TP
 .SM ldap_modrdn(3)  .SM ldap_modrdn(3)
 depreciated - use ldap_modrdn2(3)  deprecated - use ldap_modrdn2(3)
 .TP  .TP
 .SM ldap_modrdn_s(3)  .SM ldap_modrdn_s(3)
 depreciated - use ldap_modrdn2_s(3)  depreciated - use ldap_modrdn2_s(3)
Line 416  synchronously search the directory Line 291  synchronously search the directory
 .SM ldap_search_st(3)  .SM ldap_search_st(3)
 synchronously search the directory with timeout  synchronously search the directory with timeout
 .TP  .TP
 .SM ldap_ufn_search_s(3)  
 user friendly search the directory  
 .TP  
 .SM ldap_ufn_search_c(3)  
 user friendly search the directory with cancel  
 .TP  
 .SM ldap_ufn_search_ct(3)  
 user friendly search the directory with cancel and timeout  
 .TP  
 .SM ldap_ufn_setfilter(3)  
 set filter file used by ldap_ufn(3) routines  
 .TP  
 .SM ldap_ufn_setprefix(3)  
 set prefix used by ldap_ufn(3) routines  
 .TP  
 .SM ldap_ufn_timeout(3)  
 set timeout used by ldap_ufn(3) routines  
 .TP  
 .SM ldap_is_ldap_url(3)  .SM ldap_is_ldap_url(3)
 check a URL string to see if it is an LDAP URL  check a URL string to see if it is an LDAP URL
 .TP  .TP
 .SM ldap_url_parse(3)  .SM ldap_url_parse(3)
 break up an LDAP URL string into its components  break up an LDAP URL string into its components
 .TP  .TP
 .SM ldap_url_search(3)  
 asynchronously search using an LDAP URL  
 .TP  
 .SM ldap_url_search_s(3)  
 synchronously search using an LDAP URL  
 .TP  
 .SM ldap_url_search_st(3)  
 synchronously search using an LDAP URL and a timeout  
 .TP  
 .SM ldap_init_searchprefs(3)  
 initialize searchprefs routines from a file  
 .TP  
 .SM ldap_init_searchprefs_buf(3)  
 initialize searchprefs routines from a buffer  
 .TP  
 .SM ldap_free_searchprefs(3)  
 free memory allocated by searchprefs routines  
 .TP  
 .SM ldap_first_searchobj(3)  
 return first searchpref object  
 .TP  
 .SM ldap_next_searchobj(3)  
 return next searchpref object  
 .TP  
 .SM ldap_sort_entries(3)  .SM ldap_sort_entries(3)
 sort a list of search results  sort a list of search results
 .TP  .TP
Line 472  sort a list of attribute values Line 305  sort a list of attribute values
 .TP  .TP
 .SM ldap_sort_strcasecmp(3)  .SM ldap_sort_strcasecmp(3)
 case insensitive string comparison  case insensitive string comparison
 .TP  
 .SM ldap_set_string_translators(3)  
 set character set translation routines used by LDAP library  
 .TP  
 .SM ldap_t61_to_8859(3)  
 translate from ISO-8859 characters to the T.61 characters  
 .TP  
 .SM ldap_8859_to_t61(3)  
 translate from T.61 characters to the ISO-8859 characters  
 .TP  
 .SM ldap_translate_from_t61(3)  
 translate from the T.61 character set to another character set  
 .TP  
 .SM ldap_translate_to_t61(3)  
 translate to the T.61 character set from another character set  
 .TP  
 .SM ldap_enable_translation(3)  
 enable or disable character translation for an LDAP entry result  
 .TP  
 .SM cldap_open(3)  
 open a connectionless LDAP (CLDAP) session  
 .TP  
 .SM cldap_search_s(3)  
 perform a search using connectionless LDAP  
 .TP  
 .SM cldap_setretryinfo(3)  
 set retry and timeout information using connectionless LDAP  
 .TP  
 .SM cldap_close(3)  
 terminate a connectionless LDAP session  
 .SH SEE ALSO  .SH SEE ALSO
 .BR ldapd (8),  .BR slapd (8),
 .BR slapd (8)  .BR draft-ietf-ldapext-ldap-c-api-xx.txt \ <http://www.ietf.org>
 .SH AUTHORS  
 Tim Howes, Mark Smith, Gordon Good, Lance Sloan, and Steve Rothwell from  
 the University of Michigan, along with help from lots of others.  
 .SH ACKNOWLEDGEMENTS  .SH ACKNOWLEDGEMENTS
 .B      OpenLDAP  .B      OpenLDAP
 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).  is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 .B      OpenLDAP  .B      OpenLDAP
 is derived from University of Michigan LDAP 3.3 Release.    is derived from University of Michigan LDAP 3.3 Release.  
   .LP
   These API manual pages are based upon descriptions provided in the
   IETF C LDAP API Internet Draft, a work in progress, edited by
   Mark Smith.
Removed from v.1.7  
changed lines
  Added in v.1.26

______________
© Copyright 1998-2020, OpenLDAP Foundation, info@OpenLDAP.org