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