net/nsdispatch.3

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