195 lines
4.6 KiB
Groff
195 lines
4.6 KiB
Groff
.\" @(#)rpc_svc_reg.3n 1.32 93/08/31 SMI; from SVr4
|
|
.\" Copyright 1989 AT&T
|
|
.\" @(#)rpc_svc_call 1.6 89/07/20 SMI;
|
|
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
|
|
.\" $NetBSD: rpc_svc_reg.3,v 1.1 2000/06/02 23:11:14 fvdl Exp $
|
|
.Dd May 3, 1993
|
|
.Dt RPC_SVC_REG 3
|
|
.Sh NAME
|
|
.Nm rpc_svc_reg,
|
|
.Nm rpc_reg,
|
|
.Nm svc_reg,
|
|
.Nm svc_unreg,
|
|
.Nm svc_auth_reg,
|
|
.Nm xprt_register,
|
|
.Nm xprt_unregister
|
|
.Nd library routines for registering servers
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include <rpc/rpc.h>
|
|
.Ft bool_t
|
|
.Fn rpc_reg "const rpcprog_t prognum" "const rpcvers_t versnum" "const rpcproc_t procnum" "const char *(*procname)()" "const xdrproc_t inproc" "const xdrproc_t outproc" "const char *nettype"
|
|
.Ft int
|
|
.Fn svc_reg "const SVCXPRT *xprt" "const rpcprog_t prognum" "const rpcvers_t versnum" "const void (*dispatch(struct svc_req *, SVCXPRT *)" "const struct netconfig *netconf"
|
|
.Ft void
|
|
.Fn svc_unreg "const rpcprog_t prognum" "const rpcvers_t versnum"
|
|
.Ft int
|
|
.Fn svc_auth_reg "const int cred_flavor" "const enum auth_stat (*handler(struct svc_req *, truct rpc_msg *))"
|
|
.Ft void
|
|
.Fn xprt_register "const SVCXPRT *xprt"
|
|
.Ft void
|
|
.Fn xprt_unregister "const SVCXPRT *xprt"
|
|
.Sh DESCRIPTION
|
|
These routines are a part of the RPC
|
|
library which allows the RPC
|
|
servers to register themselves with rpcbind
|
|
(see
|
|
.Xr rpcbind 8 ),
|
|
and associate the given program and version
|
|
number with the dispatch function.
|
|
When the RPC server receives a RPC request, the library invokes the
|
|
dispatch routine with the appropriate arguments.
|
|
.Sh Routines
|
|
See
|
|
.Xr rpc 3
|
|
for the definition of the
|
|
.Vt SVCXPRT
|
|
data structure.
|
|
.Pp
|
|
.Bl -tag -width XXXXX
|
|
.It Fn rpc_reg
|
|
Register program
|
|
.Fa prognum ,
|
|
procedure
|
|
.Fa procname ,
|
|
and version
|
|
.Fa versnum
|
|
with the RPC
|
|
service package.
|
|
If a request arrives for program
|
|
.Fa prognum ,
|
|
version
|
|
.Fa versnum ,
|
|
and procedure
|
|
.Fa procnum ,
|
|
.Fa procname
|
|
is called with a pointer to its parameter(s);
|
|
.Fa procname
|
|
should return a pointer to its static result(s);
|
|
.Fa inproc
|
|
is the XDR function used to decode the parameters while
|
|
.Fa outproc
|
|
is the XDR function used to encode the results.
|
|
Procedures are registered on all available transports of the class
|
|
.Fa nettype .
|
|
See
|
|
.Xr rpc 3 .
|
|
This routine returns 0 if the registration succeeded,
|
|
-1 otherwise.
|
|
.Pp
|
|
.It Fn svc_reg
|
|
Associates
|
|
.Fa prognum
|
|
and
|
|
.Fa versnum
|
|
with the service dispatch procedure,
|
|
.Fa dispatch .
|
|
If
|
|
.Fa netconf
|
|
is
|
|
.Dv NULL ,
|
|
the service is not registered with the
|
|
.Xr rpcbind 8
|
|
service.
|
|
If
|
|
.Fa netconf
|
|
is non-zero,
|
|
then a mapping of the triple
|
|
[
|
|
.Fa prognum ,
|
|
.Fa versnum ,
|
|
.Fa netconf->nc_netid ]
|
|
to
|
|
.Fa xprt->xp_ltaddr
|
|
is established with the local rpcbind
|
|
service.
|
|
.Pp
|
|
The
|
|
.Fn svc_reg
|
|
routine returns 1 if it succeeds,
|
|
and 0 otherwise.
|
|
.Pp
|
|
.It Fn svc_unreg
|
|
Remove from the rpcbind
|
|
service, all mappings of the triple
|
|
[
|
|
.Fa prognum ,
|
|
.Fa versnum ,
|
|
all-transports ]
|
|
to network address
|
|
and all mappings within the RPC service package
|
|
of the double
|
|
[
|
|
.Fa prognum ,
|
|
.Fa versnum ]
|
|
to dispatch routines.
|
|
.Pp
|
|
.It Fn svc_auth_reg
|
|
Registers the service authentication routine
|
|
.Fa handler
|
|
with the dispatch mechanism so that it can be
|
|
invoked to authenticate RPC requests received
|
|
with authentication type
|
|
.Fa cred_flavor .
|
|
This interface allows developers to add new authentication
|
|
types to their RPC applications without needing to modify
|
|
the libraries.
|
|
Service implementors usually do not need this routine.
|
|
.Pp
|
|
Typical service application would call
|
|
.Fn svc_auth_reg
|
|
after registering the service and prior to calling
|
|
.Fn svc_run .
|
|
When needed to process an RPC credential of type
|
|
.Fa cred_flavor ,
|
|
the
|
|
.Fa handler
|
|
procedure will be called with two parameters
|
|
.Fa "struct svc_req *rqst" ,
|
|
and
|
|
.Fa "struct rpc_msg * msg" ,
|
|
and is expected to return a valid
|
|
.Vt "enum auth_stat"
|
|
value.
|
|
There is no provision to change or delete an authentication handler
|
|
once registered.
|
|
.Pp
|
|
The
|
|
.Fn svc_auth_reg
|
|
routine returns 0 if the registration is successful,
|
|
1 if
|
|
.Fa cred_flavor
|
|
already has an authentication handler registered for it,
|
|
and -1 otherwise.
|
|
.Pp
|
|
.It Fn xprt_register
|
|
After RPC service transport handle
|
|
.Fa xprt
|
|
is created, it is registered with the RPC
|
|
service package. This routine modifies the global variable
|
|
.Va svc_fdset
|
|
(see
|
|
.Xr rpc_svc_calls 3 ).
|
|
Service implementors usually do not need this routine.
|
|
.Pp
|
|
.It Fn xprt_unregister
|
|
Before an RPC service transport handle
|
|
.Fa xprt
|
|
is destroyed, it unregisters itself with the
|
|
RPC service package.
|
|
This routine modifies the global variable
|
|
.Va svc_fdset
|
|
(see
|
|
.Xr rpc_svc_calls 3 ).
|
|
Service implementors usually do not need this routine.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr rpcbind 8 ,
|
|
.Xr rpc 3 ,
|
|
.Xr rpc_svc_calls 3 ,
|
|
.Xr rpc_svc_create 3 ,
|
|
.Xr rpc_svc_err 3 ,
|
|
.Xr rpcbind 3 ,
|
|
.Xr select 3
|