Tribblix: manual page: ldap

LDAP_SEARCH(3LDAP) LDAP Library Functions LDAP_SEARCH(3LDAP)

NAME

ldap_search, ldap_search_s, ldap_search_ext, ldap_search_ext_s,
ldap_search_st - LDAP search operations

SYNOPSIS

cc [ flag... ] file... -lldap[ library...]
#include <sys/time.h> /* for struct timeval definition */
#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);

int ldap_search_ext(LDAP *ld, char *base, int scope, char
*filter, char **attrs, int attrsonly, LDAPControl **serverctrls,
LDAPControl **clientctrls, struct timeval *timeoutp,
int sizelimit, int *msgidp);

int ldap_search_ext_s(LDAP *ld,char *base, int scope, char *filter,
char **attrs, int attrsonly, LDAPControl **serverctrls,
LDAPControl **clientctrls, struct timeval *timeoutp,
int sizelimit, LDAPMessage **res);

DESCRIPTION

These functions are used to perform LDAP search operations. The
ldap_search_s() function does the search synchronously (that is, not
returning until the operation completes). The ldap_search_st()
function does the same, but allows a timeout to be specified. The
ldap_search() function is the asynchronous version, initiating the
search and returning the message ID of the operation it initiated.

The base is the DN of the entry at which to start the search. The
scope is the scope of the search and should be one of
LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to
search the object's immediate children, or LDAP_SCOPE_SUBTREE, to
search the object and all its descendents.

The filter is a string representation of the filter to apply in the
search. Simple filters can be specified as
attributetype=attributevalue. More complex filters are specified
using a prefix notation according to the following BNF:

<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <simple>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<simple> ::= <attributetype> <filtertype> <attributevalue>
<filtertype> ::= '=' | '~=' | '<=' | '>='

The '~=' construct is used to specify approximate matching. The
representation for <attributetype> and <attributevalue> are as
described in RFC 1778. In addition, <attributevalue> can be a single
* to achieve an attribute existence test, or can contain text and *'s
interspersed to achieve substring matching.

For example, the filter mail=* finds entries that have a mail
attribute. The filter mail=*@terminator.rs.itd.umich.edu finds
entries that have a mail attribute ending in the specified string.
Use a backslash (\) to escape parentheses characters in a filter. See
RFC 1588 for a more complete description of the filters that are
allowed. See ldap_getfilter(3LDAP) for functions to help construct
search filters automatically.

The attrs is a null-terminated array of attribute types to return
from entries that match filter. If NULL is specified, all attributes
are returned. The attrsonly is set to 1 when attribute types only are
wanted. The attrsonly is set to 0 when both attributes types and
attribute values are wanted.

The sizelimit argument returns the number of matched entries
specified for a search operation. When sizelimit is set to 50, for
example, no more than 50 entries are returned. When sizelimit is set
to 0, all matched entries are returned. The LDAP server can be
configured to send a maximum number of entries, different from the
size limit specified. If 5000 entries are matched in the database of
a server configured to send a maximum number of 500 entries, no more
than 500 entries are returned even when sizelimit is set to 0.

The ldap_search_ext() function initiates an asynchronous search
operation and returns LDAP_SUCCESS when the request is successfully
sent to the server. Otherwise, ldap_search_ext() returns an LDAP
error code. See ldap_error(3LDAP). If successful, ldap_search_ext()
places the message ID of the request in *msgidp. A subsequent call to
ldap_result(3LDAP) can be used to obtain the result of the add
request.

The ldap_search_ext_s() function initiates a synchronous search
operation and returns the result of the operation itself.

ERRORS

The ldap_search_s() and ldap_search_st() functions return the LDAP
error code that results from a search operation. See
ldap_error(3LDAP) for details.

The ldap_search() function returns -1 when the operation terminates
unsuccessfully.

ATTRIBUTES

NOTES