git.sur5r.net Git - openldap/blob - doc/man/man3/cldap_search_s.3

   1 .TH CLDAP_SEARCH_S 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 cldap_search_s \- Connectionless LDAP Search
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <lber.h>
   8 #include <ldap.h>
   9 .LP
  10 .ft B
  11 int cldap_search_s( ld, base, scope, filter, attrs, attrsonly,
  12         res, logdn )
  13 .ft
  14 LDAP *ld;
  15 char *base;
  16 int scope;
  17 char *filter;
  18 char **attrs;
  19 int attrsonly;
  20 LDAPMessage **res;
  21 char *logdn;
  22 .SH DESCRIPTION
  23 .LP
  24 The
  25 .B cldap_search_s()
  26 routine performs an LDAP search using the
  27 Connectionless LDAP (CLDAP) protocol.
  28 .LP
  29 .B cldap_search_s()
  30 has parameters and behavior identical to that of
  31 .BR ldap_search_s (3),
  32 except for the addition of the \fIlogdn\fP
  33 parameter.  logdn should contain a distinguished name to be used only
  34 for logging purposed by the LDAP server.  It should be in the text
  35 format described by RFC 1779 "A String Representation of Distinguished Names".
  36 .SH RETRANSMISSION ALGORITHM
  37 .B cldap_search_s()
  38 operates using the CLDAP protocol over
  39 .BR udp (4p).
  40 Since UDP is a non-reliable protocol, a retry mechanism is used to increase
  41 reliability.  The
  42 .BR cldap_setretryinfo (3)
  43 routine can be used to set two
  44 retry parameters:  \fItries\fP, a count of the number of times to send
  45 a search request and \fItimeout\fP, an initial timeout that determines
  46 how long to wait for a response before re-trying.  \fItimeout\fP is
  47 specified seconds.  These values are stored in the \fBld_cldaptries\fP and
  48 \fBld_cldaptimeout\fP members of the \fIld\fP LDAP structure, and the
  49 default values set in
  50 .BR ldap_open (3)
  51 are 4 and 3 respectively.  The retransmission algorithm used is:
  52 .LP
  53 Step 1.  Set the current timeout to \fBld_cldaptimeout\fP seconds, and
  54 the current LDAP server address to the first LDAP server found during
  55 the
  56 .BR ldap_open (3)
  57 call.
  58 .LP
  59 Step 2:  Send the search request to the current LDAP server address.
  60 .LP
  61 Step 3:  Set the wait timeout to the current timeout divided by the
  62 number of server addresses found during
  63 .BR ldap_open (3)
  64 or to one
  65 second, whichever is larger.  Wait at most that long for a response; if
  66 a response is received, STOP.  Note that the wait timeout is always rounded
  67 down to the next lowest second.
  68 .LP
  69 Step 5:  Repeat steps 2 and 3 for each LDAP server address.
  70 .LP
  71 Step 6:  Set the current timeout to twice its previous value and repeat
  72 Steps 2 through 6 a maximum of \fItries\fP times.
  73 .SH RETRANSMISSION EXAMPLE
  74 Assume that the default values for \fItries\fP and \fItimeout\fP of
  75 4 tries and 3 seconds are used.  Further, assume that a space-separated
  76 list of two hosts, each with one address, was passed to
  77 .BR cldap_open (3).
  78 The pattern of requests sent will be (stopping as soon as a response is
  79 received):
  80 .nf
  81   Time          Search Request Sent To:
  82    +0                   Host A try 1
  83    +1  (0+3/2)          Host B try 1
  84    +2  (1+3/2)          Host A try 2
  85    +5  (2+6/2)          Host B try 2
  86    +8  (5+6/2)          Host A try 3
  87    +14 (8+12/2)         Host B try 3
  88    +20 (14+12/2)        Host A try 4
  89    +32 (20+24/2)        Host B try 4
  90    +44 (20+24/2)        (give up - no response)
  91 .ft
  92 .SH ERRORS
  93 .B cldap_search_s()
  94 returns LDAP_SUCCESS if a search was successful and the
  95 appropriate LDAP error code otherwise.  See
  96 .BR ldap_error (3)
  97 for more information.
  98 .SH SEE ALSO
  99 .BR ldap (3),
 100 .BR ldap_error (3),
 101 .BR ldap_search_s (3),
 102 .BR cldap_open (3),
 103 .BR cldap_setretryinfo (3),
 104 .BR cldap_close (3),
 105 .BR udp (4p)
 106 .SH ACKNOWLEDGEMENTS
 107 .B      OpenLDAP
 108 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 109 .B      OpenLDAP
 110 is derived from University of Michigan LDAP 3.3 Release.