share/man/man3ldap/ldap_result.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_RESULT 3LDAP "Mar 31, 2009"
   8 .SH NAME
   9 ldap_result, ldap_msgfree \- wait for and return LDAP operation result
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  14 #include <lber.h>
  15 #include <ldap.h>
  16
  17 \fBint\fR \fBldap_result\fR(\fBLDAP *\fR\fIld\fR, \fBint\fR \fImsgid\fR, \fBint\fR \fIall\fR,
  18      \fBstruct timeval *\fR\fItimeout\fR, \fBLDAPMessage **\fR\fIresult\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBldap_msgfree\fR(\fBLDAPMessage *\fR\fImsg\fR);
  24 .fi
  25
  26 .SH DESCRIPTION
  27 .sp
  28 .LP
  29 The \fBldap_result()\fR function is used to wait for and return the result of
  30 an operation previously initiated by one of the LDAP asynchronous operation
  31 functions , for example, \fBldap_search\fR(3LDAP), and
  32 \fBldap_modify\fR(3LDAP). Those functions all return  \fB\(mi1\fR in case of
  33 error, and an invocation identifier upon successful initiation of the
  34 operation. The invocation identifier is picked by the library and is guaranteed
  35 to be unique across the LDAP session.  It can be used to request the result of
  36 a specific operation from \fBldap_result()\fR through the \fImsgid\fR
  37 parameter.
  38 .sp
  39 .LP
  40 The \fBldap_result()\fR function will block or not, depending upon the setting
  41 of the \fItimeout\fR parameter. If \fItimeout\fR is not a null pointer, it
  42 specifies a  maximum interval to wait for the selection to complete.  If
  43 \fItimeout\fR is a null pointer, the select blocks indefinitely. To effect a
  44 poll, the \fItimeout\fR argument should be a non-null pointer, pointing to a
  45 zero-valued \fBtimeval\fR structure.  See \fBselect\fR(3C) for further details.
  46 .sp
  47 .LP
  48 If the result of a specific operation is required, \fImsgid\fR should be set to
  49 the invocation identifier returned when the operation was initiated, otherwise
  50 \fBLDAP_RES_ANY\fR should be supplied.  The \fIall\fR parameter only has
  51 meaning for search responses and is used to select whether a single entry of
  52 the search response should be returned, or all results of the search should be
  53 returned.
  54 .sp
  55 .LP
  56 A search response is made up of zero or more search entries followed by a
  57 search result.  If \fIall\fR is set to 0, search entries will be returned one
  58 at a time as they come in, by means of separate calls to \fBldap_result()\fR.
  59 If it is set to a non-zero value, the search response will only be returned in
  60 its entirety, that is, after all entries and the final search result have been
  61 received.
  62 .sp
  63 .LP
  64 Upon success, the type of the result received is returned and the \fIresult\fR
  65 parameter will contain the result of the operation.  This result should be
  66 passed to the LDAP parsing functions, (see \fBldap_first_entry\fR(3LDAP)) for
  67 interpretation.
  68 .sp
  69 .LP
  70 The possible result types returned are:
  71 .sp
  72 .in +2
  73 .nf
  74 #define LDAP_RES_BIND          0x61L
  75 #define LDAP_RES_SEARCH_ENTRY  0x64L
  76 #define LDAP_RES_SEARCH_RESULT 0x65L
  77 #define LDAP_RES_MODIFY        0x67L
  78 #define LDAP_RES_ADD           0x69L
  79 #define LDAP_RES_DELETE        0x6bL
  80 #define LDAP_RES_MODRDN        0x6dL
  81 #define LDAP_RES_COMPARE       0x6fL
  82 .fi
  83 .in -2
  84
  85 .sp
  86 .LP
  87 The \fBldap_msgfree()\fR function is used to free the memory allocated for a
  88 result by \fBldap_result()\fR or \fBldap_search_s\fR(3LDAP) functions.  It
  89 takes a pointer to the result to be freed and returns the type of the message
  90 it freed.
  91 .SH ERRORS
  92 .sp
  93 .LP
  94 The \fBldap_result()\fR function returns \fB\(mi1\fR on error and 0 if the
  95 specified timeout was exceeded.
  96 .SH ATTRIBUTES
  97 .sp
  98 .LP
  99 See \fBattributes\fR(5) for a description of the following attributes:
 100 .sp
 101
 102 .sp
 103 .TS
 104 box;
 105 c | c
 106 l | l .
 107 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 108 Interface Stability     Committed
 109 .TE
 110
 111 .SH SEE ALSO
 112 .sp
 113 .LP
 114 \fBselect\fR(1), \fBldap\fR(3LDAP), \fBldap_search\fR(3LDAP) ,
 115 \fBattributes\fR(5)
 116 .SH NOTES
 117 .sp
 118 .LP
 119 The \fBldap_result()\fR function allocates memory for results that it receives.
 120 The memory can be freed by calling \fBldap_msgfree\fR(3LDAP).