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