ldap_url(3LDAP) 					      LDAP Library Functions						   ldap_url(3LDAP)

NAME

       ldap_url, ldap_is_ldap_url, ldap_url_parse, ldap_url_parse_nodn, ldap_free_urldesc, ldap_url_search, ldap_url_search_s, ldap_url_search_st,
       ldap_dns_to_url, ldap_dn_to_url - LDAP Uniform Resource Locator functions

SYNOPSIS

       cc[ flag... ] file... -lldap[ library... ]
       #include <lber.h>
       #include <ldap.h>

       int ldap_is_ldap_url(char *url);

       int ldap_url_parse(char *url, LDAPURLDesc **ludpp);

       int ldap_url_parse_nodn(char *url, LDAPURLDesc **ludpp);

       ldap_free_urldesc(LDAPURLDesc *ludp);

       int ldap_url_search(LDAP *ld, char *url, int attrsonly);

       int ldap_url_search_s(LDAP *ld, char *url,
	    int attrsonly, LDAPMessage **res);

       int ldap_url_search_st(LDAP *ld, char *url, int attrsonly,
	    struct timeval *timeout, LDAPMessage **res);

       char *ldap_dns_to_url(LDAP *ld, char *dns_name, char *attrs,
	    char *scope, char *filter);

       char *ldap_dn_to_url(LDAP *ld, char *dn, int nameparts);

DESCRIPTION

       These functions support the use of LDAP URLs (Uniform Resource Locators). The following shows the formatting used for LDAP URLs.

	 ldap://hostport/dn[?attributes[?scope[?filter]]]

       where:

       hostport      Host name with an optional :portnumber.

       dn	     Base DN to be used for an LDAP search operation.

       attributes    Comma separated list of attributes to be retrieved.

       scope	     One of these three strings: base one sub (default=base).

       filter	     LDAP search filter as used in a call to ldap_search(3LDAP).

       The following is an example of an LDAP URL:

	 ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich

       URLs preceded URL: or wrapped in angle-brackets are tolerated. URLs can also be preceded by URL: and wrapped in angle-brackets.

       ldap_is_ldap_url() returns a non-zero value if url looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick
       check for an LDAP URL; the ldap_url_parse() function should be used if a more thorough check is needed.

       ldap_url_parse()  breaks down an LDAP URL passed in url into its component pieces. If successful, zero is returned, an LDAP URL description
       is allocated, filled in, and ludpp is set to point to it. See RETURN VALUES for values returned upon error.

       ldap_url_parse_nodn() acts just like ldap_url_parse() but does not require dn in the LDAP URL.

       ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to ldap_url_parse().

       ldap_url_search() initiates an asynchronous LDAP  search  based	on  the  contents  of  the  url  string.  This	function  acts	just  like
       ldap_search(3LDAP) except that many search parameters are pulled out of the URL.

       ldap_url_search_s()  performs  a  synchronous  LDAP  search  based  on  the  contents  of  the  url  string.  This  function acts just like
       ldap_search_s(3LDAP) except that many search parameters are pulled out of the URL.

       ldap_url_search_st() performs a synchronous LDAP URL search with a specified timeout. This function acts  just  like  ldap_search_st(3LDAP)
       except that many search parameters are pulled out of the URL.

       ldap_dns_to_url()  locates  the	LDAP URL associated with a DNS domain name. The supplied DNS domain name is converted into a distinguished
       name. The directory entry specified by that distinguished name is searched for a labeled URI attribute. If successful then the  correspond-
       ing  LDAP URL is returned. If unsuccessful then that entry's parent is searched and so on until the target distinguished name is reduced to
       only two nameparts. If dns_name is NULL then the environment variable LOCALDOMAIN is used. If attrs is not NULL then it is appended to  the
       URL's  attribute  list. If scope is not NULL then it overrides the URL's scope. If filter is not NULL then it is merged with the URL's fil-
       ter. If an error is encountered then zero is returned, otherwise a string URL is returned. The caller should free the returned string if it
       is non-zero.

       ldap_dn_to_url() locates the LDAP URL associated with a distinguished name. The number of nameparts in the supplied distinguished name must
       be provided. The specified directory entry is searched for a labeledURI attribute. If successful then the LDAP URL is returned.	If  unsuc-
       cessful then that entry's parent is searched and so on until the target distinguished name is reduced to only two nameparts. If an error is
       encountered then zero is returned, otherwise a string URL is returned. The caller should free the returned string if it is non-zero.

RETURN VALUES

       Upon error, one of these values is returned for ldap_url_parse():

       LDAP_URL_ERR_BADSCOPE	URL scope string is invalid.

       LDAP_URL_ERR_HOSTPORT	URL hostport is invalid.

       LDAP_URL_ERR_MEM 	Can't allocate memory space.

       LDAP_URL_ERR_NODN	URL has no DN (required).

       LDAP_URL_ERR_NOTLDAP	URL doesn't begin with ldap://.

ATTRIBUTES

       See attributes(5) for a description of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       ldap(3LDAP), ldap_search(3LDAP), attributes(5)

       An LDAP URL Format, Tim Howes and Mark Smith, December 1995. Internet Draft (work in progress). Currently available at this URL.

	 ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt

SunOS 5.11							    02 Dec 2003 						   ldap_url(3LDAP)