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.Dd January 19, 1999 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.Fd #include <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 72.Va dtab 73is an array of 74.Va ns_dtab 75structures, which have the following format: 76.Bd -literal -offset indent 77typedef struct { 78 const char *src; 79 int (*cb)(void *retval, void *cb_data, va_list ap); 80 void *cb_data; 81} ns_dtab; 82.Ed 83.Pp 84.Bd -ragged -offset indent 85For each source type that is implemented, an entry with 86.Va src 87set to the name of the source, 88.Va cb 89defined as a function which handles that source, and 90.Va cb_data 91is used to pass arbritrary data to the callback function. 92The last entry in 93.Va dtab 94should contain 95.Dv NULL 96values for 97.Va src , 98.Va cb , 99and 100.Va cb_data . 101.Ed 102.Pp 103.Va method 104is usually the name of the function calling 105.Fn nsdispatch . 106When dynamic loading is supported, a symbol constructed from 107.Va database , 108the current source, and 109.Va method 110will be used as the name to invoke the dynamically loaded function. 111.Pp 112.Va defaults 113contains a list of default sources to try in the case of 114a missing or corrupt 115.Xr nsswitch.conf 5 , 116or if there isn't a relevant entry for 117.Va database . 118It is an array of 119.Va ns_src 120structures, which have the following format: 121.Bd -literal -offset indent 122typedef struct { 123 const char *src; 124 u_int32_t flags; 125} ns_src; 126.Ed 127.Pp 128.Bd -ragged -offset indent 129For each default source type, an entry with 130.Va src 131set to the name of the source, and 132.Va flags 133set to the relevant flags 134(usually 135.Dv NS_SUCCESS ; 136refer to 137.Sx Callback return values 138for more information). 139The last entry in 140.Va defaults 141should have 142.Va src 143set to 144.Dv NULL 145and 146.Va flags 147set to 0. 148.Pp 149For convenience, a global variable defined as: 150.Dl extern const ns_src __nsdefaultsrc[]; 151exists which contains a single default entry for 152.Sq files 153for use by callers which don't require complicated default rules. 154.Ed 155.Pp 156.Va Sq ... 157are optional extra arguments, which 158are passed to the appropriate callback function as a variable argument 159list of the type 160.Va va_list . 161.Ss Valid source types 162Whilst there is support for arbitrary sources, the following 163#defines for commonly implementated sources are available: 164.Bl -column NS_COMPAT COMPAT -offset indent 165.Sy #define value 166.It NSSRC_FILES "files" 167.It NSSRC_DNS "dns" 168.It NSSRC_NIS "nis" 169.It NSSRC_COMPAT "compat" 170.El 171.Pp 172Refer to 173.Xr nsswitch.conf 5 174for a complete description of what each source type is. 175.Pp 176.Ss Callback return values 177The callback functions should return one of the following values 178depending upon status of the lookup: 179.Bl -column NS_NOTFOUND -offset indent 180.Sy "Return value" Status code 181.It NS_SUCCESS success 182.It NS_NOTFOUND notfound 183.It NS_UNAVAIL unavail 184.It NS_TRYAGAIN tryagain 185.El 186.Pp 187Refer to 188.Xr nsswitch.conf 5 189for a complete description of what each status code is. 190.Pp 191.Nm 192returns the value of the callback that caused the dispatcher to finish, 193or NS_NOTFOUND otherwise. 194.Sh SEE ALSO 195.Xr hesiod 3 , 196.Xr stdarg 3 , 197.Xr ypclnt 3 , 198.Xr nsswitch.conf 5 199.Sh HISTORY 200The 201.Nm 202routines first appeared in 203.Nx 1.4 . 204.Sh AUTHORS 205Luke Mewburn 206.Aq lukem@netbsd.org 207wrote this freely distributable name-service switch implementation, 208using ideas from the 209.Tn ULTRIX 210.Xr svc.conf 5 211and 212.Tn Solaris 213.Xr nsswitch.conf 4 214manual pages. 215.Sh BUGS 216The 217.Nm 218routines are not thread safe. 219This will be rectified in the future. 220.Pp 221Currently there is no support for dynamically loadable dispatcher callback 222functions. 223It is anticipated that this will be added in the future in the back-end 224without requiring changes to code that invokes 225.Fn nsdispatch . 226