rpc.3n

早期freebsd实现

u_long prognum, versnum, protocol;
u_short port;
.fi
.ft R
.IP
A user interface to the
.B portmap
service, which establishes a mapping between the triple
.RI [ prognum , versnum , protocol\fR]
and
.I port
on the machine's
.B portmap
service. The value of
.I protocol
is most likely
.B
.SM IPPROTO_UDP
or 
.BR \s-1IPPROTO_TCP\s0 .
This routine returns one if it succeeds, zero otherwise.
Automatically done by
.BR svc_register(\|) .
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
pmap_unset(prognum, versnum)
u_long prognum, versnum;
.fi
.ft R
.IP
A user interface to the
.B portmap
service, which destroys all mapping between the triple
.RI [ prognum , versnum , *\fR]
and
.B ports
on the machine's
.B portmap
service. This routine returns one if it succeeds, zero
otherwise.
.br
.if t .ne 15
.LP
.ft B
.nf
.sp .5
registerrpc(prognum, versnum, procnum, procname, inproc, outproc)
u_long prognum, versnum, procnum;
char *(*procname) (\|) ;
xdrproc_t inproc, outproc;
.fi
.ft R
.IP
Register procedure
.I procname
with the
.SM RPC
service package.  If a request arrives for program
.IR prognum ,
version
.IR versnum ,
and procedure
.IR procnum ,
.I procname
is called with a pointer to its parameter(s);
.I progname
should return a pointer to its static result(s);
.I inproc
is used to decode the parameters while
.I outproc
is used to encode the results.
This routine returns zero if the registration succeeded, \-1
otherwise.
.IP
Warning: remote procedures registered in this form
are accessed using the
.SM UDP/IP
transport; see
.B svcudp_create(\|)
for restrictions.
.br
.if t .ne 5
.LP
.ft B
.nf
.sp .5
struct rpc_createerr     rpc_createerr;
.fi
.ft R
.IP
A global variable whose value is set by any
.SM RPC
client creation routine
that does not succeed.  Use the routine
.B clnt_pcreateerror(\|)
to print the reason why.
.if t .ne 7
.LP
.ft B
.nf
.sp .5
svc_destroy(xprt)
\s-1SVCXPRT\s0 *
xprt;
.fi
.ft R
.IP
A macro that destroys the
.SM RPC
service transport handle,
.IR xprt .
Destruction usually involves deallocation
of private data structures, including
.I xprt
itself.  Use of
.I xprt
is undefined after calling this routine.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
fd_set svc_fdset;
.fi
.ft R
.IP
A global variable reflecting the
.SM RPC
service side's
read file descriptor bit mask; it is suitable as a parameter
to the
.B select
system call. This is only of interest
if a service implementor does not call
.BR svc_run(\|) ,
but rather does his own asynchronous event processing.
This variable is read-only (do not pass its address to
.BR select !),
yet it may change after calls to
.B svc_getreqset(\|)
or any creation routines.
.br
.if t .ne 6
.LP
.ft B
.nf
.sp .5
int svc_fds;
.fi
.ft R
.IP
Similar to
.BR svc_fedset(\|) ,
but limited to 32 descriptors. This
interface is obsoleted by
.BR svc_fdset(\|) .
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
svc_freeargs(xprt, inproc, in)
\s-1SVCXPRT\s0 *xprt;
xdrproc_t inproc;
char *in;
.fi
.ft R
.IP
A macro that frees any data allocated by the
.SM RPC/XDR
system when it decoded the arguments to a service procedure
using
.BR svc_getargs(\|) .
This routine returns 1 if the results were successfully
freed,
and zero otherwise.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
svc_getargs(xprt, inproc, in)
\s-1SVCXPRT\s0 *xprt;
xdrproc_t inproc;
char *in;
.fi
.ft R
.IP
A macro that decodes the arguments of an
.SM RPC
request
associated with the
.SM RPC
service transport handle,
.IR xprt .
The parameter
.I in
is the address where the arguments will be placed;
.I inproc
is the
.SM XDR
routine used to decode the arguments.
This routine returns one if decoding succeeds, and zero
otherwise.
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
struct sockaddr_in *
svc_getcaller(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
The approved way of getting the network address of the caller
of a procedure associated with the
.SM RPC
service transport handle,
.IR xprt .
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
svc_getreqset(rdfds)
fd_set *rdfds;
.fi
.ft R
.IP
This routine is only of interest if a service implementor
does not call
.BR svc_run(\|) ,
but instead implements custom asynchronous event processing.
It is called when the
.B select
system call has determined that an
.SM RPC
request has arrived on some
.SM RPC
.B socket(s) ;
.I rdfds
is the resultant read file descriptor bit mask.
The routine returns when all sockets associated with the
value of
.I rdfds
have been serviced.
.br
.if t .ne 6
.LP
.ft B
.nf
.sp .5
svc_getreq(rdfds)
int rdfds;
.fi
.ft R
.IP
Similar to
.BR svc_getreqset(\|) ,
but limited to 32 descriptors. This interface is obsoleted by
.BR svc_getreqset(\|) .
.br
.if t .ne 17
.LP
.ft B
.nf
.sp .5
svc_register(xprt, prognum, versnum, dispatch, protocol)
\s-1SVCXPRT\s0 *xprt;
u_long prognum, versnum;
void (*dispatch) (\|);
u_long protocol;
.fi
.ft R
.IP
Associates
.I prognum
and
.I versnum
with the service dispatch procedure,
.IR dispatch .
If
.I protocol
is zero, the service is not registered with the
.B portmap
service.  If
.I protocol
is non-zero, then a mapping of the triple
.RI [ prognum , versnum , protocol\fR]
to
\fB\%xprt\->xp_port\fR
is established with the local
.B portmap
service (generally
.I protocol
is zero,
.B
.SM IPPROTO_UDP
or 
.B
.SM IPPROTO_TCP
).
The procedure
.I dispatch
has the following form:
.RS 1i
.ft B
.nf
dispatch(request, xprt)
struct svc_req *request;
\s-1SVCXPRT\s0 *xprt;
.ft R
.fi
.RE
.IP
The
.B svc_register(\|)
routine returns one if it succeeds, and zero otherwise.
.br
.if t .ne 6
.LP
.ft B
.nf
.sp .5
svc_run(\|)
.fi
.ft R
.IP
This routine never returns. It waits for
.SM RPC
requests to arrive, and calls the appropriate service
procedure using
.B svc_getreq(\|)
when one arrives. This procedure is usually waiting for a
.B select(\|)
system call to return.
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
svc_sendreply(xprt, outproc, out)
\s-1SVCXPRT\s0 *xprt;
xdrproc_t outproc;
char *out;
.fi
.ft R
.IP
Called by an
.SM RPC
service's dispatch routine to send the results of a
remote procedure call.  The parameter
.I xprt
is the request's associated transport handle;
.I outproc
is the
.SM XDR
routine which is used to encode the results; and
.I out
is the address of the results.
This routine returns one if it succeeds, zero otherwise.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
svc_unregister(prognum, versnum)
u_long prognum, versnum;
.fi
.ft R
.IP
Remove all mapping of the double
.RI [ prognum , versnum ]
to dispatch routines, and of the triple
.RI [ prognum , versnum , *\fR]
to port number.
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
void
svcerr_auth(xprt, why)
\s-1SVCXPRT\s0 *xprt;
enum auth_stat why;
.fi
.ft R
.IP
Called by a service dispatch routine that refuses to perform
a remote procedure call due to an authentication error.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
svcerr_decode(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Called by a service dispatch routine that cannot successfully
decode its parameters. See also
.BR svc_getargs(\|) .
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
svcerr_noproc(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Called by a service dispatch routine that does not implement
the procedure number that the caller requests.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
svcerr_noprog(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Called when the desired program is not registered with the
.SM RPC
package. Service implementors usually do not need this routine.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
svcerr_progvers(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Called when the desired version of a program is not registered
with the
.SM RPC
package. Service implementors usually do not need this routine.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
svcerr_systemerr(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Called by a service dispatch routine when it detects a system
error
not covered by any particular protocol.
For example, if a service can no longer allocate storage,
it may call this routine.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
void
svcerr_weakauth(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Called by a service dispatch routine that refuses to perform
a remote procedure call due to insufficient
authentication parameters.  The routine calls
.BR "svcerr_auth(xprt, \s-1AUTH_TOOWEAK\s0)" .
.br
.if t .ne 11
.LP
.ft B
.nf
.sp .5
\s-1SVCXPRT\s0 *
svcraw_create(\|)
.fi
.ft R
.IP
This routine creates a toy
.SM RPC
service transport, to which it returns a pointer.  The
transport
is really a buffer within the process's address space,
so the corresponding
.SM RPC
client should live in the same
address space;
see
.BR clntraw_create(\|) .
This routine allows simulation of
.SM RPC
and acquisition of
.SM RPC
overheads (such as round trip times), without any kernel
interference.
This routine returns
.SM NULL
if it fails.
.br
.if t .ne 11
.LP
.ft B
.nf
.sp .5
\s-1SVCXPRT\s0 *
svctcp_create(sock, send_buf_size, recv_buf_size)
int sock;
u_int send_buf_size, recv_buf_size;
.fi
.ft R
.IP
This routine creates a
.SM TCP/IP\s0-based
.SM RPC
service transport, to which it returns a pointer.
The transport is associated with the socket
.IR sock ,
which may be
.BR \s-1RPC_ANYSOCK\s0 ,
in which case a new socket is created.
If the socket is not bound to a local
.SM TCP
port, then this routine binds it to an arbitrary port.  Upon
completion,
\fB\%xprt\->xp_sock\fR
is the transport's socket descriptor, and
\fB\%xprt\->xp_port\fR
is the transport's port number.
This routine returns
.SM NULL
if it fails. Since
.SM TCP\s0-based
.SM RPC
uses buffered
.SM I/O ,
users may specify the size of buffers; values of zero
choose suitable defaults.
.br
.if t .ne 11
.LP
.ft B
.nf
.sp .5
\s-1SVCXPRT\s0 *
svcfd_create(fd, sendsize, recvsize)
int fd;
u_int sendsize;
u_int recvsize;
.fi
.ft R
.IP
Create a service on top of any open descriptor. Typically,
this
descriptor is a connected socket for a stream protocol such
as
.SM TCP\s0.
.I sendsize
and
.I recvsize
indicate sizes for the send and receive buffers.  If they are
zero, a reasonable default is chosen.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
\s-1SVCXPRT\s0 *
svcudp_bufcreate(sock, sendsize, recosize)
int sock;
.fi
.ft R
.IP
This routine creates a
.SM UDP/IP\s0-based
.SM RPC
service transport, to which it returns a pointer.
The transport is associated with the socket
.IR sock ,
which may be
.B \s-1RPC_ANYSOCK\s0 ,
in which case a new socket is created.
If the socket is not bound to a local
.SM UDP
port, then this routine binds it to an arbitrary port. Upon
completion,
\fB\%xprt\->xp_sock\fR
is the transport's socket descriptor, and
\fB\%xprt\->xp_port\fR
is the transport's port number.
This routine returns
.SM NULL
if it fails.
.IP
This allows the user to specify the maximun packet size for sending and 
receiving
.SM UDP\s0-based
.SM RPC messages.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_accepted_reply(xdrs, ar)
\s-1XDR\s0 *xdrs;
struct accepted_reply *ar;
.fi
.ft R
.IP
Used for encoding
.SM RPC
reply messages. This routine is useful for users who
wish to generate
\s-1RPC\s0-style
messages without using the
.SM RPC
package.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_authunix_parms(xdrs, aupp)
\s-1XDR\s0 *xdrs;
struct authunix_parms *aupp;
.fi
.ft R
.IP
Used for describing
.SM UNIX
credentials. This routine is useful for users
who wish to generate these credentials without using the
.SM RPC
authentication package.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
void
xdr_callhdr(xdrs, chdr)
\s-1XDR\s0 *xdrs;
struct rpc_msg *chdr;
.fi
.ft R
.IP
Used for describing
.SM RPC
call header messages.
This routine is useful for users who wish to generate
.SM RPC\s0-style
messages without using the
.SM RPC
package.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_callmsg(xdrs, cmsg)
\s-1XDR\s0 *xdrs;
struct rpc_msg *cmsg;
.fi
.ft R
.IP
Used for describing
.SM RPC
call messages.
This routine is useful for users who wish to generate
.SM RPC\s0-style
messages without using the
.SM RPC
package.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_opaque_auth(xdrs, ap)
\s-1XDR\s0 *xdrs;
struct opaque_auth *ap;
.fi
.ft R
.IP
Used for describing
.SM RPC
authentication information messages.
This routine is useful for users who wish to generate
.SM RPC\s0-style
messages without using the
.SM RPC
package.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_pmap(xdrs, regs)
\s-1XDR\s0 *xdrs;
struct pmap *regs;
.fi
.ft R
.IP
Used for describing parameters to various
.B portmap
procedures, externally.
This routine is useful for users who wish to generate
these parameters without using the
.B pmap
interface.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_pmaplist(xdrs, rp)
\s-1XDR\s0 *xdrs;
struct pmaplist **rp;
.fi
.ft R
.IP
Used for describing a list of port mappings, externally.
This routine is useful for users who wish to generate
these parameters without using the
.B pmap
interface.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_rejected_reply(xdrs, rr)
\s-1XDR\s0 *xdrs;
struct rejected_reply *rr;
.fi
.ft R
.IP
Used for describing
.SM RPC
reply messages.
This routine is useful for users who wish to generate
.SM RPC\s0-style
messages without using the
.SM RPC
package.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_replymsg(xdrs, rmsg)
\s-1XDR\s0 *xdrs;
struct rpc_msg *rmsg;
.fi
.ft R
.IP
Used for describing
.SM RPC
reply messages.
This routine is useful for users who wish to generate
.SM RPC
style messages without using the
.SM RPC
package.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
void
xprt_register(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
After
.SM RPC
service transport handles are created,
they should register themselves with the
.SM RPC
service package.
This routine modifies the global variable
.BR svc_fds(\|) .
Service implementors usually do not need this routine.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
void
xprt_unregister(xprt)
\s-1SVCXPRT\s0 *xprt;
.fi
.ft R
.IP
Before an
.SM RPC
service transport handle is destroyed,
it should unregister itself with the
.SM RPC
service package.
This routine modifies the global variable
.BR svc_fds(\|) .
Service implementors usually do not need this routine.
.SH SEE ALSO
.BR rpc_secure (3N),
.BR xdr (3N)
.br
The following manuals:
.RS
.ft I
Remote Procedure Calls: Protocol Specification
.br
Remote Procedure Call Programming Guide
.br
rpcgen Programming Guide
.br
.ft R
.RE
.IR "\s-1RPC\s0: Remote Procedure Call Protocol Specification" ,
.SM RFC1050, Sun Microsystems, Inc.,
.SM USC-ISI\s0.