2001-08-25 04:17:23 +08:00
|
|
|
.TH LDAP 3 "1 August 2001" "OpenLDAP LDVERSION"
|
1999-09-12 12:41:47 +08:00
|
|
|
.\" $OpenLDAP$
|
2000-05-13 10:47:56 +08:00
|
|
|
.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
|
1999-09-12 12:41:47 +08:00
|
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
1998-08-09 08:43:13 +08:00
|
|
|
.SH NAME
|
2000-06-16 14:44:25 +08:00
|
|
|
ldap - OpenLDAP Lightweight Directory Access Protocol API
|
1998-08-09 08:43:13 +08:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.ft B
|
|
|
|
#include <ldap.h>
|
|
|
|
.ft
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
2001-09-26 01:51:36 +08:00
|
|
|
The Lightweight Directory Access Protocol provides access to X.500
|
|
|
|
directory services. The services may be stand\-alone or part of
|
|
|
|
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.
|
2000-07-22 09:59:08 +08:00
|
|
|
.LP
|
2001-08-25 04:17:23 +08:00
|
|
|
The OpenLDAP Software package includes a stand-alone server in
|
1998-08-09 08:43:13 +08:00
|
|
|
.BR slapd (8),
|
|
|
|
various LDAP clients, and an LDAP client library used to provide
|
|
|
|
programmatic access to the LDAP protocol. This man page gives an
|
|
|
|
overview of the LDAP library routines.
|
|
|
|
.LP
|
|
|
|
Both synchronous and asynchronous APIs are provided. Also included are
|
|
|
|
various routines to parse the results returned from these routines.
|
2000-06-16 14:44:25 +08:00
|
|
|
These routines are found in the \-lldap library.
|
1998-08-09 08:43:13 +08:00
|
|
|
.LP
|
2000-07-22 09:59:08 +08:00
|
|
|
The basic interaction is as follows. A session handle associated
|
|
|
|
with created using
|
|
|
|
.BR ldap_init (3).
|
|
|
|
The underlying session is established upon first use which is
|
|
|
|
commonly an LDAP bind operation. The LDAP bind operation is
|
|
|
|
performed by calling one of
|
|
|
|
.BR ldap_sasl_bind (3)
|
1998-08-09 08:43:13 +08:00
|
|
|
and friends. Next, other operations are performed
|
|
|
|
by calling one of the synchronous or asynchronous routines (e.g.,
|
2000-07-22 09:59:08 +08:00
|
|
|
.BR ldap_search_ext_s (3)
|
1998-08-09 08:43:13 +08:00
|
|
|
or
|
2000-07-22 09:59:08 +08:00
|
|
|
.BR ldap_search_ext (3)
|
1998-08-09 08:43:13 +08:00
|
|
|
followed by
|
|
|
|
.BR ldap_result (3)).
|
|
|
|
Results returned from these routines are interpreted by calling the
|
2000-07-22 09:59:08 +08:00
|
|
|
LDAP parsing routines such as
|
|
|
|
.BR ldap_parse_result (3).
|
|
|
|
The LDAP association and underlying connection is terminated by calling
|
|
|
|
.BR ldap_unbind_ext (3).
|
1998-08-09 08:43:13 +08:00
|
|
|
Errors can be interpreted by calling
|
2000-07-22 09:59:08 +08:00
|
|
|
.BR ldap_err2string (3).
|
1998-08-09 08:43:13 +08:00
|
|
|
.SH SEARCH FILTERS
|
|
|
|
Search filters to be passed to the ldap search routines can be
|
|
|
|
constructed by hand, or by calling the
|
|
|
|
.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
|
|
|
|
Results obtained from the ldap search routines can be output by hand,
|
|
|
|
by calling
|
|
|
|
.BR ldap_first_entry (3)
|
|
|
|
and
|
|
|
|
.BR ldap_next_entry (3)
|
|
|
|
to step through
|
|
|
|
the entries returned,
|
|
|
|
.BR ldap_first_attribute (3)
|
|
|
|
and
|
|
|
|
.BR ldap_next_attribute (3)
|
|
|
|
to step through an entry's attributes, and
|
|
|
|
.BR ldap_get_values (3)
|
2000-07-22 09:59:08 +08:00
|
|
|
to retrieve a given attribute's value. Attribute values
|
|
|
|
may or may not be displayable.
|
1998-08-09 08:43:13 +08:00
|
|
|
.LP
|
|
|
|
Alternatively, the entry can be output automatically by calling
|
|
|
|
the
|
|
|
|
.BR ldap_entry2text (3),
|
|
|
|
.BR ldap_entry2text_search (3),
|
|
|
|
.BR ldap_entry2html (3),
|
|
|
|
or
|
|
|
|
.BR ldap_entry2html_search (3)
|
|
|
|
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)
|
|
|
|
The
|
|
|
|
.BR ldap_url (3)
|
|
|
|
routines can be used 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
|
|
|
|
an LDAP URL.
|
|
|
|
.SH CACHING
|
|
|
|
The
|
|
|
|
.BR ldap_cache (3)
|
|
|
|
routines implement a local client caching scheme,
|
|
|
|
providing a substantial performance increase for repeated queries.
|
2001-08-25 04:17:23 +08:00
|
|
|
Caching is experiemental.
|
1998-08-09 08:43:13 +08:00
|
|
|
.SH UTILITY ROUTINES
|
|
|
|
Also provided are various utility routines. The
|
|
|
|
.BR ldap_sort (3)
|
|
|
|
routines are used to sort the entries and values returned via
|
|
|
|
the ldap search routines. The
|
|
|
|
.BR ldap_friendly (3)
|
|
|
|
routines are
|
|
|
|
used to map from short two letter country codes (or other strings)
|
2000-06-16 14:44:25 +08:00
|
|
|
to longer "friendlier" names.
|
1998-08-09 08:43:13 +08:00
|
|
|
.SH BER LIBRARY
|
|
|
|
Also included in the distribution is a set of lightweight Basic
|
|
|
|
Encoding Rules routines. These routines are used by the LDAP library
|
|
|
|
routines to encode and decode LDAP protocol elements using the
|
|
|
|
(slightly simplified) Basic Encoding Rules defined by LDAP. They are
|
2001-08-25 04:17:23 +08:00
|
|
|
not normally used directly by an LDAP application program except
|
2000-07-22 09:59:08 +08:00
|
|
|
in the handling of controls and extended operations. The
|
1998-08-09 08:43:13 +08:00
|
|
|
routines provide a printf and scanf-like interface, as well as
|
2000-07-22 09:59:08 +08:00
|
|
|
lower-level access. These routines are found in the -llber
|
1998-08-09 08:43:13 +08:00
|
|
|
library.
|
|
|
|
.SH INDEX
|
|
|
|
.TP 20
|
|
|
|
.SM ldap_open(3)
|
|
|
|
open a connection to an LDAP server
|
|
|
|
.TP
|
|
|
|
.SM ldap_init(3)
|
|
|
|
initialize the LDAP library without opening a connection to a server
|
|
|
|
.TP
|
|
|
|
.SM ldap_result(3)
|
|
|
|
wait for the result from an asynchronous operation
|
|
|
|
.TP
|
|
|
|
.SM ldap_abandon(3)
|
|
|
|
abandon (abort) an asynchronous operation
|
|
|
|
.TP
|
|
|
|
.SM ldap_add(3)
|
|
|
|
asynchronously add an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_add_s(3)
|
|
|
|
synchronously add an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_bind(3)
|
|
|
|
asynchronously bind to the directory
|
|
|
|
.TP
|
|
|
|
.SM ldap_bind_s(3)
|
|
|
|
synchronously bind to the directory
|
|
|
|
.TP
|
|
|
|
.SM ldap_simple_bind(3)
|
|
|
|
asynchronously bind to the directory using simple authentication
|
|
|
|
.TP
|
|
|
|
.SM ldap_simple_bind_s(3)
|
|
|
|
synchronously bind to the directory using simple authentication
|
|
|
|
.TP
|
|
|
|
.SM ldap_unbind(3)
|
|
|
|
synchronously unbind from the LDAP server and close the connection
|
|
|
|
.TP
|
|
|
|
.SM ldap_unbind_s(3)
|
|
|
|
equivalent to
|
|
|
|
.BR ldap_unbind (3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_memfree (3)
|
1998-12-23 03:08:27 +08:00
|
|
|
dispose of memory allocated by LDAP routines.
|
1998-08-09 08:43:13 +08:00
|
|
|
.TP
|
|
|
|
.SM ldap_enable_cache(3)
|
|
|
|
enable LDAP client caching
|
|
|
|
.TP
|
|
|
|
.SM ldap_disable_cache(3)
|
|
|
|
disable LDAP client caching
|
|
|
|
.TP
|
|
|
|
.SM ldap_destroy_cache(3)
|
|
|
|
disable LDAP client caching and destroy cache contents
|
|
|
|
.TP
|
|
|
|
.SM ldap_flush_cache(3)
|
|
|
|
flush LDAP client cache
|
|
|
|
.TP
|
|
|
|
.SM ldap_uncache_entry(3)
|
|
|
|
uncache requests pertaining to an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_uncache_request(3)
|
|
|
|
uncache a request
|
|
|
|
.TP
|
|
|
|
.SM ldap_set_cache_options(3)
|
|
|
|
set cache options
|
|
|
|
.TP
|
|
|
|
.SM ldap_compare(3)
|
|
|
|
asynchronous compare to a directory entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_compare_s(3)
|
|
|
|
synchronous compare to a directory entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_delete(3)
|
|
|
|
asynchronously delete an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_delete_s(3)
|
|
|
|
synchronously delete an entry
|
|
|
|
.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)
|
|
|
|
print an LDAP error indication to standard error
|
|
|
|
.TP
|
|
|
|
.SM ld_errno(3)
|
|
|
|
LDAP error indication
|
|
|
|
.TP
|
|
|
|
.SM ldap_result2error(3)
|
|
|
|
extract LDAP error indication from LDAP result
|
|
|
|
.TP
|
|
|
|
.SM ldap_errlist(3)
|
|
|
|
list of ldap errors and their meanings
|
|
|
|
.TP
|
|
|
|
.SM ldap_err2string(3)
|
|
|
|
convert LDAP error indication to a string
|
|
|
|
.TP
|
|
|
|
.SM ldap_first_attribute(3)
|
|
|
|
return first attribute name in an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_next_attribute(3)
|
|
|
|
return next attribute name in an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_first_entry(3)
|
|
|
|
return first entry in a chain of search results
|
|
|
|
.TP
|
|
|
|
.SM ldap_next_entry(3)
|
|
|
|
return next entry in a chain of search results
|
|
|
|
.TP
|
|
|
|
.SM ldap_count_entries(3)
|
|
|
|
return number of entries in a search result
|
|
|
|
.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)
|
|
|
|
extract the DN from an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_explode_dn(3)
|
|
|
|
convert a DN into its component parts
|
|
|
|
.TP
|
1998-11-05 07:28:51 +08:00
|
|
|
.SM ldap_explode_rdn(3)
|
|
|
|
convert a RDN into its component parts
|
|
|
|
.TP
|
1998-08-09 08:43:13 +08:00
|
|
|
.SM ldap_get_values(3)
|
|
|
|
return an attribute's values
|
|
|
|
.TP
|
|
|
|
.SM ldap_get_values_len(3)
|
|
|
|
return an attribute values with lengths
|
|
|
|
.TP
|
|
|
|
.SM ldap_value_free(3)
|
|
|
|
free memory allocated by ldap_get_values(3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_value_free_len(3)
|
|
|
|
free memory allocated by ldap_get_values_len(3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_count_values(3)
|
|
|
|
return number of values
|
|
|
|
.TP
|
|
|
|
.SM ldap_count_values_len(3)
|
|
|
|
return number of values
|
|
|
|
.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)
|
|
|
|
asynchronously modify an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_modify_s(3)
|
|
|
|
synchronously modify an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_mods_free(3)
|
|
|
|
free array of pointers to mod structures used by ldap_modify(3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_modrdn2(3)
|
|
|
|
asynchronously modify the RDN of an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_modrdn2_s(3)
|
|
|
|
synchronously modify the RDN of an entry
|
|
|
|
.TP
|
|
|
|
.SM ldap_modrdn(3)
|
|
|
|
depreciated - use ldap_modrdn2(3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_modrdn_s(3)
|
|
|
|
depreciated - use ldap_modrdn2_s(3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_msgfree(3)
|
|
|
|
free results allocated by ldap_result(3)
|
|
|
|
.TP
|
1998-11-05 07:51:31 +08:00
|
|
|
.SM ldap_msgtype(3)
|
|
|
|
return the message type of a message from ldap_result(3)
|
|
|
|
.TP
|
|
|
|
.SM ldap_msgid(3)
|
|
|
|
return the message id of a message from ldap_result(3)
|
|
|
|
.TP
|
1998-08-09 08:43:13 +08:00
|
|
|
.SM ldap_search(3)
|
|
|
|
asynchronously search the directory
|
|
|
|
.TP
|
|
|
|
.SM ldap_search_s(3)
|
|
|
|
synchronously search the directory
|
|
|
|
.TP
|
|
|
|
.SM ldap_search_st(3)
|
|
|
|
synchronously search the directory with timeout
|
|
|
|
.TP
|
|
|
|
.SM ldap_is_ldap_url(3)
|
|
|
|
check a URL string to see if it is an LDAP URL
|
|
|
|
.TP
|
|
|
|
.SM ldap_url_parse(3)
|
|
|
|
break up an LDAP URL string into its components
|
|
|
|
.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)
|
|
|
|
sort a list of search results
|
|
|
|
.TP
|
|
|
|
.SM ldap_sort_values(3)
|
|
|
|
sort a list of attribute values
|
|
|
|
.TP
|
|
|
|
.SM ldap_sort_strcasecmp(3)
|
|
|
|
case insensitive string comparison
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR slapd (8)
|
2001-09-26 01:51:36 +08:00
|
|
|
.BR draft-ietf-ldapext-ldap-c-api-xx.txt \ <http://www.ietf.org>
|
1998-10-25 09:41:42 +08:00
|
|
|
.SH ACKNOWLEDGEMENTS
|
|
|
|
.B OpenLDAP
|
|
|
|
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
|
|
|
|
.B OpenLDAP
|
|
|
|
is derived from University of Michigan LDAP 3.3 Release.
|
2001-09-26 01:51:36 +08:00
|
|
|
.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.
|