1.\" $NetBSD: nsdispatch.3,v 1.17 2004/07/27 14:35:56 wiz Exp $ 2.\" 3.\" Copyright (c) 1997, 1998, 1999, 2004 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; and by Jason R. Thorpe. 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.Dd July 18, 2004 38.Dt NSDISPATCH 3 39.Os 40.Sh NAME 41.Nm nsdispatch 42.Nd name-service switch dispatcher routine 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In nsswitch.h 47.Ft int 48.Fo nsdispatch 49.Fa "void *retval" 50.Fa "const ns_dtab dtab[]" 51.Fa "const char *database" 52.Fa "const char *method" 53.Fa "const ns_src defaults[]" 54.Fa "..." 55.Fc 56.Sh DESCRIPTION 57The 58.Fn nsdispatch 59function invokes the callback functions specified in 60.Va dtab 61in the order given in 62.Pa /etc/nsswitch.conf 63for the database 64.Va database 65until a successful entry is found. 66.Pp 67.Va retval 68is passed to each callback function to modify as necessary 69(to pass back to the caller of 70.Fn nsdispatch ) . 71.Pp 72Each callback has the function signature described by the typedef: 73.Pp 74.Ft typedef int 75.Fn \*(lp*nss_method\*(rp "void *retval" "void *cb_data" "va_list *ap" ; 76.Pp 77.Va dtab 78is an array of 79.Va ns_dtab 80structures, which have the following format: 81.Bd -literal -offset indent 82typedef struct { 83 const char *src; 84 nss_method cb; 85 void *cb_data; 86} ns_dtab; 87.Ed 88.Pp 89.Bd -ragged -offset indent 90The 91.Fa dtab 92array should consist of one entry for each source type that is implemented, 93with 94.Va src 95as the name of the source, 96.Va cb 97as a function which handles that source, and 98.Va cb_data 99as a pointer to arbitrary data to be passed to the callback. 100The last entry in 101.Va dtab 102should contain 103.Dv NULL 104values for 105.Va src , 106.Va cb , 107and 108.Va cb_data . 109.Ed 110.Pp 111Callbacks may also be provided by dynamically-loaded modules, in which 112case they are selected using the 113.Fa database 114and 115.Fa method 116arguments in addition to the configured source. 117.Fa method 118is usually the name of the function calling 119.Fn nsdispatch . 120Note that the callbacks provided by 121.Fa dtab 122take priority over those implemented in dynamically-loaded modules in the 123event of a conflict. 124.Pp 125.Va defaults 126contains a list of default sources to try in the case of 127a missing or corrupt 128.Xr nsswitch.conf 5 , 129or if there isn't a relevant entry for 130.Va database . 131It is an array of 132.Va ns_src 133structures, which have the following format: 134.Bd -literal -offset indent 135typedef struct { 136 const char *src; 137 u_int32_t flags; 138} ns_src; 139.Ed 140.Pp 141.Bd -ragged -offset indent 142The 143.Fa defaults 144array should consist of one entry foe each source to consult by default 145indicated by 146.Va src , 147and 148.Fa flags 149set to the desired behavior 150(usually 151.Dv NS_SUCCESS ; 152refer to 153.Sx Callback return values 154for more information). 155The last entry in 156.Fa defaults 157should have 158.Va src 159set to 160.Dv NULL 161and 162.Va flags 163set to 0. 164.Pp 165For convenience, a global variable defined as: 166.Dl extern const ns_src __nsdefaultsrc[]; 167exists which contains a single default entry for 168.Sq files 169for use by callers which don't require complicated default rules. 170.Ed 171.Pp 172.Sq Va ... 173are optional extra arguments, which 174are passed to the appropriate callback function as a variable argument 175list of the type 176.Va va_list . 177.Ss Dynamically-loaded module interface 178The 179.Fn nsdispatch 180function loads callback modules from the run-time link-editor's search 181path using the following naming convention: 182.Bd -literal -offset indent 183nss_\*[Lt]source\*[Gt].so.\*[Lt]version\*[Gt] 184.Ed 185.Bl -tag -width XversionX -offset indent 186.It Aq source 187The source that the module implements. 188.It Aq version 189The 190.Nm nsdispatch 191module interface version, which is defined by the integer 192.Dv NSS_MODULE_INTERFACE_VERSION , 193which has the value 0. 194.El 195.Pp 196When a module is loaded, 197.Fn nsdispatch 198looks for and calls the following function in the module: 199.Pp 200.Ft ns_mtab * 201.Fn nss_module_register "const char *source" "u_int *nelems" \ 202 "nss_module_unregister_fn *unreg" ; 203.Pp 204.Bl -tag -width source 205.It Fa source 206The name of the source that the module implements, as used by 207.Fn nsdispatch 208to construct the module's name. 209.It Fa nelems 210A pointer to an unsigned integer that 211.Fn nss_module_register 212should set to the number of elements in the 213.Va ns_mtab 214array returned by 215.Fn nss_module_register . 216.It Fa unreg 217A pointer to a function pointer that 218.Fn nss_module_resgister 219can optionally set to a function to be invoked when the module is 220unloaded. 221.El 222.Pp 223The unregister function signature is described by the typedef: 224.Pp 225.Ft typedef void 226.Fn \*(lp*nss_module_unregister_fn\*(rp "ns_mtab *mtab" "u_int nelems" ; 227.Pp 228.Fn nss_module_register 229returns an array of 230.Va ns_mtab 231structures, which have the following format: 232.Bd -literal -offset indent 233typedef struct { 234 const char *database; 235 const char *name; 236 nss_method method; 237 void *mdata; 238} ns_mtab; 239.Ed 240.Pp 241.Bd -ragged -offset indent 242The 243.Fa mtab 244array should consist of one entry for each method that is implemented, 245with 246.Va database 247as the name of the database, 248.Va name 249as the name of the method, 250.Va method 251as the callback that implements the method, and 252.Va mdata 253as a pointer to arbitrary data to be passed to the callback. 254.Ed 255.Ss Valid source types 256While there is support for arbitrary sources, the following 257#defines for commonly implemented sources are provided: 258.Bl -column NSSRC_COMPAT COMPAT -offset indent 259.Sy #define value 260.It NSSRC_FILES "files" 261.It NSSRC_DNS "dns" 262.It NSSRC_NIS "nis" 263.It NSSRC_COMPAT "compat" 264.El 265.Pp 266Refer to 267.Xr nsswitch.conf 5 268for a complete description of what each source type is. 269.Ss Valid database types 270While there is support for arbitrary databases, the following 271#defines for currently implemented system databases are provided: 272.Bl -column NSDB_NETGROUP NETGROUP -offset indent 273.Sy #define value 274.It NSDB_HOSTS "hosts" 275.It NSDB_GROUP "group" 276.It NSDB_NETGROUP "netgroup" 277.It NSDB_NETWORKS "networks" 278.It NSDB_PASSWD "passwd" 279.It NSDB_SHELLS "shells" 280.El 281.Pp 282Refer to 283.Xr nsswitch.conf 5 284for a complete description of what each database is. 285.Ss Callback return values 286The callback functions should return one of the following values 287depending upon status of the lookup: 288.Bl -column NS_NOTFOUND -offset indent 289.Sy "Return value" Status code 290.It NS_SUCCESS success 291.It NS_NOTFOUND notfound 292.It NS_UNAVAIL unavail 293.It NS_TRYAGAIN tryagain 294.El 295.Pp 296Refer to 297.Xr nsswitch.conf 5 298for a complete description of what each status code is. 299.Pp 300.Nm 301returns the value of the callback that caused the dispatcher to finish, 302or NS_NOTFOUND otherwise. 303.Sh SEE ALSO 304.Xr ld.elf_so 1 , 305.Xr hesiod 3 , 306.Xr stdarg 3 , 307.Xr ypclnt 3 , 308.Xr nsswitch.conf 5 309.Sh HISTORY 310The 311.Nm 312routines first appeared in 313.Nx 1.4 . 314Support for dynamically-loaded modules first appeared in 315.Nx 3.0 . 316.Sh AUTHORS 317Luke Mewburn 318.Aq lukem@NetBSD.org 319wrote this freely distributable name-service switch implementation, 320using ideas from the 321.Tn ULTRIX 322.Xr svc.conf 5 323and 324.Tn Solaris 325.Xr nsswitch.conf 4 326manual pages. 327Support for dynamically-loaded modules was added by Jason Thorpe 328.Aq thorpej@NetBSD.org , 329based on code developed by the 330.Fx 331Project. 332