1ldap_url(3LDAP)             LDAP Library Functions             ldap_url(3LDAP)
2
3
4

NAME

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

SYNOPSIS

12       cc[ flag... ] file... -lldap[ library... ]
13       #include <lber.h>
14       #include <ldap.h>
15
16       int ldap_is_ldap_url(char *url);
17
18
19       int ldap_url_parse(char *url, LDAPURLDesc **ludpp);
20
21
22       int ldap_url_parse_nodn(char *url, LDAPURLDesc **ludpp);
23
24
25       ldap_free_urldesc(LDAPURLDesc *ludp);
26
27
28       int ldap_url_search(LDAP *ld, char *url, int attrsonly);
29
30
31       int ldap_url_search_s(LDAP *ld, char *url,
32            int attrsonly, LDAPMessage **res);
33
34
35       int ldap_url_search_st(LDAP *ld, char *url, int attrsonly,
36            struct timeval *timeout, LDAPMessage **res);
37
38
39       char *ldap_dns_to_url(LDAP *ld, char *dns_name, char *attrs,
40            char *scope, char *filter);
41
42
43       char *ldap_dn_to_url(LDAP *ld, char *dn, int nameparts);
44
45

DESCRIPTION

47       These functions support the use of LDAP URLs  (Uniform  Resource  Loca‐
48       tors). The following shows the formatting used for LDAP URLs.
49
50         ldap://hostport/dn[?attributes[?scope[?filter]]]
51
52
53
54       where:
55
56       hostport      Host name with an optional :portnumber.
57
58
59       dn            Base DN to be used for an LDAP search operation.
60
61
62       attributes    Comma separated list of attributes to be retrieved.
63
64
65       scope         One of these three strings: base one sub (default=base).
66
67
68       filter        LDAP    search    filter   as   used   in   a   call   to
69                     ldap_search(3LDAP).
70
71
72
73       The following is an example of an LDAP URL:
74
75         ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
76
77
78
79       URLs preceded URL: or wrapped in angle-brackets are tolerated. URLs can
80       also be preceded by URL: and wrapped in angle-brackets.
81
82
83       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
88
89       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
94
95       ldap_url_parse_nodn()  acts  just  like  ldap_url_parse()  but does not
96       require dn in the LDAP URL.
97
98
99       ldap_free_urldesc() should be called to free an  LDAP  URL  description
100       that was obtained from a call to ldap_url_parse().
101
102
103       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
108
109       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
114
115       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
119
120       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
134
135       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

RETURN VALUES

145       Upon error, one of these values is returned for ldap_url_parse():
146
147       LDAP_URL_ERR_BADSCOPE    URL scope string is invalid.
148
149
150       LDAP_URL_ERR_HOSTPORT    URL hostport is invalid.
151
152
153       LDAP_URL_ERR_MEM         Can't allocate memory space.
154
155
156       LDAP_URL_ERR_NODN        URL has no DN (required).
157
158
159       LDAP_URL_ERR_NOTLDAP     URL doesn't begin with ldap://.
160
161

ATTRIBUTES

163       See attributes(5) for a description of the following attributes:
164
165
166
167
168       ┌─────────────────────────────┬─────────────────────────────┐
169       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
170       │Interface Stability          │Evolving                     │
171       └─────────────────────────────┴─────────────────────────────┘
172

SEE ALSO

174       ldap(3LDAP), ldap_search(3LDAP), attributes(5)
175
176
177       An LDAP URL Format, Tim Howes and Mark Smith, December  1995.  Internet
178       Draft (work in progress). Currently available at this URL.
179
180         ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt
181
182
183
184
185SunOS 5.11                        02 Dec 2003                  ldap_url(3LDAP)
Impressum