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