xref: /titanic_41/usr/src/man/man3ldap/cldap_search_s.3ldap (revision 2c2d21e98a95cba5687ec6574c974a5c6c4a6adb)
te
Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved.
Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
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.
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.
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]
CLDAP_SEARCH_S 3LDAP "Jan 27, 2002"
NAME
cldap_search_s - connectionless LDAP search
SYNOPSIS

cc[ flag... ] file... -lldap[ library... ]
#include <lber.h>
#include <ldap.h>

int cldap_search_s(LDAP *ld, char *base, int scope, char *filter,
 char *attrs, int attrsonly, LDAPMessage **res, char *logdn);
DESCRIPTION

The cldap_search_s() function performs an LDAP search using the Connectionless LDAP (CLDAP) protocol.

cldap_search_s() has parameters and behavior identical to that of ldap_search_s(3LDAP), except for the addition of the logdn 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.

"Retransmission Algorithm"

cldap_search_s() operates using the CLDAP protocol over udp(7P). Since UDP is a non-reliable protocol, a retry mechanism is used to increase reliability. The cldap_setretryinfo(3LDAP) function can be used to set two retry parameters: tries, a count of the number of times to send a search request and timeout, an initial timeout that determines how long to wait for a response before re-trying. timeout is specified seconds. These values are stored in the ld_cldaptries and ld_cldaptimeout members of the ld LDAP structure, and the default values set in ldap_open(3LDAP) are 4 and 3 respectively. The retransmission algorithm used is: Step 1

Set the current timeout to ld_cldaptimeout seconds, and the current LDAP server address to the first LDAP server found during the ldap_open(3LDAP) call.

Step 2

Send the search request to the current LDAP server address.

Step 3

Set the wait timeout to the current timeout divided by the number of server addresses found during ldap_open(3LDAP) 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.

Step 4

Repeat steps 2 and 3 for each LDAP server address.

Step 5

Set the current timeout to twice its previous value and repeat Steps 2 through 5 a maximum of tries times.

EXAMPLES

Assume that the default values for tries and timeout 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 cldap_open(3LDAP). The pattern of requests sent will be (stopping as soon as a response is received):

 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)
ERRORS

cldap_search_s() returns LDAP_SUCCESS if a search was successful and the appropriate LDAP error code otherwise. See ldap_error(3LDAP) for more information.

ATTRIBUTES

See attributes(5) for a description of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Evolving
SEE ALSO

ldap(3LDAP), ldap_error(3LDAP), ldap_search_s(3LDAP), cldap_open(3LDAP), cldap_setretryinfo(3LDAP), cldap_close(3LDAP), attributes(5), udp(7P)