Manual Pages for UNIX Operating System command usage for man ldap_url_search

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 
     #include 

     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:




SunOS 5.11          Last change: 02 Dec 2003                    1






LDAP Library Functions                            ldap_url(3LDAP)



     hostport      Host name with an optional :portnumber.


     dn            Base DN to be used for an LDAP  search  opera-
                   tion.


     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().



SunOS 5.11          Last change: 02 Dec 2003                    2






LDAP Library Functions                            ldap_url(3LDAP)



     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 parame-
     ters 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 corresponding 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 filter. 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 dis-
     tinguished  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  unsuccessful  then  that
     entry's  parent  is searched and so on until the target dis-
     tinguished 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.




SunOS 5.11          Last change: 02 Dec 2003                    3






LDAP Library Functions                            ldap_url(3LDAP)



     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  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|


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          Last change: 02 Dec 2003                    4