LDAP_UFN(3)						     Library Functions Manual						       LDAP_UFN(3)

NAME

       ldap_ufn_search_s,  ldap_ufn_search_c,  ldap_ufn_search_ct,  ldap_ufn_setfilter, ldap_ufn_setfilter, ldap_ufn_setprefix, ldap_ufn_timeout -
       Perform an LDAP user friendly search operation

SYNOPSIS

       #include <ldap.h>

       int ldap_ufn_search_c(ld, ufn, attrs, attrsonly, res, cancelproc,
		      cancelparm)
       LDAP *ld;
       char *ufn;
       char **attrs;
       int attrsonly;
       LDAPMessage **res;
       int (*cancelproc)();
       void *cancelparm;

       int ldap_ufn_search_ct(ld, ufn, attrs, attrsonly, res, cancelproc,
		      cancelparm, tag1, tag2, tag3)
       LDAP *ld;
       char *ufn;
       char **attrs;
       int attrsonly;
       LDAPMessage **res;
       int (*cancelproc)();
       void *cancelparm;
       char *tag1, *tag2, *tag3;

       int ldap_ufn_search_s(ld, ufn, attrs, attrsonly, res)
       LDAP *ld;
       char *ufn;
       char **attrs;
       int attrsonly;
       LDAPMessage **res;

       LDAPFiltDesc *ldap_ufn_setfilter(ld, fname)
       LDAP *ld;
       char *fname;

       void ldap_ufn_setprefix(ld, prefix)
       LDAP *ld;
       char *prefix;

       int ldap_ufn_timeout(tvparam)
       void *tvparam;

DESCRIPTION

       These routines are used to perform LDAP user friendly search operations.  ldap_ufn_search_s() is the simplest form.   It  does  the  search
       synchronously.	It  takes  ld  to identify the the LDAP connection.  The ufn parameter is the user friendly name for which to search.  The
       attrs, attrsonly and res parameters are the same as for ldap_search(3).

       The ldap_ufn_search_c() routine functions the same as ldap_ufn_search_s(), except that it takes cancelproc, a function to  call	periodicly
       during the search.  It should be a function taking a single void * argument, given by calcelparm.  If cancelproc returns a non-zero result,
       the search will be abandoned and no results returned.  The purpose of this routine is to provide a way for the search to be cancelled,  for
       example, by a user or because some other condition occurs.

       The  ldap_ufn_search_ct()  routine  is  like  ldap_ufn_search_c(),  except  that  it  takes  three extra parameters.  tag1 is passed to the
       ldap_init_getfilter(3) routine when resolving the first component of the UFN.  tag2 is used when resolving intermediate	components.   tag3
       is  used  when  resolving  the last component.  By default, the tags used by the other UFN search routines during these three phases of the
       search are "ufn first", "ufn intermediate", and "ufn last".

       The ldap_ufn_setfilter() routine is used to set the ldapfilter.conf(5) file for use with the ldap_init_getfilter(3) routine to fname.

       The ldap_ufn_setprefix() routine is used to set the default prefix (actually, it's a suffix) appended to UFNs before searhing.	UFNs  with
       fewer  than  three components have the prefix appended first, before searching.	If that fails, the UFN is tried with progressively shorter
       versions of the prefix, stripping off components.  If the UFN has three or more components, it is tried by itself first.  If that fails,  a
       similar process is applied with the prefix appended.

       The ldap_ufn_timeout() routine is used to set the timeout associated with ldap_ufn_search_s() searches.	The timeout parameter should actu-
       ally be a pointer to a struct timeval (this is so ldap_ufn_timeout() can be used as a cancelproc in the above routines).

NOTES

       These routines may dynamically allocate memory.	The caller is required to free such  memory  using  the  supplied  deallocation  routines.
       Return values are contained in <ldap.h>.

SEE ALSO

       gettimeofday(2), ldap(3), ldap_search(3), ldap_getfilter(3), ldapfilter.conf(5), ldap_error(3)

ACKNOWLEDGEMENTS

       OpenLDAP  is  developed and maintained by The OpenLDAP Project (http://www.openldap.org/).  OpenLDAP is derived from University of Michigan
       LDAP 3.3 Release.

OpenLDAP 2.0.27-Release 					 22 September 1998						       LDAP_UFN(3)