| blob | f955c3a0bd700df2f377aa5cabff313ee5c9194f |
1 .\" $NetBSD: nsdispatch.3,v 1.28 2008/05/08 13:01:42 lukem Exp $
2 .\"
3 .\" Copyright (c) 1997, 1998, 1999, 2004, 2005, 2008
4 .\" 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; and by Jason R. Thorpe.
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 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 .\" POSSIBILITY OF SUCH DAMAGE.
30 .\"
31 .Dd May 8, 2008
32 .Dt NSDISPATCH 3
33 .Os
34 .Sh NAME
35 .Nm nsdispatch
36 .Nd name-service switch dispatcher routine
37 .Sh LIBRARY
38 .Lb libc
39 .Sh SYNOPSIS
40 .In nsswitch.h
41 .Ft int
42 .Fo nsdispatch
43 .Fa "void *nsdrv"
44 .Fa "const ns_dtab dtab[]"
45 .Fa "const char *database"
46 .Fa "const char *name"
47 .Fa "const ns_src defaults[]"
48 .Fa "..."
49 .Fc
50 .Sh DESCRIPTION
51 The
52 .Fn nsdispatch
53 function invokes the callback functions specified in
54 .Fa dtab
55 in the order given in
56 .Pa /etc/nsswitch.conf
57 for the database
58 .Fa database
59 until the action criteria for a source of that database is fulfilled.
60 .Pp
61 .Fa nsdrv
62 is passed to each callback function to use as necessary
63 (to pass back to the caller of
64 .Fn nsdispatch ) .
65 .Pp
66 .Fa dtab
67 is an array of
68 .Fa ns_dtab
69 structures, which have the following format:
70 .Bl -item -offset indent
71 .It
72 .Bd -literal
73 typedef struct {
74 const char *src;
75 nss_method cb;
76 void *cb_data;
77 } ns_dtab;
78 .Ed
79 .It
80 The
81 .Fa dtab
82 array should consist of one entry for each source type that has a
83 static implementation,
84 with
85 .Fa src
86 as the name of the source,
87 .Fa cb
88 as a callback function which handles that source, and
89 .Fa cb_data
90 as a pointer to arbitrary data to be passed to the callback function.
91 The last entry in
92 .Fa dtab
93 should contain
94 .Dv NULL
95 values for
96 .Fa src ,
97 .Fa cb ,
98 and
99 .Fa cb_data .
100 .It
101 The callback function signature is described by the typedef:
102 .Bd -ragged -offset indent
103 .Ft typedef int
104 .Fo \*(lp*nss_method\*(rp
105 .Fa "void *cbrv"
106 .Fa "void *cbdata"
107 .Fa "va_list ap"
108 .Fc ;
109 .Bl -tag -width cbdata
110 .It Fa cbrv
111 The
112 .Fa nsdrv
113 that
114 .Fn nsdispatch
115 was invoked with.
116 .It Fa cbdata
117 The
118 .Fa cb_data
119 member of the array entry for the source that this
120 callback function implements in the
121 .Fa dtab
122 argument of
123 .Fn nsdispatch .
124 .It Fa ap
125 The
126 .Fa ...
127 arguments to
128 .Fn nsdispatch ,
129 converted to a
130 .Ft va_list .
131 .El
132 .Ed
133 .El
134 .Pp
135 .Fa database
136 and
137 .Fa name
138 are used to select methods from optional per-source
139 dynamically-loaded modules.
140 .Fa name
141 is usually the name of the function calling
142 .Fn nsdispatch .
143 Note that the callback functions provided by
144 .Fa dtab
145 take priority over those implemented in dynamically-loaded modules in the
146 event of a conflict.
147 .Pp
148 .Fa defaults
149 contains a list of default sources to try in the case of
150 a missing or corrupt
151 .Xr nsswitch.conf 5 ,
152 or if there isn't a relevant entry for
153 .Fa database .
154 It is an array of
155 .Fa ns_src
156 structures, which have the following format:
157 .Bl -item -offset indent
158 .It
159 .Bd -literal
160 typedef struct {
161 const char *src;
162 uint32_t flags;
163 } ns_src;
164 .Ed
165 .It
166 The
167 .Fa defaults
168 array should consist of one entry for each source to consult by default
169 indicated by
170 .Fa src ,
171 and
172 .Fa flags
173 set to the desired behavior
174 (usually
175 .Dv NS_SUCCESS ;
176 refer to
177 .Sx Callback function return values
178 for more information).
179 The last entry in
180 .Fa defaults
181 should have
182 .Fa src
183 set to
184 .Dv NULL
185 and
186 .Fa flags
187 set to 0.
188 .It
189 Some invokers of
190 .Fn nsdispatch
191 (such as
192 .Xr setgrent 3 )
193 need to force all callback functions to be invoked,
194 irrespective of the action criteria listed in
195 .Xr nsswitch.conf 5 .
196 This can be achieved by adding
197 .Dv NS_FORCEALL
198 to
199 .Fa defaults[0].flags
200 before invoking
201 .Fn nsdispatch .
202 The return value of
203 .Fn nsdispatch
204 will be the result of the final callback function invoked.
205 .It
206 For convenience, a global variable defined as:
207 .Dl extern const ns_src __nsdefaultsrc[];
208 exists which contains a single default entry for
209 .Sq files
210 for use by callers which don't require complicated default rules.
211 .El
212 .Pp
213 .Fa ...
214 are optional extra arguments, which
215 are passed to the appropriate callback function as a
216 .Xr stdarg 3
217 variable argument
218 list of the type
219 .Fa va_list .
220 .Pp
221 .Nm
222 returns the value of the callback function that caused the dispatcher
223 to finish, or
224 .Dv NS_NOTFOUND
225 otherwise.
226 .\"
227 .Ss Dynamically-loaded module interface
228 The
229 .Fn nsdispatch
230 function loads callback functions from the run-time link-editor's search
231 path using the following naming convention:
232 .Bl -item -offset indent
233 .It
234 .Bd -literal
235 nss_\*[Lt]source\*[Gt].so.\*[Lt]version\*[Gt]
236 .Ed
237 .Bl -tag -width XversionX
238 .It Aq source
239 The source that the module implements.
240 .It Aq version
241 The
242 .Nm nsdispatch
243 module interface version, which is defined by the integer
244 .Dv NSS_MODULE_INTERFACE_VERSION ,
245 which has the value 0.
246 .El
247 .El
248 .Pp
249 When a module is loaded,
250 .Fn nsdispatch
251 looks for and calls the following function in the module:
252 .Pp
253 .Bd -ragged -offset indent
254 .Ft ns_mtab *
255 .Fo nss_module_register
256 .Fa "const char *source"
257 .Fa "u_int *nelems"
258 .Fa "nss_module_unregister_fn *unreg"
259 .Fc ;
260 .Pp
261 .Bl -tag -width source
262 .It Fa source
263 The name of the source that the module implements, as used by
264 .Fn nsdispatch
265 to construct the module's name.
266 .It Fa nelems
267 A pointer to an unsigned integer that
268 .Fn nss_module_register
269 should set to the number of elements in the
270 .Ft ns_mtab
271 array returned by
272 .Fn nss_module_register ,
273 or
274 .Dv 0
275 if there was a failure.
276 .It Fa unreg
277 A pointer to a function pointer that
278 .Fn nss_module_register
279 can optionally set to an unregister function to be invoked when the module is
280 unloaded, or
281 .Dv NULL
282 if there isn't one.
283 .El
284 .Ed
285 .Pp
286 The unregister function signature is described by the typedef:
287 .Pp
288 .Bd -ragged -offset indent
289 .Ft typedef void
290 .Fo \*(lp*nss_module_unregister_fn\*(rp
291 .Fa "ns_mtab *mtab"
292 .Fa "u_int nelems"
293 .Fc ;
294 .Pp
295 .Bl -tag -width nelems
296 .It Fa mtab
297 The array of
298 .Ft ns_mtab
299 structures returned by
300 .Fn nss_module_register .
301 .It Fa nelems
302 The
303 .Fa *nelems
304 value set by
305 .Fn nss_module_register .
306 .El
307 .Ed
308 .Pp
309 .Fn nss_module_register
310 returns an array of
311 .Ft ns_mtab
312 structures
313 (with
314 .Fa *nelems
315 entries), or
316 .Dv NULL
317 if there was a failure.
318 The
319 .Ft ns_mtab
320 structures have the following format:
321 .Bl -item -offset indent
322 .It
323 .Bd -literal
324 typedef struct {
325 const char *database;
326 const char *name;
327 nss_method method;
328 void *mdata;
329 } ns_mtab;
330 .Ed
331 .It
332 The
333 .Fa mtab
334 array should consist of one entry for each callback function (method)
335 that is implemented,
336 with
337 .Fa database
338 as the name of the database,
339 .Fa name
340 as the name of the callback function,
341 .Fa method
342 as the
343 .Ft nss_method
344 callback function that implements the method, and
345 .Fa mdata
346 as a pointer to arbitrary data to be passed to the callback function as its
347 .Fa cbdata
348 argument.
349 .El
350 .\"
351 .Ss Valid source types
352 While there is support for arbitrary sources, the following
353 #defines for commonly implemented sources are provided:
354 .Bl -column NSSRC_COMPAT COMPAT -offset indent
355 .It Sy #define Value
356 .It NSSRC_FILES "files"
357 .It NSSRC_DNS "dns"
358 .It NSSRC_NIS "nis"
359 .It NSSRC_COMPAT "compat"
360 .El
361 .Pp
362 Refer to
363 .Xr nsswitch.conf 5
364 for a complete description of what each source type is.
365 .\"
366 .Ss Valid database types
367 While there is support for arbitrary databases, the following
368 #defines for currently implemented system databases are provided:
369 .Bl -column NSDB_PASSWD_COMPAT PASSWD_COMPAT -offset indent
370 .It Sy #define Value
371 .It NSDB_HOSTS "hosts"
372 .It NSDB_GROUP "group"
373 .It NSDB_GROUP_COMPAT "group_compat"
374 .It NSDB_NETGROUP "netgroup"
375 .It NSDB_NETWORKS "networks"
376 .It NSDB_PASSWD "passwd"
377 .It NSDB_PASSWD_COMPAT "passwd_compat"
378 .It NSDB_SHELLS "shells"
379 .El
380 .Pp
381 Refer to
382 .Xr nsswitch.conf 5
383 for a complete description of what each database is.
384 .\"
385 .Ss Callback function return values
386 The callback functions should return one of the following values
387 depending upon status of the lookup:
388 .Bl -column NS_NOTFOUND -offset indent
389 .It Sy "Return value" Status code
390 .It NS_SUCCESS The requested entry was found.
391 .It NS_NOTFOUND The entry is not present at this source.
392 .It NS_TRYAGAIN The source is busy, and may respond to retries.
393 .It NS_UNAVAIL The source is not responding, or entry is corrupt.
394 .El
395 .\"
396 .Sh CALLBACK FUNCTION API FOR STANDARD DATABASES
397 The organization of the
398 .Fa ap
399 argument for an
400 .Fn nss_method
401 callback function for a standard method in a standard database is:
402 .Bl -enum -offset indent -compact
403 .It
404 Pointer to return value of the standard function.
405 .It
406 First argument of the standard function.
407 .It
408 (etc.)
409 .El
410 .Pp
411 For example, given the standard function
412 .Xr getgrnam 3 :
413 .Bd -ragged -offset indent -compact
414 .Ft struct group *
415 .Fn getgrnam "const char *name"
416 .Ed
417 the
418 .Fa ap
419 organization used by the callback functions is:
420 .Bl -enum -offset indent -compact
421 .It
422 .Ft "struct group **"
423 .It
424 .Ft "const char *"
425 .El
426 .Pp
427 .Sy NOTE:
428 Not all standard databases are using this calling convention yet;
429 those that aren't are noted below.
430 These will be changed in the future.
431 .Pp
432 The callback function names and
433 .Ft va_list
434 organization for various standard database callback functions are:
435 .\"
436 .Ss Methods for hosts database
437 .Sy NOTE:
438 The method APIs for this database will be changing in the near future.
439 .Bl -tag -width 3n
440 .It Sy getaddrinfo
441 .Ft "char *name" ,
442 .Ft "const struct addrinfo *pai"
443 .Pp
444 Returns
445 .Ft "struct addrinfo *"
446 via
447 .Ft "void *cbrv" .
448 .It Sy gethostbyaddr
449 .Ft "unsigned char *addr" ,
450 .Ft "int addrlen" ,
451 .Ft "int af"
452 .Pp
453 Returns
454 .Ft "struct hostent *"
455 via
456 .Ft "void *cbrv" .
457 .It Sy gethostbyname
458 .Ft "char *name" ,
459 .Ft "int namelen" ,
460 .Ft "int af"
461 .Pp
462 Returns
463 .Ft "struct hostent *"
464 via
465 .Ft "void *cbrv" .
466 .El
467 .\"
468 .Ss Methods for group and group_compat databases
469 .Bl -tag -width 3n
470 .It Sy endgrent
471 Empty
472 .Fa ap .
473 .Pp
474 All methods for all sources are invoked for this method name.
475 .It Sy getgrent
476 .Ft "struct group **retval"
477 .Pp
478 .Fa *retval
479 should be set to a pointer to an internal static
480 .Ft "struct group"
481 on success,
482 .Dv NULL otherwise.
483 .Pp
484 .Xr getgrent 3
485 returns
486 .Fa *retval
487 if
488 .Fn nsdispatch
489 returns
490 .Dv NS_SUCCESS ,
491 .Dv NULL
492 otherwise.
493 .It Sy getgrent_r
494 .Ft "int *retval" ,
495 .Ft "struct group *grp" ,
496 .Ft "char *buffer" ,
497 .Ft "size_t buflen" ,
498 .Ft "struct group **result"
499 .Pp
500 .Fa *retval
501 should be set to an appropriate
502 .Xr errno 2
503 on failure.
504 .Pp
505 .Xr getgrent_r 3
506 returns 0
507 if
508 .Fn nsdispatch
509 returns
510 .Dv NS_SUCCESS
511 or
512 .Dv NS_NOTFOUND ,
513 and
514 .Fa *retval
515 otherwise.
516 .It Sy getgrgid
517 .Ft "struct group **retval" ,
518 .Ft "gid_t gid"
519 .Pp
520 .Fa *retval
521 should be set to a pointer to an internal static
522 .Ft "struct group"
523 on success,
524 .Dv NULL otherwise.
525 .Pp
526 .Xr getgrgid 3
527 returns
528 .Fa *retval
529 if
530 .Fn nsdispatch
531 returns
532 .Dv NS_SUCCESS ,
533 .Dv NULL
534 otherwise.
535 .It Sy getgrgid_r
536 .Ft "int *retval" ,
537 .Ft "gid_t gid" ,
538 .Ft "struct group *grp" ,
539 .Ft "char *buffer" ,
540 .Ft "size_t buflen" ,
541 .Ft "struct group **result"
542 .Pp
543 .Fa *retval
544 should be set to an appropriate
545 .Xr errno 2
546 on failure.
547 .Pp
548 .Xr getgrgid_r 3
549 returns 0
550 if
551 .Fn nsdispatch
552 returns
553 .Dv NS_SUCCESS
554 or
555 .Dv NS_NOTFOUND ,
556 and
557 .Fa *retval
558 otherwise.
559 .It Sy getgrnam
560 .Ft "struct group **retval" ,
561 .Ft "const char *name"
562 .Pp
563 .Fa *retval
564 should be set to a pointer to an internal static
565 .Ft "struct group"
566 on success,
567 .Dv NULL otherwise.
568 .Pp
569 .Xr getgrnam 3
570 returns
571 .Fa *retval
572 if
573 .Fn nsdispatch
574 returns
575 .Dv NS_SUCCESS ,
576 .Dv NULL
577 otherwise.
578 .It Sy getgrnam_r
579 .Ft "int *retval" ,
580 .Ft "const char *name" ,
581 .Ft "struct group *grp" ,
582 .Ft "char *buffer" ,
583 .Ft "size_t buflen" ,
584 .Ft "struct group **result"
585 .Pp
586 .Fa *retval
587 should be set to an appropriate
588 .Xr errno 2
589 on failure.
590 .Pp
591 .Xr getgrnam_r 3
592 returns 0
593 if
594 .Fn nsdispatch
595 returns
596 .Dv NS_SUCCESS
597 or
598 .Dv NS_NOTFOUND ,
599 and
600 .Fa *retval
601 otherwise.
602 .It Sy getgroupmembership
603 .Ft "int *retval" ,
604 .Ft "const char *name" ,
605 .Ft "gid_t basegid" ,
606 .Ft "gid_t *groups" ,
607 .Ft "int maxgrp" ,
608 .Ft "int *groupc"
609 .Pp
610 .Fa retval
611 is unused.
612 .Pp
613 Lookups for
614 .Sy group_compat
615 are also stopped if
616 .Dv NS_SUCCESS
617 was returned to prevent multiple
618 .Dq "+:"
619 compat entries from being expanded.
620 .Pp
621 .Xr getgroupmembership 3
622 returns
623 is -1 if
624 .Fa *groupc
625 is greater than to
626 .Fa maxgrp ,
627 and 0 otherwise.
628 .It Sy setgroupent
629 .Ft "int *retval" ,
630 .Ft "int stayopen"
631 .Pp
632 .Fa retval
633 should be set to 0 on failure and 1 on success.
634 .Pp
635 All methods for all sources are invoked for this method name.
636 .It Sy setgrent
637 Empty
638 .Fa ap .
639 .Pp
640 All methods for all sources are invoked for this method name.
641 .El
642 .\"
643 .Ss Methods for netgroup database
644 .Sy NOTE:
645 The method APIs for this database will be changing in the near future.
646 .Bl -tag -width 3n
647 .It Sy endnetgrent
648 Empty
649 .Fa ap .
650 .It Sy lookup
651 .Ft "char *name" ,
652 .Ft "char **line" ,
653 .Ft "int bywhat"
654 .Pp
655 Find the given
656 .Fa name
657 and return its value in
658 .Fa line .
659 .Fa bywhat
660 is one of
661 .Dv _NG_KEYBYNAME ,
662 .Dv _NG_KEYBYUSER ,
663 or
664 .Dv _NG_KEYBYHOST .
665 .It Sy getnetgrent
666 .Ft "int *retval" ,
667 .Ft "const char **host" ,
668 .Ft "const char **user" ,
669 .Ft "const char **domain"
670 .Pp
671 .Fa *retval
672 should be set to 0 for no more netgroup members and 1 otherwise.
673 .Pp
674 .Xr getnetgrent 3
675 returns
676 .Fa *retval
677 if
678 .Fn nsdispatch
679 returns
680 .Dv NS_SUCCESS ,
681 0 otherwise.
682 .It Sy innetgr
683 .Ft "int *retval" ,
684 .Ft "const char *grp" ,
685 .Ft "const char *host" ,
686 .Ft "const char *user" ,
687 .Ft "const char *domain"
688 .Pp
689 .Fa *retval
690 should be set to 1 for a successful match and 0 otherwise.
691 .It Sy setnetgrent
692 .Ft "const char *netgroup"
693 .El
694 .\"
695 .Ss Methods for networks database
696 .Bl -tag -width 3n
697 .It Sy getnetbyaddr
698 .Ft "struct netent **retval" ,
699 .Ft "uint32_t net" ,
700 .Ft "int type"
701 .Pp
702 .Fa *retval
703 should be set to a pointer to an internal static
704 .Ft "struct netent"
705 on success,
706 .Dv NULL otherwise.
707 .Pp
708 .Xr getnetbyaddr 3
709 returns
710 .Fa *retval
711 if
712 .Fn nsdispatch
713 returns
714 .Dv NS_SUCCESS ,
715 .Dv NULL
716 otherwise.
717 .It Sy getnetbyname
718 .Ft "struct netent **retval" ,
719 .Ft "const char *name"
720 .Pp
721 .Fa *retval
722 should be set to a pointer to an internal static
723 .Ft "struct netent"
724 on success,
725 .Dv NULL otherwise.
726 .Pp
727 .Xr getnetbyname 3
728 returns
729 .Fa *retval
730 if
731 .Fn nsdispatch
732 returns
733 .Dv NS_SUCCESS ,
734 .Dv NULL
735 otherwise.
736 .El
737 .\"
738 .Ss Methods for passwd and passwd_compat databases
739 .Bl -tag -width 3n
740 .It Sy endpwent
741 Empty
742 .Fa ap .
743 .Pp
744 All methods for all sources are invoked for this method name.
745 .It Sy getpwent
746 .Ft "struct passwd **retval"
747 .Pp
748 .Fa *retval
749 should be set to a pointer to an internal static
750 .Ft "struct passwd"
751 on success,
752 .Dv NULL otherwise.
753 .Pp
754 .Xr getpwent 3
755 returns
756 .Fa *retval
757 if
758 .Fn nsdispatch
759 returns
760 .Dv NS_SUCCESS ,
761 .Dv NULL
762 otherwise.
763 .It Sy getpwent_r
764 .Ft "int *retval" ,
765 .Ft "struct passwd *pw" ,
766 .Ft "char *buffer" ,
767 .Ft "size_t buflen" ,
768 .Ft "struct passwd **result"
769 .Pp
770 .Fa *retval
771 should be set to an appropriate
772 .Xr errno 2
773 on failure.
774 .Pp
775 .Xr getpwent_r 3
776 returns 0
777 if
778 .Fn nsdispatch
779 returns
780 .Dv NS_SUCCESS
781 or
782 .Dv NS_NOTFOUND ,
783 and
784 .Fa *retval
785 otherwise.
786 .It Sy getpwnam
787 .Ft "struct passwd **retval" ,
788 .Ft "const char *name"
789 .Pp
790 .Fa *retval
791 should be set to a pointer to an internal static
792 .Ft "struct passwd"
793 on success,
794 .Dv NULL otherwise.
795 .Pp
796 .Xr getpwnam 3
797 returns
798 .Fa *retval
799 if
800 .Fn nsdispatch
801 returns
802 .Dv NS_SUCCESS ,
803 .Dv NULL
804 otherwise.
805 .It Sy getpwnam_r
806 .Ft "int *retval" ,
807 .Ft "const char *name" ,
808 .Ft "struct passwd *pw" ,
809 .Ft "char *buffer" ,
810 .Ft "size_t buflen" ,
811 .Ft "struct passwd **result"
812 .Pp
813 .Fa *retval
814 should be set to an appropriate
815 .Xr errno 2
816 on failure.
817 .Pp
818 .Xr getpwnam_r 3
819 returns 0
820 if
821 .Fn nsdispatch
822 returns
823 .Dv NS_SUCCESS
824 or
825 .Dv NS_NOTFOUND ,
826 and
827 .Fa *retval
828 otherwise.
829 .It Sy getpwuid
830 .Ft "struct passwd **retval" ,
831 .Ft "uid_t uid"
832 .Pp
833 .Fa *retval
834 should be set to a pointer to an internal static
835 .Ft "struct passwd"
836 on success,
837 .Dv NULL otherwise.
838 .Pp
839 .Xr getpwuid 3
840 returns
841 .Fa *retval
842 if
843 .Fn nsdispatch
844 returns
845 .Dv NS_SUCCESS ,
846 .Dv NULL
847 otherwise.
848 .It Sy getpwuid_r
849 .Ft "int *retval" ,
850 .Ft "uid_t uid" ,
851 .Ft "struct passwd *pw" ,
852 .Ft "char *buffer" ,
853 .Ft "size_t buflen" ,
854 .Ft "struct passwd **result"
855 .Pp
856 .Fa *retval
857 should be set to an appropriate
858 .Xr errno 2
859 on failure.
860 .Pp
861 .Xr getpwuid_r
862 returns 0
863 if
864 .Fn nsdispatch
865 returns
866 .Dv NS_SUCCESS
867 or
868 .Dv NS_NOTFOUND ,
869 and
870 .Fa *retval
871 otherwise.
872 .It Sy setpassent
873 .Ft "int *retval" ,
874 .Ft "int stayopen"
875 .Pp
876 .Fa retval
877 should be set to 0 on failure and 1 on success.
878 .Pp
879 All methods for all sources are invoked for this method name.
880 .It Sy setpwent
881 Empty
882 .Fa ap .
883 .Pp
884 All methods for all sources are invoked for this method name.
885 .El
886 .\"
887 .Ss Methods for shells database
888 .Bl -tag -width 3n
889 .It Sy endusershell
890 Empty
891 .Fa ap .
892 .Pp
893 All methods for all sources are invoked for this method name.
894 .It Sy getusershell
895 .Ft "char **retval"
896 .Pp
897 .Xr getusershell 3
898 returns
899 .Fa *retval
900 if
901 .Fn nsdispatch
902 returns
903 .Dv NS_SUCCESS ,
904 and 0 otherwise.
905 .It Sy setusershell
906 Empty
907 .Fa ap .
908 .Pp
909 All methods for all sources are invoked for this method name.
910 .El
911 .\"
912 .Sh SEE ALSO
913 .Xr ld.elf_so 1 ,
914 .Xr hesiod 3 ,
915 .Xr stdarg 3 ,
916 .Xr ypclnt 3 ,
917 .Xr nsswitch.conf 5
918 .Sh HISTORY
919 The
920 .Nm
921 routines first appeared in
922 .Nx 1.4 .
923 Support for dynamically-loaded modules first appeared in
924 .Nx 3.0 .
925 .Sh AUTHORS
926 Luke Mewburn
927 .Aq lukem@NetBSD.org
928 wrote this freely distributable name-service switch implementation,
929 using ideas from the
930 .Tn ULTRIX
931 .Xr svc.conf 5
932 and
933 .Tn Solaris
934 .Xr nsswitch.conf 4
935 manual pages.
936 Support for dynamically-loaded modules was added by Jason Thorpe
937 .Aq thorpej@NetBSD.org ,
938 based on code developed by the
939 .Fx
940 Project.