Back to main site | Back to man page index

LDAP_RESULT(3)                                 Library Functions Manual                                LDAP_RESULT(3)



NAME
       ldap_result - Wait for the result of an LDAP operation

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       #include <ldap.h>

       int ldap_result( LDAP *ld, int msgid, int all,
            struct timeval *timeout, LDAPMessage **result );

       int ldap_msgfree( LDAPMessage *msg );

       int ldap_msgtype( LDAPMessage *msg );

       int ldap_msgid( LDAPMessage *msg );

DESCRIPTION
       The  ldap_result()  routine  is used to wait for and return the result of an operation previously initiated by
       one of the LDAP asynchronous operation routines (e.g., ldap_search_ext(3), ldap_modify_ext(3),  etc.).   Those
       routines all return -1 in case of error, and an invocation identifier upon successful initiation of the opera‐
       tion. The invocation identifier is picked by the library and is guaranteed to be unique across the  LDAP  ses‐
       sion.   It  can  be  used  to  request the result of a specific operation from ldap_result() through the msgid
       parameter.

       The ldap_result() routine will block or not, depending upon the setting of the timeout parameter.  If  timeout
       is not a NULL pointer,  it  specifies  a  maximum interval  to wait for the selection to complete.  If timeout
       is a NULL  pointer, the LDAP_OPT_TIMEOUT value set by ldap_set_option(3) is used. With  the  default  setting,
       the   select  blocks  indefinitely.   To effect  a  poll,  the  timeout argument should be a non-NULL pointer,
       pointing to a zero-valued timeval structure.  To obtain the behavior of the  default  setting,  bypassing  any
       value  set by ldap_set_option(3), set to -1 the tv_sec field of the timeout parameter.  See select(2) for fur‐
       ther details.

       If the result of a specific operation is required, msgid should be set to the invocation  identifier  returned
       when  the  operation  was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait
       for any or unsolicited response.

       The all parameter, if non-zero, causes ldap_result() to return all responses with msgid,  otherwise  only  the
       next response is returned.  This is commonly used to obtain all the responses of a search operation.

       A  search response is made up of zero or more search entries, zero or more search references, and zero or more
       extended partial responses followed by a search result.  If all is set to 0, search entries will  be  returned
       one  at  a  time  as they come in, via separate calls to ldap_result().  If it's set to 1, the search response
       will only be returned in its  entirety,  i.e.,  after  all  entries,  all  references,  all  extended  partial
       responses, and the final search result have been received.

RETURN VALUE
       Upon  success, the type of the result received is returned and the result parameter will contain the result of
       the operation; otherwise, the result parameter is undefined.  This result should be passed to the LDAP parsing
       routines, ldap_first_message(3) and friends, for interpretation.

       The possible result types returned are:

            LDAP_RES_BIND (0x61)
            LDAP_RES_SEARCH_ENTRY (0x64)

       the  type  of  the last message in the chain.  If the parameter is NULL, the function does nothing and returns
       zero.

       The ldap_msgtype() routine returns the type of a message.

       The ldap_msgid() routine returns the message id of a message.

ERRORS
       ldap_result() returns -1 if something bad happens, and zero if the timeout specified was exceeded.   ldap_msg‐
       type() and ldap_msgid() return -1 on error.

SEE ALSO
       ldap(3), ldap_first_message(3), select(2)

ACKNOWLEDGEMENTS
       OpenLDAP  Software  is  developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.  OpenLDAP
       Software is derived from University of Michigan LDAP 3.3 Release.



OpenLDAP 2.4.40                                       2014/09/20                                       LDAP_RESULT(3)