share/man/man3ldap/cldap_search_s.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH CLDAP_SEARCH_S 3LDAP "Jan 27, 2002"
   8 .SH NAME
   9 cldap_search_s \- connectionless LDAP search
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  14 #include <lber.h>
  15 #include <ldap.h>
  16
  17 \fBint\fR \fBcldap_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR,
  18      \fBchar\fR \fI*attrs\fR, \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR, \fBchar\fR \fI*logdn\fR);
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBcldap_search_s()\fR function performs an LDAP search using the
  25 Connectionless LDAP (CLDAP) protocol.
  26 .sp
  27 .LP
  28 \fBcldap_search_s()\fR has parameters and behavior identical to that of
  29 \fBldap_search_s\fR(3LDAP), except for the addition of the \fIlogdn\fR
  30 parameter.  \fIlogdn\fR should contain a distinguished name to be used only for
  31 logging purposed by the LDAP server.  It should be in the text format described
  32 by \fIRFC 1779, A String Representation of Distinguished Names\fR.
  33 .SS "Retransmission Algorithm"
  34 .sp
  35 .LP
  36 \fBcldap_search_s()\fR operates using the CLDAP protocol over \fBudp\fR(7P).
  37 Since UDP is a non-reliable protocol, a retry mechanism is used to increase
  38 reliability. The \fBcldap_setretryinfo\fR(3LDAP) function can be used to set
  39 two retry parameters:  \fItries\fR, a count of the number of times to send a
  40 search request and \fItimeout\fR, an initial timeout that determines how long
  41 to wait for a response before re-trying. \fItimeout\fR is specified seconds.
  42 These values are stored in the \fBld_cldaptries\fR and \fBld_cldaptimeout\fR
  43 members of the \fBld\fR LDAP structure, and the default values set in
  44 \fBldap_open\fR(3LDAP) are 4 and 3 respectively. The retransmission algorithm
  45 used is:
  46 .sp
  47 .ne 2
  48 .na
  49 \fBStep 1\fR
  50 .ad
  51 .RS 10n
  52 Set the current timeout to \fBld_cldaptimeout\fR seconds, and the current LDAP
  53 server address to the first LDAP server found during the \fBldap_open\fR(3LDAP)
  54 call.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fBStep 2\fR
  61 .ad
  62 .RS 10n
  63 Send the search request to the current LDAP server address.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fBStep 3\fR
  70 .ad
  71 .RS 10n
  72 Set the wait timeout to the current timeout divided by the number of server
  73 addresses found during \fBldap_open\fR(3LDAP) or to one second, whichever is
  74 larger. Wait at most that long for a response; if a response is received, STOP.
  75 Note that the wait timeout is always rounded down to the next lowest second.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fBStep 4\fR
  82 .ad
  83 .RS 10n
  84 Repeat steps 2 and 3 for each LDAP server address.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fBStep 5\fR
  91 .ad
  92 .RS 10n
  93 Set the current timeout to twice its previous value and repeat Steps 2 through
  94 5 a maximum of \fItries\fR times.
  95 .RE
  96
  97 .SH EXAMPLES
  98 .sp
  99 .LP
 100 Assume that the default values for \fItries\fR and \fItimeout\fR of 4 tries and
 101 3 seconds are used. Further, assume that a space-separated list of two hosts,
 102 each with one address, was passed to \fBcldap_open\fR(3LDAP). The pattern of
 103 requests sent will be (stopping as soon as a response is received):
 104 .sp
 105 .in +2
 106 .nf
 107   Time          Search Request Sent To:
 108    +0                   Host A try 1
 109    +1  (0+3/2)          Host B try 1
 110    +2  (1+3/2)          Host A try 2
 111    +5  (2+6/2)          Host B try 2
 112    +8  (5+6/2)          Host A try 3
 113    +14 (8+12/2) Host B try 3
 114    +20 (14+12/2)        Host A try 4
 115    +32 (20+24/2)        Host B try 4
 116    +44 (20+24/2)        (give up - no response)
 117 .fi
 118 .in -2
 119
 120 .SH ERRORS
 121 .sp
 122 .LP
 123 \fBcldap_search_s()\fR returns  \fBLDAP_SUCCESS\fR if a search was successful
 124 and the appropriate LDAP error code otherwise.  See \fBldap_error\fR(3LDAP) for
 125 more information.
 126 .SH ATTRIBUTES
 127 .sp
 128 .LP
 129 See \fBattributes\fR(5) for a description of the following attributes:
 130 .sp
 131
 132 .sp
 133 .TS
 134 box;
 135 c | c
 136 l | l .
 137 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 138 Interface Stability     Evolving
 139 .TE
 140
 141 .SH SEE ALSO
 142 .sp
 143 .LP
 144 \fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBldap_search_s\fR(3LDAP),
 145 \fBcldap_open\fR(3LDAP), \fBcldap_setretryinfo\fR(3LDAP),
 146 \fBcldap_close\fR(3LDAP), \fBattributes\fR(5), \fBudp\fR(7P)