Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
LDAP Library Functionsldap_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);

DESCRIPTION

 

These functions are used to perform LDAP search operations. ldap_search_s() does the search synchronously (that is, not returning 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 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.

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=*" will find any entries that have a mail attribute. The filter "mail=*@terminator.rs.itd.umich.edu" will find any entries that have a mail attribute ending in the specified string. To put parentheses in a filter, escape them with a backslash '\' character. See RFC 1588 for a more complete description of allowable filters. See ldap_getfilter(3LDAP) for functions to help in constructing search filters automatically.

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. Attrsonly should be set to 1 if only attribute types are wanted. It should be set to 0 if both attributes types and attribute values are wanted.

The ldap_search_ext() function initiates an asynchronous search operation and returns LDAP_SUCCESS if the request was successfully sent to the server, or else it returns a 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 as such returns the result of the operation itself.

ERRORS

 

ldap_search_s() and ldap_search_st() will return the LDAP error code resulting from the search operation. See ldap_error(3LDAP) for details.

ldap_search() returns -1 when terminating unsuccessfully.

ATTRIBUTES

 

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

ATTRIBUTE TYPEATTRIBUTE VALUE
AvailabilitySUNWcsl (32-bit)
 SUNWcslx (64-bit)
Interface StabilityEvolving

SEE ALSO

 

ldap(3LDAP), ldap_result(3LDAP), ldap_getfilter(3LDAP), ldap_error(3LDAP) , attributes(5)

NOTES

 

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

These functions may allocate memory which must be freed by the calling application. Return values are contained in <ldap.h>.


SunOS 5.9Go To TopLast Changed 27 Jan 2002

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.