diff options
Diffstat (limited to 'lib/libc/net/nsdispatch.3')
| -rw-r--r-- | lib/libc/net/nsdispatch.3 | 147 |
1 files changed, 80 insertions, 67 deletions
diff --git a/lib/libc/net/nsdispatch.3 b/lib/libc/net/nsdispatch.3 index b87d122..d49a9d5 100644 --- a/lib/libc/net/nsdispatch.3 +++ b/lib/libc/net/nsdispatch.3 @@ -35,7 +35,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd January 19, 1999 +.Dd April 16, 2003 .Dt NSDISPATCH 3 .Os .Sh NAME @@ -44,98 +44,111 @@ .Sh LIBRARY .Lb libc .Sh SYNOPSIS +.In sys/types.h +.In stdarg.h .In nsswitch.h .Ft int .Fo nsdispatch .Fa "void *retval" .Fa "const ns_dtab dtab[]" .Fa "const char *database" -.Fa "const char *method" +.Fa "const char *method_name" .Fa "const ns_src defaults[]" .Fa "..." .Fc .Sh DESCRIPTION The .Fn nsdispatch -function invokes the callback functions specified in +function invokes the methods specified in .Va dtab -in the order given in -.Pa /etc/nsswitch.conf +in the order given by +.Xr nsswitch.conf 5 for the database .Va database until a successful entry is found. .Pp .Va retval -is passed to each callback function to modify as necessary -(to pass back to the caller of -.Fn nsdispatch ) +is passed to each method to modify as necessary, to pass back results to +the caller of +.Fn nsdispatch . +.Pp +Each method has the function signature described by the typedef: +.Pp +.Ft typedef "int \*(lp*nss_method\*(rp\*(lpvoid *retval, void *mdata, va_list *ap\*(rp" ; .Pp .Va dtab is an array of .Va ns_dtab structures, which have the following format: .Bd -literal -offset indent -typedef struct { - const char *src; - int (*cb)(void *retval, void *cb_data, va_list ap); - void *cb_data; +typedef struct _ns_dtab { + const char *src; + nss_method method; + void *mdata; } ns_dtab; .Ed .Pp .Bd -ragged -offset indent -For each source type that is implemented, an entry with +The +.Fa dtab +array should consist of one entry for each source type that is +implemented, with .Va src -set to the name of the source, -.Va cb -defined as a function which handles that source, and -.Va cb_data -is used to pass arbitrary data to the callback function. +as the name of the source, +.Va method +as a function which handles that source, and +.Va mdata +as a handle on arbitrary data to be passed to the method. The last entry in .Va dtab should contain .Dv NULL values for .Va src , -.Va cb , +.Va method , and -.Va cb_data . +.Va mdata . .Ed .Pp -.Va method -is usually the name of the function calling -.Fn nsdispatch . -When dynamic loading is supported, a symbol constructed from -.Va database , -the current source, and -.Va method -will be used as the name to invoke the dynamically loaded function. +Additionally, methods may be implemented in NSS modules, in +which case they are selected using the +.Fa database +and +.Fa method_name +arguments along with the configured source. +(The methods supplied via +.Fa dtab +take priority over those implemented in NSS modules in the event +of a conflict.) .Pp .Va defaults -contains a list of default sources to try in the case of -a missing or corrupt -.Xr nsswitch.conf 5 , -or if there isn't a relevant entry for +contains a list of default sources to try if +.Xr nsswitch.conf 5 +is missing or corrupted, or if there is no relevant entry for .Va database . It is an array of .Va ns_src structures, which have the following format: .Bd -literal -offset indent -typedef struct { - const char *src; - u_int32_t flags; +typedef struct _ns_src { + const char *src; + u_int32_t flags; } ns_src; .Ed .Pp .Bd -ragged -offset indent -For each default source type, an entry with -.Va src -set to the name of the source, and +The +.Fa defaults +array should consist of one entry for each source to be configured by +default indicated by +.Va src , +and .Va flags -set to the relevant flags +set to the criterion desired (usually .Dv NS_SUCCESS ; refer to -.Sx Callback return values +.Sx Method return values for more information). The last entry in .Va defaults @@ -149,18 +162,18 @@ set to 0. .Pp For convenience, a global variable defined as: .Dl extern const ns_src __nsdefaultsrc[]; -exists which contains a single default entry for +exists which contains a single default entry for the source .Sq files -for use by callers which don't require complicated default rules. +that may be used by callers which do not require complicated default +rules. .Ed .Pp .Sq Va ... -are optional extra arguments, which -are passed to the appropriate callback function as a variable argument -list of the type -.Va va_list . +are optional extra arguments, which are passed to the appropriate method +as a variable argument list of the type +.Vt va_list . .Ss Valid source types -Whilst there is support for arbitrary sources, the following +While there is support for arbitrary sources, the following #defines for commonly implemented sources are available: .Bl -column NS_COMPAT COMPAT -offset indent .It Sy "#define value" @@ -174,29 +187,32 @@ Refer to .Xr nsswitch.conf 5 for a complete description of what each source type is. .Pp -.Ss Callback return values -The callback functions should return one of the following values -depending upon status of the lookup: -.Bl -column NS_NOTFOUND -offset indent +.Ss Method return values +The +.Vt nss_method +functions must return one of the following values depending upon status +of the lookup: +.Bl -column "RETURN VALUE" "STATUS CODE" .It Sy "Return value Status code" .It "NS_SUCCESS success" .It "NS_NOTFOUND notfound" .It "NS_UNAVAIL unavail" .It "NS_TRYAGAIN tryagain" +.It "NS_RETURN -none-" .El .Pp Refer to .Xr nsswitch.conf 5 -for a complete description of what each status code is. +for a complete description of each status code. .Pp The .Fn nsdispatch -function returns the value of the callback that caused the dispatcher to -finish, or NS_NOTFOUND otherwise. +function returns the value of the method that caused the dispatcher to +terminate, or NS_NOTFOUND otherwise. .Sh SEE ALSO .Xr hesiod 3 , .Xr stdarg 3 , -.Xr ypclnt 3 , +.Xr yp 8 , .Xr nsswitch.conf 5 .Sh HISTORY The @@ -208,25 +224,22 @@ It was imported from the Project, where it appeared first in .Nx 1.4 . +Support for NSS modules first appeared in +.Fx 5.1 . .Sh AUTHORS Luke Mewburn .Aq lukem@netbsd.org -wrote this freely distributable name-service switch implementation, +wrote this freely-distributable name-service switch implementation, using ideas from the .Tn ULTRIX -.Xr svc.conf 5 +"svc.conf\*(lp5\*(rp" and .Tn Solaris -.Xr nsswitch.conf 4 +"nsswitch.conf\*(lp4\*(rp" manual pages. -.Sh BUGS The +.Fx Project +added the support for threads and NSS modules, and normalized the uses +of .Fn nsdispatch -function is not thread safe. -This will be rectified in the future. -.Pp -Currently there is no support for dynamically loadable dispatcher callback -functions. -It is anticipated that this will be added in the future in the back-end -without requiring changes to code that invokes -.Fn nsdispatch . +within the standard C library. |
