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 April 16, 2003 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 sys/types.h 48.In stdarg.h 49.In nsswitch.h 50.Ft int 51.Fo nsdispatch 52.Fa "void *retval" 53.Fa "const ns_dtab dtab[]" 54.Fa "const char *database" 55.Fa "const char *method_name" 56.Fa "const ns_src defaults[]" 57.Fa "..." 58.Fc 59.Sh DESCRIPTION 60The 61.Fn nsdispatch 62function invokes the methods specified in 63.Va dtab 64in the order given by 65.Xr nsswitch.conf 5 66for the database 67.Va database 68until a successful entry is found. 69.Pp 70.Va retval 71is passed to each method to modify as necessary, to pass back results to 72the caller of 73.Fn nsdispatch . 74.Pp 75Each method has the function signature described by the typedef: 76.Pp 77.Ft typedef "int \*(lp*nss_method\*(rp\*(lpvoid *retval, void *mdata, va_list *ap\*(rp" ; 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 _ns_dtab { 85 const char *src; 86 nss_method method; 87 void *mdata; 88} ns_dtab; 89.Ed 90.Pp 91.Bd -ragged -offset indent 92The 93.Fa dtab 94array should consist of one entry for each source type that is 95implemented, with 96.Va src 97as the name of the source, 98.Va method 99as a function which handles that source, and 100.Va mdata 101as a handle on arbitrary data to be passed to the method. 102The last entry in 103.Va dtab 104should contain 105.Dv NULL 106values for 107.Va src , 108.Va method , 109and 110.Va mdata . 111.Ed 112.Pp 113Additionally, methods may be implemented in NSS modules, in 114which case they are selected using the 115.Fa database 116and 117.Fa method_name 118arguments along with the configured source. 119(The methods supplied via 120.Fa dtab 121take priority over those implemented in NSS modules in the event 122of a conflict.) 123.Pp 124.Va defaults 125contains a list of default sources to try if 126.Xr nsswitch.conf 5 127is missing or corrupted, or if there is no relevant entry for 128.Va database . 129It is an array of 130.Va ns_src 131structures, which have the following format: 132.Bd -literal -offset indent 133typedef struct _ns_src { 134 const char *src; 135 u_int32_t flags; 136} ns_src; 137.Ed 138.Pp 139.Bd -ragged -offset indent 140The 141.Fa defaults 142array should consist of one entry for each source to be configured by 143default indicated by 144.Va src , 145and 146.Va flags 147set to the criterion desired 148(usually 149.Dv NS_SUCCESS ; 150refer to 151.Sx Method return values 152for more information). 153The last entry in 154.Va defaults 155should have 156.Va src 157set to 158.Dv NULL 159and 160.Va flags 161set to 0. 162.Pp 163For convenience, a global variable defined as: 164.Dl extern const ns_src __nsdefaultsrc[]; 165exists which contains a single default entry for the source 166.Sq files 167that may be used by callers which do not require complicated default 168rules. 169.Ed 170.Pp 171.Sq Va ... 172are optional extra arguments, which are passed to the appropriate method 173as a variable argument list of the type 174.Vt va_list . 175.Ss Valid source types 176While there is support for arbitrary sources, the following 177#defines for commonly implemented sources are available: 178.Bl -column NS_COMPAT COMPAT -offset indent 179.It Sy "#define value" 180.It "NSSRC_FILES ""files""" 181.It "NSSRC_DNS ""dns""" 182.It "NSSRC_NIS ""nis""" 183.It "NSSRC_COMPAT ""compat""" 184.El 185.Pp 186Refer to 187.Xr nsswitch.conf 5 188for a complete description of what each source type is. 189.Pp 190.Ss Method return values 191The 192.Vt nss_method 193functions must return one of the following values depending upon status 194of the lookup: 195.Bl -column "RETURN VALUE" "STATUS CODE" 196.It Sy "Return value Status code" 197.It "NS_SUCCESS success" 198.It "NS_NOTFOUND notfound" 199.It "NS_UNAVAIL unavail" 200.It "NS_TRYAGAIN tryagain" 201.It "NS_RETURN -none-" 202.El 203.Pp 204Refer to 205.Xr nsswitch.conf 5 206for a complete description of each status code. 207.Pp 208The 209.Fn nsdispatch 210function returns the value of the method that caused the dispatcher to 211terminate, or NS_NOTFOUND otherwise. 212.Sh SEE ALSO 213.Xr hesiod 3 , 214.Xr stdarg 3 , 215.Xr yp 8 , 216.Xr nsswitch.conf 5 217.Sh HISTORY 218The 219.Fn nsdispatch 220function first appeared in 221.Fx 5.0 . 222It was imported from the 223.Nx 224Project, 225where it appeared first in 226.Nx 1.4 . 227Support for NSS modules first appeared in 228.Fx 5.1 . 229.Sh AUTHORS 230Luke Mewburn 231.Aq lukem@netbsd.org 232wrote this freely-distributable name-service switch implementation, 233using ideas from the 234.Tn ULTRIX 235"svc.conf\*(lp5\*(rp" 236and 237.Tn Solaris 238"nsswitch.conf\*(lp4\*(rp" 239manual pages. 240The 241.Fx Project 242added the support for threads and NSS modules, and normalized the uses 243of 244.Fn nsdispatch 245within the standard C library. 246