1.\" $NetBSD: nsdispatch.3,v 1.8 1999/03/22 19:44:53 garbled Exp $ 2.\" $FreeBSD$ 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 58The 59.Fn nsdispatch 60function invokes the callback functions specified in 61.Va dtab 62in the order given in 63.Pa /etc/nsswitch.conf 64for the database 65.Va database 66until a successful entry is found. 67.Pp 68.Va retval 69is 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 74is an array of 75.Va ns_dtab 76structures, which have the following format: 77.Bd -literal -offset indent 78typedef 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 86For each source type that is implemented, an entry with 87.Va src 88set to the name of the source, 89.Va cb 90defined as a function which handles that source, and 91.Va cb_data 92is used to pass arbitrary data to the callback function. 93The last entry in 94.Va dtab 95should contain 96.Dv NULL 97values for 98.Va src , 99.Va cb , 100and 101.Va cb_data . 102.Ed 103.Pp 104.Va method 105is usually the name of the function calling 106.Fn nsdispatch . 107When dynamic loading is supported, a symbol constructed from 108.Va database , 109the current source, and 110.Va method 111will be used as the name to invoke the dynamically loaded function. 112.Pp 113.Va defaults 114contains a list of default sources to try in the case of 115a missing or corrupt 116.Xr nsswitch.conf 5 , 117or if there isn't a relevant entry for 118.Va database . 119It is an array of 120.Va ns_src 121structures, which have the following format: 122.Bd -literal -offset indent 123typedef struct { 124 const char *src; 125 u_int32_t flags; 126} ns_src; 127.Ed 128.Pp 129.Bd -ragged -offset indent 130For each default source type, an entry with 131.Va src 132set to the name of the source, and 133.Va flags 134set to the relevant flags 135(usually 136.Dv NS_SUCCESS ; 137refer to 138.Sx Callback return values 139for more information). 140The last entry in 141.Va defaults 142should have 143.Va src 144set to 145.Dv NULL 146and 147.Va flags 148set to 0. 149.Pp 150For convenience, a global variable defined as: 151.Dl extern const ns_src __nsdefaultsrc[]; 152exists which contains a single default entry for 153.Sq files 154for use by callers which don't require complicated default rules. 155.Ed 156.Pp 157.Sq Va ... 158are optional extra arguments, which 159are passed to the appropriate callback function as a variable argument 160list of the type 161.Va va_list . 162.Ss Valid source types 163Whilst there is support for arbitrary sources, the following 164#defines for commonly implemented 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 173Refer to 174.Xr nsswitch.conf 5 175for a complete description of what each source type is. 176.Pp 177.Ss Callback return values 178The callback functions should return one of the following values 179depending 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 188Refer to 189.Xr nsswitch.conf 5 190for a complete description of what each status code is. 191.Pp 192The 193.Fn nsdispatch 194function returns the value of the callback that caused the dispatcher to 195finish, or NS_NOTFOUND otherwise. 196.Sh SEE ALSO 197.Xr hesiod 3 , 198.Xr stdarg 3 , 199.Xr ypclnt 3 , 200.Xr nsswitch.conf 5 201.Sh HISTORY 202The 203.Fn nsdispatch 204function first appeared in 205.Fx 5.0 . 206It was imported from the 207.Nx 208Project, 209where it appeared first in 210.Nx 1.4 . 211.Sh AUTHORS 212Luke Mewburn 213.Aq lukem@netbsd.org 214wrote this freely distributable name-service switch implementation, 215using ideas from the 216.Tn ULTRIX 217.Xr svc.conf 5 218and 219.Tn Solaris 220.Xr nsswitch.conf 4 221manual pages. 222.Sh BUGS 223The 224.Fn nsdispatch 225function is not thread safe. 226This will be rectified in the future. 227.Pp 228Currently there is no support for dynamically loadable dispatcher callback 229functions. 230It is anticipated that this will be added in the future in the back-end 231without requiring changes to code that invokes 232.Fn nsdispatch . 233