usr/src/man/man3ldap/ldap_ufn.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2002, 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.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_UFN 3LDAP "Jan 27, 2002"
   8 .SH NAME
   9 ldap_ufn, ldap_ufn_search_s, ldap_ufn_search_c, ldap_ufn_search_ct,
  10 ldap_ufn_setfilter, ldap_ufn_setprefix, ldap_ufn_timeout \- LDAP user friendly
  11 search functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  16 #include <lber.h>
  17 #include <ldap.h>
  18
  19 \fBint\fR \fBldap_ufn_search_c\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*ufn\fR, \fBchar\fR \fI**attrs\fR,
  20      \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR, \fBint (\fR\fI*cancelproc\fR)(),
  21      \fBvoid\fR \fI*cancelparm\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBldap_ufn_search_ct\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*ufn\fR, \fBchar\fR \fI**attrs\fR,
  27      \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR,\fBint (\fR\fI*cancelproc\fR)(),
  28      \fBvoid\fR \fI*cancelparm\fR,\fBchar\fR \fI*tag1\fR, \fBchar\fR \fI*tag2\fR,
  29      \fBchar\fR \fI*tag3\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBldap_ufn_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*ufn\fR, \fBchar\fR \fI**attrs\fR,
  35      \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBLDAPFiltDesc *\fR\fBldap_ufn_setfilter\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*fname\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBvoid\fR \fBldap_ufn_setprefix\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*prefix\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBldap_ufn_timeout\fR(\fBvoid\fR \fI*tvparam\fR);
  51 .fi
  52
  53 .SH DESCRIPTION
  54 .LP
  55 These functions are used to perform LDAP user friendly search operations.
  56 \fBldap_ufn_search_s()\fR is the simplest form.  It does the search
  57 synchronously.  It takes \fIld\fR to identify the LDAP connection. The
  58 \fIufn\fR parameter is the user friendly name for which to search. The
  59 \fIattrs\fR, \fIattrsonly\fR and \fIres\fR parameters are the same as for
  60 \fBldap_search\fR(3LDAP).
  61 .sp
  62 .LP
  63 The \fBldap_ufn_search_c()\fR function functions the same as
  64 \fBldap_ufn_search_s()\fR, except that it takes \fIcancelproc\fR, a function to
  65 call periodically during the search.  It should be a function taking a single
  66 void * argument, given by \fIcancelparm\fR.  If \fIcancelproc\fR returns a
  67 non-zero result, the search will be abandoned and no results returned. The
  68 purpose of this function is to provide a way for the search to be cancelled,
  69 for example, by a user or because some other condition occurs.
  70 .sp
  71 .LP
  72 The \fBldap_ufn_search_ct()\fR function is like \fBldap_ufn_search_c()\fR,
  73 except that it takes three extra parameters.  \fItag1\fR is passed to the
  74 \fBldap_init_getfilter\fR(3LDAP) function when resolving the first component of
  75 the UFN.  \fItag2\fR is used when resolving intermediate components. \fItag3\fR
  76 is used when resolving the last component. By default, the tags used by the
  77 other UFN search functions during these three phases of the search are "ufn
  78 first", "ufn intermediate", and "ufn last".
  79 .sp
  80 .LP
  81 The \fBldap_ufn_setfilter()\fR function is used to set the
  82 \fBldapfilter.conf\fR(5) file for use with the \fBldap_init_getfilter\fR(3LDAP)
  83 function to \fIfname\fR.
  84 .sp
  85 .LP
  86 The \fBldap_ufn_setprefix()\fR function is used to set the default prefix
  87 (actually, it's a suffix) appended to UFNs before searhing.  UFNs with fewer
  88 than three components have the prefix appended first, before searching.  If
  89 that fails, the UFN is tried with progressively shorter versions of the prefix,
  90 stripping off components.  If the UFN has three or more components, it is tried
  91 by itself first.  If that fails, a similar process is applied with the prefix
  92 appended.
  93 .sp
  94 .LP
  95 The \fBldap_ufn_timeout()\fR function is used to set the timeout associated
  96 with \fBldap_ufn_search_s()\fR searches.  The \fItimeout\fR parameter should
  97 actually be a pointer to a struct timeval. This is so \fBldap_ufn_timeout()\fR
  98 can be used as a cancelproc in the above functions.
  99 .SH ATTRIBUTES
 100 .LP
 101 See \fBattributes\fR(7) for a description of the following attributes:
 102 .sp
 103
 104 .sp
 105 .TS
 106 box;
 107 c | c
 108 l | l .
 109 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 110 Interface Stability     Evolving
 111 .TE
 112
 113 .SH SEE ALSO
 114 .LP
 115 .BR gettimeofday (3C),
 116 .BR ldap (3LDAP),
 117 .BR ldap_error (3LDAP),
 118 .BR ldap_getfilter (3LDAP),
 119 .BR ldap_search (3LDAP),
 120 .BR ldapfilter.conf (5),
 121 .BR attributes (7)
 122 .SH NOTES
 123 .LP
 124 These functions may allocates memory.  Return values are contained in
 125 <\fBldap.h\fR>.