opensolaris man page for cldap_search_s

cldap_search_s(3LDAP)					      LDAP Library Functions					     cldap_search_s(3LDAP)

NAME
       cldap_search_s - connectionless LDAP search

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

       int cldap_search_s(LDAP *ld, char *base, int scope, char *filter,
	    char *attrs, int attrsonly, LDAPMessage **res, char *logdn);

DESCRIPTION
       The cldap_search_s() function performs an LDAP search using the Connectionless LDAP (CLDAP) protocol.

       cldap_search_s()  has  parameters  and  behavior identical to that of ldap_search_s(3LDAP), except for the addition of the logdn parameter.
       logdn should contain a distinguished name to be used only for logging purposed by the LDAP  server.   It  should  be  in  the  text  format
       described by RFC 1779, A String Representation of Distinguished Names.

   Retransmission Algorithm
       cldap_search_s()  operates  using  the  CLDAP  protocol	over  udp(7P).	Since UDP is a non-reliable protocol, a retry mechanism is used to
       increase reliability. The cldap_setretryinfo(3LDAP) function can be used to set two retry parameters:  tries, a	count  of  the	number	of
       times to send a search request and timeout, an initial timeout that determines how long to wait for a response before re-trying. timeout is
       specified seconds.  These values are stored in the ld_cldaptries and ld_cldaptimeout members of the ld LDAP structure, and the default val-
       ues set in ldap_open(3LDAP) are 4 and 3 respectively. The retransmission algorithm used is:

       Step 1	 Set the current timeout to ld_cldaptimeout seconds, and the current LDAP server address to the first LDAP server found during the
		 ldap_open(3LDAP) call.

       Step 2	 Send the search request to the current LDAP server address.

       Step 3	 Set the wait timeout to the current timeout divided by the number of server addresses found during  ldap_open(3LDAP)  or  to  one
		 second,  whichever  is larger. Wait at most that long for a response; if a response is received, STOP. Note that the wait timeout
		 is always rounded down to the next lowest second.

       Step 4	 Repeat steps 2 and 3 for each LDAP server address.

       Step 5	 Set the current timeout to twice its previous value and repeat Steps 2 through 5 a maximum of tries times.

EXAMPLES
       Assume that the default values for tries and timeout of 4 tries and 3 seconds are used. Further, assume that a space-separated list of  two
       hosts,  each  with  one	address,  was passed to cldap_open(3LDAP). The pattern of requests sent will be (stopping as soon as a response is
       received):

	   Time 	Search Request Sent To:
	    +0		     Host A try 1
	    +1	(0+3/2)      Host B try 1
	    +2	(1+3/2)      Host A try 2
	    +5	(2+6/2)      Host B try 2
	    +8	(5+6/2)      Host A try 3
	    +14 (8+12/2)     Host B try 3
	    +20 (14+12/2)    Host A try 4
	    +32 (20+24/2)    Host B try 4
	    +44 (20+24/2)    (give up - no response)

ERRORS
       cldap_search_s() returns  LDAP_SUCCESS if a search was successful and the appropriate LDAP error code otherwise.  See ldap_error(3LDAP) for
       more information.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcsl (32-bit)		   |
       |			     |SUNWcslx (64-bit) 	   |
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       ldap(3LDAP),  ldap_error(3LDAP),  ldap_search_s(3LDAP),	cldap_open(3LDAP),  cldap_setretryinfo(3LDAP),	cldap_close(3LDAP), attributes(5),
       udp(7P)

SunOS 5.11							    27 Jan 2002 					     cldap_search_s(3LDAP)