HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |NOTES |DEPRECATED INTERFACES |SEE ALSO |ACKNOWLEDGEMENTS |COLOPHON | |
LDAP_SEARCH(3) Library Functions ManualLDAP_SEARCH(3)ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s - Perform an LDAP search operation
OpenLDAP LDAP (libldap, -lldap)
#include <sys/types.h>#include <ldap.h>int ldap_search_ext(LDAP *ld,char *base,intscope,char *filter,char *attrs[],intattrsonly,LDAPControl **serverctrls,LDAPControl **clientctrls,struct timeval *timeout,intsizelimit,int *msgidp);int ldap_search_ext_s(LDAP *ld,char *base,intscope,char *filter,char *attrs[],intattrsonly,LDAPControl **serverctrls,LDAPControl **clientctrls,struct timeval *timeout,intsizelimit,LDAPMessage **res);#include <openldap.h>int ldap_pvt_put_filter( BerElement *ber, const char *str);
These routines are used to perform LDAP search operations. Theldap_search_ext_s()routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by theres parameter. Theldap_search_ext()routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by themsgidp parameter. Thebase parameter is the DN of the entry at which to start the search. Thescope parameter 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, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. Thefilter is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). Theattrs parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. Theattrsonly parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. Theserverctrls andclientctrls parameters may be used to specify server and client controls, respectively. Theldap_search_ext_s()routine is the synchronous version ofldap_search_ext(). It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. Seeldap_error(3) for details.ldap_pvt_put_filter()parses a string filter provided instr, performs structural validation and serializes it into the BerElement passed inber as a side-effect. On error, the encoding state ofber is not specified in any way. There is currently no way to learn what part of the string caused the validation to fail.
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). These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. Note thatres parameter ofldap_search_ext_s()andldap_search_s() should be freed withldap_msgfree()regardless of return value of these functions.
Theldap_search()routine is deprecated in favor of theldap_search_ext()routine. Theldap_search_s()andldap_search_st()routines are deprecated in favor of theldap_search_ext_s()routine. Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated.
ldap(3),ldap_result(3),ldap_error(3),lber-types(3)
OpenLDAP Softwareis developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.OpenLDAP Softwareis derived from the University of Michigan LDAP 3.3 Release.
This page is part of theOpenLDAP (an open source implementation of the Lightweight Directory Access Protocol) project. Information about the project can be found at ⟨http://www.openldap.org/⟩. If you have a bug report for this manual page, see ⟨http://www.openldap.org/its/⟩. This page was obtained from the project's upstream Git repository ⟨https://git.openldap.org/openldap/openldap.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-05.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgOpenLDAP LDVERSION RELEASEDATELDAP_SEARCH(3)Pages that refer to this page:ldapsearch(1), ldap_abandon(3), ldap_first_entry(3), ldap_first_message(3), ldap_first_reference(3), ldap_get_option(3), ldap_parse_result(3), ldap_parse_vlv_control(3), ldap_result(3), ldap_sync(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |