1ldap_url(3LDAP) LDAP Library Functions ldap_url(3LDAP)
2
6 ldap_url, ldap_is_ldap_url, ldap_url_parse, ldap_url_parse_nodn,
7 ldap_free_urldesc, ldap_url_search, ldap_url_search_s,
8 ldap_url_search_st, ldap_dns_to_url, ldap_dn_to_url - LDAP Uniform
9 Resource Locator functions
10
12 cc[ flag... ] file... -lldap[ library... ]
13 #include <lber.h>
14 #include <ldap.h>
15 int ldap_is_ldap_url(char *url);
17 int ldap_url_parse(char *url, LDAPURLDesc **ludpp);
20 int ldap_url_parse_nodn(char *url, LDAPURLDesc **ludpp);
23 ldap_free_urldesc(LDAPURLDesc *ludp);
26 int ldap_url_search(LDAP *ld, char *url, int attrsonly);
29 int ldap_url_search_s(LDAP *ld, char *url,
32 int attrsonly, LDAPMessage **res);
33 int ldap_url_search_st(LDAP *ld, char *url, int attrsonly,
36 struct timeval *timeout, LDAPMessage **res);
37 char *ldap_dns_to_url(LDAP *ld, char *dns_name, char *attrs,
40 char *scope, char *filter);
41 char *ldap_dn_to_url(LDAP *ld, char *dn, int nameparts);
44
47 These functions support the use of LDAP URLs (Uniform Resource Loca‐
48 tors). The following shows the formatting used for LDAP URLs.
49 ldap://hostport/dn[?attributes[?scope[?filter]]]
51 where:
55 hostport Host name with an optional :portnumber.
57 dn Base DN to be used for an LDAP search operation.
60 attributes Comma separated list of attributes to be retrieved.
63 scope One of these three strings: base one sub (default=base).
66 filter LDAP search filter as used in a call to
69 ldap_search(3LDAP).
70 The following is an example of an LDAP URL:
74 ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
76 URLs preceded URL: or wrapped in angle-brackets are tolerated. URLs can
80 also be preceded by URL: and wrapped in angle-brackets.
81 ldap_is_ldap_url() returns a non-zero value if url looks like an LDAP
84 URL (as opposed to some other kind of URL). It can be used as a quick
85 check for an LDAP URL; the ldap_url_parse() function should be used if
86 a more thorough check is needed.
87 ldap_url_parse() breaks down an LDAP URL passed in url into its compo‐
90 nent pieces. If successful, zero is returned, an LDAP URL description
91 is allocated, filled in, and ludpp is set to point to it. See RETURN
92 VALUES for values returned upon error.
93 ldap_url_parse_nodn() acts just like ldap_url_parse() but does not
96 require dn in the LDAP URL.
97 ldap_free_urldesc() should be called to free an LDAP URL description
100 that was obtained from a call to ldap_url_parse().
101 ldap_url_search() initiates an asynchronous LDAP search based on the
104 contents of the url string. This function acts just like
105 ldap_search(3LDAP) except that many search parameters are pulled out of
106 the URL.
107 ldap_url_search_s() performs a synchronous LDAP search based on the
110 contents of the url string. This function acts just like
111 ldap_search_s(3LDAP) except that many search parameters are pulled out
112 of the URL.
113 ldap_url_search_st() performs a synchronous LDAP URL search with a
116 specified timeout. This function acts just like ldap_search_st(3LDAP)
117 except that many search parameters are pulled out of the URL.
118 ldap_dns_to_url() locates the LDAP URL associated with a DNS domain
121 name. The supplied DNS domain name is converted into a distinguished
122 name. The directory entry specified by that distinguished name is
123 searched for a labeled URI attribute. If successful then the corre‐
124 sponding LDAP URL is returned. If unsuccessful then that entry's parent
125 is searched and so on until the target distinguished name is reduced to
126 only two nameparts. If dns_name is NULL then the environment variable
127 LOCALDOMAIN is used. If attrs is not NULL then it is appended to the
128 URL's attribute list. If scope is not NULL then it overrides the URL's
129 scope. If filter is not NULL then it is merged with the URL's filter.
130 If an error is encountered then zero is returned, otherwise a string
131 URL is returned. The caller should free the returned string if it is
132 non-zero.
133 ldap_dn_to_url() locates the LDAP URL associated with a distinguished
136 name. The number of nameparts in the supplied distinguished name must
137 be provided. The specified directory entry is searched for a labeledURI
138 attribute. If successful then the LDAP URL is returned. If unsuccessful
139 then that entry's parent is searched and so on until the target distin‐
140 guished name is reduced to only two nameparts. If an error is encoun‐
141 tered then zero is returned, otherwise a string URL is returned. The
142 caller should free the returned string if it is non-zero.
143
145 Upon error, one of these values is returned for ldap_url_parse():
146 LDAP_URL_ERR_BADSCOPE URL scope string is invalid.
148 LDAP_URL_ERR_HOSTPORT URL hostport is invalid.
151 LDAP_URL_ERR_MEM Can't allocate memory space.
154 LDAP_URL_ERR_NODN URL has no DN (required).
157 LDAP_URL_ERR_NOTLDAP URL doesn't begin with ldap://.
160
163 See attributes(5) for a description of the following attributes:
164 ┌─────────────────────────────┬─────────────────────────────┐
169 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
170 │Interface Stability │Evolving │
171 └─────────────────────────────┴─────────────────────────────┘
172
174 ldap(3LDAP), ldap_search(3LDAP), attributes(5)
175 An LDAP URL Format, Tim Howes and Mark Smith, December 1995. Internet
178 Draft (work in progress). Currently available at this URL.
179 ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt
181SunOS 5.11 02 Dec 2003 ldap_url(3LDAP)