lib/libc/net/nsdispatch.3

   1 .\"     $NetBSD: nsdispatch.3,v 1.8 1999/03/22 19:44:53 garbled Exp $
   2 .\"
   3 .\" Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"        This product includes software developed by the NetBSD
  20 .\"        Foundation, Inc. and its contributors.
  21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  22 .\"    contributors may be used to endorse or promote products derived
  23 .\"    from this software without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  35 .\" POSSIBILITY OF SUCH DAMAGE.
  36 .\"
  37 .\" $FreeBSD$
  38 .\"
  39 .Dd April 16, 2003
  40 .Dt NSDISPATCH 3
  41 .Os
  42 .Sh NAME
  43 .Nm nsdispatch
  44 .Nd name-service switch dispatcher routine
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In stdarg.h
  50 .In nsswitch.h
  51 .Ft int
  52 .Fo nsdispatch
  53 .Fa "void *retval"
  54 .Fa "const ns_dtab dtab[]"
  55 .Fa "const char *database"
  56 .Fa "const char *method_name"
  57 .Fa "const ns_src defaults[]"
  58 .Fa "..."
  59 .Fc
  60 .Sh DESCRIPTION
  61 The
  62 .Fn nsdispatch
  63 function invokes the methods specified in
  64 .Va dtab
  65 in the order given by
  66 .Xr nsswitch.conf 5
  67 for the database
  68 .Va database
  69 until a successful entry is found.
  70 .Pp
  71 .Va retval
  72 is passed to each method to modify as necessary, to pass back results to
  73 the caller of
  74 .Fn nsdispatch .
  75 .Pp
  76 Each method has the function signature described by the typedef:
  77 .Pp
  78 .Ft typedef int
  79 .Fn \*(lp*nss_method\*(rp "void *retval" "void *mdata" "va_list *ap" ;
  80 .Pp
  81 .Va dtab
  82 is an array of
  83 .Va ns_dtab
  84 structures, which have the following format:
  85 .Bd -literal -offset indent
  86 typedef struct _ns_dtab {
  87         const char      *src;
  88         nss_method       method;
  89         void            *mdata;
  90 } ns_dtab;
  91 .Ed
  92 .Pp
  93 .Bd -ragged -offset indent
  94 The
  95 .Fa dtab
  96 array should consist of one entry for each source type that is
  97 implemented, with
  98 .Va src
  99 as the name of the source,
 100 .Va method
 101 as a function which handles that source, and
 102 .Va mdata
 103 as a handle on arbitrary data to be passed to the method.
 104 The last entry in
 105 .Va dtab
 106 should contain
 107 .Dv NULL
 108 values for
 109 .Va src ,
 110 .Va method ,
 111 and
 112 .Va mdata .
 113 .Ed
 114 .Pp
 115 Additionally, methods may be implemented in NSS modules, in
 116 which case they are selected using the
 117 .Fa database
 118 and
 119 .Fa method_name
 120 arguments along with the configured source.
 121 (The methods supplied via
 122 .Fa dtab
 123 take priority over those implemented in NSS modules in the event
 124 of a conflict.)
 125 .Pp
 126 .Va defaults
 127 contains a list of default sources to try if
 128 .Xr nsswitch.conf 5
 129 is missing or corrupted, or if there is no relevant entry for
 130 .Va database .
 131 It is an array of
 132 .Va ns_src
 133 structures, which have the following format:
 134 .Bd -literal -offset indent
 135 typedef struct _ns_src {
 136         const char      *src;
 137         u_int32_t        flags;
 138 } ns_src;
 139 .Ed
 140 .Pp
 141 .Bd -ragged -offset indent
 142 The
 143 .Fa defaults
 144 array should consist of one entry for each source to be configured by
 145 default indicated by
 146 .Va src ,
 147 and
 148 .Va flags
 149 set to the criterion desired
 150 (usually
 151 .Dv NS_SUCCESS ;
 152 refer to
 153 .Sx Method return values
 154 for more information).
 155 The last entry in
 156 .Va defaults
 157 should have
 158 .Va src
 159 set to
 160 .Dv NULL
 161 and
 162 .Va flags
 163 set to 0.
 164 .Pp
 165 For convenience, a global variable defined as:
 166 .Dl extern const ns_src __nsdefaultsrc[];
 167 exists which contains a single default entry for the source
 168 .Sq files
 169 that may be used by callers which do not require complicated default
 170 rules.
 171 .Ed
 172 .Pp
 173 .Sq Va ...
 174 are optional extra arguments, which are passed to the appropriate method
 175 as a variable argument list of the type
 176 .Vt va_list .
 177 .Ss Valid source types
 178 While there is support for arbitrary sources, the following
 179 #defines for commonly implemented sources are available:
 180 .Bl -column NSSRC_COMPAT compat -offset indent
 181 .It Sy "#define value"
 182 .It Dv NSSRC_FILES Ta """files""
 183 .It Dv NSSRC_DNS Ta """dns""
 184 .It Dv NSSRC_NIS Ta """nis""
 185 .It Dv NSSRC_COMPAT Ta """compat""
 186 .El
 187 .Pp
 188 Refer to
 189 .Xr nsswitch.conf 5
 190 for a complete description of what each source type is.
 191 .Pp
 192 .Ss Method return values
 193 The
 194 .Vt nss_method
 195 functions must return one of the following values depending upon status
 196 of the lookup:
 197 .Bl -column "Return value" "Status code"
 198 .It Sy "Return value    Status code"
 199 .It Dv NS_SUCCESS Ta success
 200 .It Dv NS_NOTFOUND Ta notfound
 201 .It Dv NS_UNAVAIL Ta unavail
 202 .It Dv NS_TRYAGAIN Ta tryagain
 203 .It Dv NS_RETURN Ta -none-
 204 .El
 205 .Pp
 206 Refer to
 207 .Xr nsswitch.conf 5
 208 for a complete description of each status code.
 209 .Pp
 210 The
 211 .Fn nsdispatch
 212 function returns the value of the method that caused the dispatcher to
 213 terminate, or
 214 .Dv NS_NOTFOUND
 215 otherwise.
 216 .Sh SEE ALSO
 217 .Xr hesiod 3 ,
 218 .Xr stdarg 3 ,
 219 .Xr nsswitch.conf 5 ,
 220 .Xr yp 8
 221 .Sh HISTORY
 222 The
 223 .Fn nsdispatch
 224 function first appeared in
 225 .Fx 5.0 .
 226 It was imported from the
 227 .Nx
 228 Project,
 229 where it appeared first in
 230 .Nx 1.4 .
 231 Support for NSS modules first appeared in
 232 .Fx 5.1 .
 233 .Sh AUTHORS
 234 Luke Mewburn
 235 .Aq lukem@netbsd.org
 236 wrote this freely-distributable name-service switch implementation,
 237 using ideas from the
 238 .Tn ULTRIX
 239 svc.conf(5)
 240 and
 241 .Tn Solaris
 242 nsswitch.conf(4)
 243 manual pages.
 244 The
 245 .Fx
 246 Project
 247 added the support for threads and NSS modules, and normalized the uses
 248 of
 249 .Fn nsdispatch
 250 within the standard C library.