.TH CLDAP_SEARCH_S 3 "22 September 1998" "OpenLDAP LDVERSION"
.SH NAME
cldap_search_s \- Connectionless LDAP Search
.SH SYNOPSIS
.nf
.ft B
#include <lber.h>
#include <ldap.h>
.LP
.ft B
int cldap_search_s( ld, base, scope, filter, attrs, attrsonly,
	res, logdn )
.ft
LDAP *ld;
char *base;
int scope;
char *filter;
char **attrs;
int attrsonly;
LDAPMessage **res;
char *logdn;
.SH DESCRIPTION
.LP
The
.B cldap_search_s()
routine performs an LDAP search using the
Connectionless LDAP (CLDAP) protocol.
.LP
.B cldap_search_s()
has parameters and behavior identical to that of
.BR ldap_search_s (3),
except for the addition of the \fIlogdn\fP
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".
.SH RETRANSMISSION ALGORITHM
.B cldap_search_s()
operates using the CLDAP protocol over
.BR udp (4p).
Since UDP is a non-reliable protocol, a retry mechanism is used to increase
reliability.  The
.BR cldap_setretryinfo (3)
routine can be used to set two
retry parameters:  \fItries\fP, a count of the number of times to send
a search request and \fItimeout\fP, an initial timeout that determines
how long to wait for a response before re-trying.  \fItimeout\fP is
specified seconds.  These values are stored in the \fBld_cldaptries\fP and
\fBld_cldaptimeout\fP members of the \fIld\fP LDAP structure, and the
default values set in
.BR ldap_open (3)
are 4 and 3 respectively.  The retransmission algorithm used is:
.LP
Step 1.  Set the current timeout to \fBld_cldaptimeout\fP seconds, and
the current LDAP server address to the first LDAP server found during
the
.BR ldap_open (3)
call.
.LP
Step 2:  Send the search request to the current LDAP server address.
.LP
Step 3:  Set the wait timeout to the current timeout divided by the
number of server addresses found during
.BR 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.
.LP
Step 5:  Repeat steps 2 and 3 for each LDAP server address.
.LP
Step 6:  Set the current timeout to twice its previous value and repeat
Steps 2 through 6 a maximum of \fItries\fP times.
.SH RETRANSMISSION EXAMPLE
Assume that the default values for \fItries\fP and \fItimeout\fP 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
.BR cldap_open (3).
The pattern of requests sent will be (stopping as soon as a response is
received):
.nf
  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)
.ft
.SH ERRORS
.B cldap_search_s()
returns LDAP_SUCCESS if a search was successful and the
appropriate LDAP error code otherwise.  See
.BR ldap_error (3)
for more information.
.SH SEE ALSO
.BR ldap (3),
.BR ldap_error (3),
.BR ldap_search_s (3),
.BR cldap_open (3),
.BR cldap_setretryinfo (3),
.BR cldap_close (3),
.BR udp (4p)
.SH ACKNOWLEDGEMENTS
.B	OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B	OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.