1998-10-25 09:41:42 +08:00
|
|
|
.TH CLDAP_SEARCH_S 3 "22 September 1998" "OpenLDAP LDVERSION"
|
1999-09-12 12:41:47 +08:00
|
|
|
.\" $OpenLDAP$
|
2000-05-13 10:47:56 +08:00
|
|
|
.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
|
1999-09-12 12:41:47 +08:00
|
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
1998-08-09 08:43:13 +08:00
|
|
|
.SH NAME
|
|
|
|
|
cldap_search_s \- Connectionless LDAP Search
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.nf
|
|
|
|
|
.ft B
|
|
|
|
|
#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)
|
1998-10-25 09:41:42 +08:00
|
|
|
.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.
|
