ldap_search(3ldap)


ldap_search, ldap_search_s, ldap_search_st -- LDAP search operations

Synopsis

#include <lber.h> 
#include <ldap.h> 

int ldap_search(LDAP *ld, char *base, int scope, char *filter, char *attrs[], int attrsonly);

int ldap_search_s(LDAP *ld, char *base, int scope, char *filter, char *attrs[], int attrsonly, LDAPMessage **res);

int ldap_search_st(LDAP *ld, char *base, int scope, char *filter, char *attrs[], int attrsonly, struct timeval *timeout, LDAPMessage **res);

Description

These routines are used to perform LDAP search operations. ldap_search_s does the search synchronously (that is, it does not return until the operation completes). ldap_search_st does the same, but allows a timeout to be specified. ldap_search is the asynchronous version, initiating the search and returning the message ID of the operation it initiated. base is the DN of the entry at which to start the search. scope is the scope of the search and should be one of the following:

LDAP_SCOPE_BASE
search the object itself

LDAP_SCOPE_ONELEVEL
search the object's immediate children

LDAP_SCOPE_SUBTREE
search the object and all its descendents
filter is a string representation of the filter to apply in the search. Simple filters have the pattern attributetype operator attributevalue. For example:
   (cn=John Doe) 
In this example, the attribute type is ``cn'' (common name), the operator is ``='', and the attribute value is ``John Doe''. This filter will retrieve all entries having a common name equal to ``John Doe''.

The following filter retrieves all entries with a surname beginning with ``S'':

   (sn=S*) 
Simple filters can be combined to form complex filters. A prefix notation is used. In the following example, the filter retrieves entries whose common name attribute is either ``John Doe'' or ``Jane Doe'':
   (|(cn=John Doe) (cn=Jane Doe)) 
The ``|'' notation represents OR: ``&'' can be used to represent AND, and ``!'' to represent NOT.

For further details of search filters, refer to RFC 1960.

attrs is a null-terminated array of attribute types to return from entries that match filter. If NULL is specified, all attributes will be returned. For example, to return only the fax and home telephone number attributes for an entry:

   char *my_attrs = {"facsimileTelephoneNumber", "homePhone", NULL}; 
attrsonly is a Boolean that should be set to 0 if both attributes types and attribute values are wanted, and to non-zero if only attribute types are wanted.

For ldap_search_s and ldap_search_st, the res parameter gives the location into which the result of the function call will be placed, if successful. The result will be one or more messages in a chain. Use ldap_first_entry(3ldap) to obtain the first of these messages, then ldap_next_entry(3ldap) to step through the chain. Examine the contents of individual messages with ldap_first_attribute(3ldap) and ldap_next_attribute(3ldap). For the asynchronous variant, ldap_search, call ldap_result(3ldap) to obtain the results.

For ldap_search_st, the timeout parameter refers to a struct timeval, which gives a timeout period in seconds and microseconds.

Return values

ldap_search_s and ldap_search_st will return the LDAP error code resulting from the search operation. See ldap_perror(3ldap) for details. ldap_search returns -1 in case of error.

Warnings

Note that both read and list functionality are subsumed by these routines, by using a filter like ``objectclass=*'' and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).

References

Intro(3ldap), ldap_perror(3ldap), ldap_result(3ldap)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.