usr/src/man/man3ldap/ldap_url.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_URL 3LDAP "Dec 02, 2003"
   8 .SH NAME
   9 ldap_url, ldap_is_ldap_url, ldap_url_parse, ldap_url_parse_nodn,
  10 ldap_free_urldesc, ldap_url_search, ldap_url_search_s, ldap_url_search_st,
  11 ldap_dns_to_url, ldap_dn_to_url \- LDAP Uniform Resource Locator functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  16 #include <lber.h>
  17 #include <ldap.h>
  18
  19 \fBint\fR \fBldap_is_ldap_url\fR(\fBchar\fR \fI*url\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBldap_url_parse\fR(\fBchar\fR \fI*url\fR, \fBLDAPURLDesc\fR \fI**ludpp\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBldap_url_parse_nodn\fR(\fBchar\fR \fI*url\fR, \fBLDAPURLDesc\fR \fI**ludpp\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fB\fR\fBldap_free_urldesc\fR(\fBLDAPURLDesc\fR \fI*ludp\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBldap_url_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*url\fR, \fBint\fR \fIattrsonly\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBint\fR \fBldap_url_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*url\fR,
  45      \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBldap_url_search_st\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*url\fR, \fBint\fR \fIattrsonly\fR,
  51      \fBstruct timeval\fR \fI*timeout\fR, \fBLDAPMessage\fR \fI**res\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBchar *\fR\fBldap_dns_to_url\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dns_name\fR, \fBchar\fR \fI*attrs\fR,
  57      \fBchar\fR \fI*scope\fR, \fBchar\fR \fI*filter\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBchar *\fR\fBldap_dn_to_url\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBint\fR \fInameparts\fR);
  63 .fi
  64
  65 .SH DESCRIPTION
  66 .sp
  67 .LP
  68 These functions support the use of LDAP URLs (Uniform Resource Locators). The
  69 following shows the formatting used for LDAP URLs.
  70 .sp
  71 .in +2
  72 .nf
  73 \fBldap://\fR\fIhostport\fR\fB/\fR\fIdn\fR[\fB?\fR\fIattributes\fR[\fB?\fR\fIscope\fR[\fB?\fR\fIfilter\fR]]]
  74 .fi
  75 .in -2
  76
  77 .sp
  78 .LP
  79 where:
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fIhostport\fR\fR
  84 .ad
  85 .RS 14n
  86 Host name with an optional \fB:portnumber\fR.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fIdn\fR\fR
  93 .ad
  94 .RS 14n
  95 Base DN to be used for an LDAP search operation.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fIattributes\fR\fR
 102 .ad
 103 .RS 14n
 104 Comma separated list of attributes to be retrieved.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fIscope\fR\fR
 111 .ad
 112 .RS 14n
 113 One of these three strings: base one sub (default=base).
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fIfilter\fR\fR
 120 .ad
 121 .RS 14n
 122 LDAP search filter as used in a call to \fBldap_search\fR(3LDAP).
 123 .RE
 124
 125 .sp
 126 .LP
 127 The following is an example of an LDAP URL:
 128 .sp
 129 .in +2
 130 .nf
 131 ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
 132 .fi
 133 .in -2
 134
 135 .sp
 136 .LP
 137 URLs preceded \fBURL:\fR or wrapped in angle-brackets are tolerated. URLs can
 138 also be preceded by \fBURL:\fR and wrapped in angle-brackets.
 139 .sp
 140 .LP
 141 \fBldap_is_ldap_url()\fR returns a non-zero value if \fIurl\fR looks like an
 142 LDAP URL (as opposed to some other kind of URL). It can be used as a quick
 143 check for an LDAP URL; the \fBldap_url_parse()\fR function should be used if a
 144 more thorough check is needed.
 145 .sp
 146 .LP
 147 \fBldap_url_parse()\fR breaks down an LDAP URL passed in \fIurl\fR into its
 148 component pieces. If successful, zero is returned, an LDAP URL description is
 149 allocated, filled in, and \fIludpp\fR is set to point to it. See \fBRETURN
 150 VALUES\fR for values returned upon error.
 151 .sp
 152 .LP
 153 \fBldap_url_parse_nodn()\fR acts just like \fBldap_url_parse()\fR but does not
 154 require \fIdn\fR in the LDAP URL.
 155 .sp
 156 .LP
 157 \fBldap_free_urldesc()\fR should be called to free an LDAP URL description that
 158 was obtained from a call to \fBldap_url_parse()\fR.
 159 .sp
 160 .LP
 161 \fBldap_url_search()\fR initiates an asynchronous LDAP search based on the
 162 contents of the \fIurl\fR string. This function acts just like
 163 \fBldap_search\fR(3LDAP) except that many search parameters are pulled out of
 164 the URL.
 165 .sp
 166 .LP
 167 \fBldap_url_search_s()\fR performs a synchronous LDAP search based on the
 168 contents of the \fIurl\fR string. This function acts just like
 169 \fBldap_search_s\fR(3LDAP) except that many search parameters are pulled out of
 170 the URL.
 171 .sp
 172 .LP
 173 \fBldap_url_search_st()\fR performs a synchronous LDAP URL search with a
 174 specified \fItimeout\fR. This function acts just like
 175 \fBldap_search_st\fR(3LDAP) except that many search parameters are pulled out
 176 of the URL.
 177 .sp
 178 .LP
 179 \fBldap_dns_to_url()\fR locates the LDAP URL associated with a DNS domain name.
 180 The supplied DNS domain name is converted into a distinguished name. The
 181 directory entry specified by that distinguished name is searched for a labeled
 182 URI attribute. If successful then the corresponding LDAP URL is returned. If
 183 unsuccessful then that entry's parent is searched and so on until the target
 184 distinguished name is reduced to only two nameparts. If \fIdns_name\fR is
 185 \fINULL\fR then the environment variable LOCALDOMAIN is used. If \fIattrs\fR is
 186 not \fINULL\fR then it is appended to the URL's attribute list. If \fIscope\fR
 187 is not NULL then it overrides the URL's scope. If \fIfilter\fR is not
 188 \fINULL\fR then it is merged with the URL's filter. If an error is encountered
 189 then zero is returned, otherwise a string URL is returned. The caller should
 190 free the returned string if it is non-zero.
 191 .sp
 192 .LP
 193 \fBldap_dn_to_url()\fR locates the LDAP URL associated with a distinguished
 194 name. The number of nameparts in the supplied distinguished name must be
 195 provided. The specified directory entry is searched for a labeledURI attribute.
 196 If successful then the LDAP URL is returned. If unsuccessful then that entry's
 197 parent is searched and so on until the target distinguished name is reduced to
 198 only two nameparts. If an error is encountered then zero is returned, otherwise
 199 a string URL is returned. The caller should free the returned string if it is
 200 non-zero.
 201 .SH RETURN VALUES
 202 .sp
 203 .LP
 204 Upon error, one of these values is returned for \fBldap_url_parse()\fR:
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBLDAP_URL_ERR_BADSCOPE\fR\fR
 209 .ad
 210 .RS 25n
 211 URL scope string is invalid.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBLDAP_URL_ERR_HOSTPORT\fR\fR
 218 .ad
 219 .RS 25n
 220 URL hostport is invalid.
 221 .RE
 222
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBLDAP_URL_ERR_MEM\fR\fR
 227 .ad
 228 .RS 25n
 229 Can't allocate memory space.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBLDAP_URL_ERR_NODN\fR\fR
 236 .ad
 237 .RS 25n
 238 URL has no DN (required).
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fBLDAP_URL_ERR_NOTLDAP\fR\fR
 245 .ad
 246 .RS 25n
 247 URL doesn't begin with \fBldap://\fR.
 248 .RE
 249
 250 .SH ATTRIBUTES
 251 .sp
 252 .LP
 253 See \fBattributes\fR(7) for a description of the following attributes:
 254 .sp
 255
 256 .sp
 257 .TS
 258 box;
 259 c | c
 260 l | l .
 261 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 262 Interface Stability     Evolving
 263 .TE
 264
 265 .SH SEE ALSO
 266 .sp
 267 .LP
 268 .BR ldap (3LDAP),
 269 .BR ldap_search (3LDAP),
 270 .BR attributes (7)
 271 .sp
 272 .LP
 273 \fBAn\fR \fBLDAP\fR \fBURL\fR \fBFormat,\fR Tim Howes and Mark Smith, December
 274 1995. Internet Draft (work in progress). Currently available at this URL.
 275 .sp
 276 .in +2
 277 .nf
 278 ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt
 279 .fi
 280 .in -2
 281