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