CLDAP_SEARCH_S(3)

NAME
cldap_search_s - Connectionless LDAP Search

SYNOPSIS
#include <ldap.h>

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

DESCRIPTION

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

cldap_search_s() has parameters and behavior identical to that of ldap_search_s(3), 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(4p). Since UDP is a non-reliable protocol, a retry mechanism is used to increase reliability. The cldap_setretryinfo(3) routine 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 values set in ldap_open(3) 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(3) 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(3) 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 5: Repeat steps 2 and 3 for each LDAP server address.

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

RETRANSMISSION EXAMPLE
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(3). 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(3) for more information.

SEE ALSO
ldap(3), ldap_error(3), ldap_search_s(3), cldap_open(3), cldap_setretryinfo(3), cldap_close(3), udp(4p)

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.