mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
3a119bf1f7
replace 'malloced' with 'dynamically allocated' State ldap_memfree(3) should be used instead of free() Still need ldap_memfree(3) man page.
134 lines
3.7 KiB
Groff
134 lines
3.7 KiB
Groff
.TH LDAP_RESULT 3 "22 September 1998" "OpenLDAP LDVERSION"
|
|
.SH NAME
|
|
ldap_result \- Wait for the result of an LDAP operation
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <lber.h>
|
|
#include <ldap.h>
|
|
.LP
|
|
.ft B
|
|
int ldap_result(ld, msgid, all, timeout, result)
|
|
.ft
|
|
LDAP *ld;
|
|
int msgid, all;
|
|
struct timeval *timeout;
|
|
LDAPMessage **result;
|
|
.LP
|
|
.ft B
|
|
int ldap_msgfree(msg)
|
|
.ft
|
|
LDAPMessage *msg;
|
|
.LP
|
|
.ft B
|
|
int ldap_msgtype(msg)
|
|
.ft
|
|
LDAPMessage *msg;
|
|
.LP
|
|
.ft B
|
|
int ldap_msgid(msg)
|
|
.ft
|
|
LDAPMessage *msg;
|
|
.SH DESCRIPTION
|
|
The
|
|
.B 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.,
|
|
.BR ldap_search (3),
|
|
.BR ldap_modify (3),
|
|
etc.). Those routines all return -1 in case of error, and an
|
|
invocation identifier upon successful initiation of the operation. The
|
|
invocation identifier is picked by the library and is guaranteed to be
|
|
unique across the LDAP session. It can be used to request the result
|
|
of a specific operation from
|
|
.B ldap_result()
|
|
through the \fImsgid\fP parameter.
|
|
.LP
|
|
The
|
|
.B ldap_result()
|
|
routine will block or not, depending upon the setting
|
|
of the \fItimeout\fP 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 select blocks indefinitely. To
|
|
effect a poll, the timeout argument should be a non-NULL
|
|
pointer, pointing to a zero-valued timeval structure. See
|
|
.BR select (2)
|
|
for further details.
|
|
.LP
|
|
If the result of a specific operation is required, \fImsgid\fP should
|
|
be set to the invocation identifier returned when the operation was
|
|
initiated, otherwise LDAP_RES_ANY should be supplied. The \fIall\fP
|
|
parameter only has meaning for search responses and is used to select
|
|
whether a single entry of the search response should be returned, or
|
|
all results of the search should be returned.
|
|
.LP
|
|
A search response is made up of zero or
|
|
more search entries followed by a search result. If \fIall\fP is set
|
|
to 0, search entries will be returned one at a time as they come in,
|
|
via separate calls to
|
|
.BR ldap_result() .
|
|
If it's set to 1, the search
|
|
response will only be returned in its entirety, i.e., after all entries
|
|
and the final search result have been received.
|
|
.LP
|
|
Upon success, the type of the result received is returned and the
|
|
\fIresult\fP parameter will contain the result of the operation. This
|
|
result should be passed to the LDAP parsing routines,
|
|
.BR ldap_first_entry (3)
|
|
and friends, for interpretation.
|
|
.LP
|
|
The possible result types returned are:
|
|
.LP
|
|
.nf
|
|
#define LDAP_RES_BIND 0x61L
|
|
#define LDAP_RES_SEARCH_ENTRY 0x64L
|
|
#define LDAP_RES_SEARCH_RESULT 0x65L
|
|
#define LDAP_RES_MODIFY 0x67L
|
|
#define LDAP_RES_ADD 0x69L
|
|
#define LDAP_RES_DELETE 0x6bL
|
|
#define LDAP_RES_MODRDN 0x6dL
|
|
#define LDAP_RES_COMPARE 0x6fL
|
|
.fi
|
|
.LP
|
|
The
|
|
.B ldap_msgfree()
|
|
routine is used to free the memory allocated for
|
|
a result by
|
|
.B ldap_result()
|
|
or
|
|
.BR ldap_search_s (3)
|
|
and friends. It takes
|
|
a pointer to the result to be freed and returns the type of the
|
|
message it freed.
|
|
.LP
|
|
The
|
|
.B ldap_msgtype()
|
|
routine returns the type of a message.
|
|
.LP
|
|
The
|
|
.B ldap_msgid()
|
|
routine returns the message id of a message.
|
|
.SH ERRORS
|
|
.B ldap_result()
|
|
returns -1 if something bad happens, and zero if the
|
|
timeout specified was exceeded.
|
|
.B ldap_msgtype()
|
|
and
|
|
.B ldap_msgid()
|
|
return -1 on error.
|
|
.SH NOTES
|
|
This routine dynamically allocates memory for results that it receives.
|
|
The memory can be freed by the caller using
|
|
.BR ldap_msgfree .
|
|
.SH SEE ALSO
|
|
.BR ldap (3),
|
|
.BR ldap_search (3),
|
|
.BR select (2)
|
|
.SH ACKNOWLEDGEMENTS
|
|
.B OpenLDAP
|
|
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
|
|
.B OpenLDAP
|
|
is derived from University of Michigan LDAP 3.3 Release.
|