 |
Index for
Section 3 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
rpc_svc(3)
NAME
svc_destroy, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller,
svc_getreq, svc_getreqset, svc_register, svc_run, svc_sendreply,
svc_unregister, svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog,
svcerr_progvers, svcerr_systemerr, svcerr_weakauth, svcfd_create,
svcraw_create, svctcp_create, svcudp_create - library routines for ONC
server remote procedure calls
SYNOPSIS
svc_destroy(
SVCXPRT *xprt );
fd_set svc_fdset;
int svc_fds;
svc_freeargs(
SVCXPRT *xprt,
xdrproc_t inproc,
char *in );
svc_getargs(
SVCXPRT *xprt,
xdrproc_t inproc,
char *in );
struct sockaddr_in *svc_getcaller(
SVCXPRT *xprt );
svc_getreq(
int rdfds );
svc_getreqset(
fd_set *rdfds );
svc_register(
SVCXPRT *xprt,
u_int prognum,
u_int versnum,
void (*dispatch) (),
int protocol );
svc_run(
void );
svc_sendreply(
SVCXPRT *xprt,
xdrproc_t outproc,
char *out );
void svc_unregister
u_int prognum,
u_int versnum );
void svcerr_auth(
SVCXPRT *xprt,
num auth_stat why );
void svcerr_decode(
SVCXPRT *xprt );
void svcerr_noproc(
SVCXPRT *xprt );
void svcerr_noprog(
SVCXPRT *xprt );
void svcerr_progvers(
SVCXPRT *xprt );
void svcerr_systemerr(
SVCXPRT *xprt );
void svcerr_weakauth(
SVCXPRT *xprt );
voidsvcfd_create(
int fd,
u_int sendsize,
u_int recvsize );
SVCXPRT * svcraw_create(
void );
SVCXPRT * svctcp_create(
int sock,
u_int send_buf_size,
u_int recv_buf_size );
SVCXPRT * svcudp_create(
int sock );
DESCRIPTION
These routines allow C programs to make procedure calls on other machines
across the network. First, the client calls a procedure to send a data
packet to the server. Upon receipt of the packet, the server calls a
dispatch routine to perform the requested service, and then sends back a
reply. Finally, the procedure call returns to the client.
Unless otherwise indicated, the routines described in this reference page
are thread safe (that is, they can be used safely in a multithreaded
environment). Routines that are not thread safe are flagged as such.
svc_destroy()
[Not Thread Safe] A macro that destroys the RPC service transport
handle, xprt. Destruction usually involves deallocation of private data
structures, including xprt itself. Use of xprt is undefined after
calling this routine.
fd_set svc_fdset;
A global variable that reflects the RPC service side's read file
descriptor bit mask; it is suitable as a parameter to the select system
call. This is only of interest if a service implementor does not call
svc_run(), but rather does his own asynchronous event processing. This
variable is read-only (do not pass its address to select), yet it may
change after calls to svc_getreqset() or any creation routines.
int svc_fds;
Similar to svc_fdset(), but limited to 32 descriptors. This interface
is obsoleted by svc_fdset().
svc_freeargs()
[Not Thread Safe] A macro that frees any data allocated by the RPC/XDR
system when it decoded the arguments to a service procedure using
svc_getargs(). This routine returns 1 if the results were successfully
freed, and zero (0) otherwise.
svc_getargs()
[Not Thread Safe] A macro that decodes the arguments of an RPC request
associated with the RPC service transport handle, xprt. The in
parameter is the address where the arguments will be placed; inproc is
the XDR routine used to decode the arguments. This routine returns one
(1) if decoding succeeds, and zero (0) otherwise.
struct sockaddr_in *svc_getcaller()
[Not Thread Safe] The approved way of getting the network address of
the caller of a procedure associated with the RPC service transport
handle, xprt.
svc_getreq()
[Not Thread Safe] Similar to svc_getreqset(), but limited to 32
descriptors. This interface is obsoleted by svc_getreqset().
svc_getreqset()
[Not Thread Safe] This routine is only of interest if a service
implementor does not call svc_run(), but instead implements custom
asynchronous event processing. It is called when the select system call
has determined that an RPC request has arrived on some RPC socket(s);
rdfds is the resultant read file descriptor bit mask. The routine
returns when all sockets associated with the value of rdfds have been
serviced.
svc_register()
[Not Thread Safe] Associates prognum and versnum with the service
dispatch procedure, dispatch. If protocol is zero, the service is not
registered with the portmap service. If protocol is non-zero, a mapping
of the triple [prognum, versnum, protocol] to xprt->xp_port is
established with the local portmap service (generally protocol is zero,
IPPROTO_UDP or IPPROTO_TCP). The dispatch procedure has the following
form:
dispatch(
struct svc_req *request,
SVCXPRT *xprt);
The svc_register() routine returns one (1) if it succeeds, and zero (0)
otherwise.
svc_run()
[Not Thread Safe] This routine waits for RPC requests to arrive, and
calls the appropriate service procedure using svc_getreq() when one
arrives. This procedure is usually waiting for a select() system call
to return.
svc_sendreply()
[Not Thread Safe] Called by an RPC service's dispatch routine to send
the results of a remote procedure call. The xprt parameter is the
request's associated transport handle; outproc is the XDR routine which
is used to encode the results; and out is the address of the results.
This routine returns one (1) if it succeeds, zero (0) otherwise.
void svc_unregister()
[Not Thread Safe] Removes all mapping of the double [prognum,versnum]
to dispatch routines, and of the triple [prognum,versnum,*] to port
number.
void svcerr_auth()
[Not Thread Safe] Called by a service dispatch routine that refuses
to perform a remote procedure call due to an authentication error.
void svcerr_decode()
[Not Thread Safe] Called by a service dispatch routine that cannot
successfully decode its parameters. See also svc_getargs().
void svcerr_noproc()
[Not Thread Safe] Called by a service dispatch routine that does not
implement the procedure number that the caller requests.
void svcerr_noprog()
[Not Thread Safe] Called when the desired program is not registered
with the RPC package. Service implementors usually do not need this
routine.
void svcerr_progvers()
[Not Thread Safe] Called when the desired version of a program is not
registered with the RPC package. Service implementors usually do not
need this routine.
void svcerr_systemerr()
[Not Thread Safe] 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.
void svcerr_weakauth()
[Not Thread Safe] Called by a service dispatch routine that refuses to
perform a remote procedure call due to insufficient (but correct)
authentication parameters. The routine calls
svcerr_auth(xprt,AUTH_TOOWEAK).
voidsvcfd_create()
[Not Thread Safe] Creates a service on top of any open descriptor.
Typically, this descriptor is a connected socket for a stream protocol
such as TCP. The sendsize and recvsize parameters indicate sizes for
the send and receive buffers. If they are zero (0), a reasonable
default is chosen.
SVCXPRT * svcraw_create()
[Not Thread Safe] Creates a toy RPC service transport, to which it
returns a pointer. The transport is really a buffer within the
process's address space, so the corresponding RPC client should live in
the same address space; see clntraw_create(). This routine allows
simulation of RPC and acquisition of RPC overheads (such as round trip
times), without any kernel interference. This routine returns NULL if
it fails.
SVCXPRT * svctcp_create()
[Not Thread Safe] Creates a TCP/IP-based RPC service transport, to
which it returns a pointer. The transport is associated with the sock
socket, which may be RPC_ANYSOCK, in which case a new socket is
created. If the socket is not bound to a local TCP port, this routine
binds it to an arbitrary port. Upon completion, xprt->xp_sock is the
transport's socket descriptor, and xprt->xp_port is the transport's
port number. This routine returns NULL if it fails. Since TCP-based RPC
uses buffered I/O , users may specify the size of buffers; values of
zero (0) choose suitable defaults.
SVCXPRT * svcudp_create()
[Not Thread Safe] Creates a UDP/IP-based RPC service transport, to
which it returns a pointer. The transport is associated with the sock
socket, which may be RPC_ANYSOCK, in which case a new socket is
created. If the socket is not bound to a local UDP port, then this
routine binds it to an arbitrary port. Upon completion, xprt->xp_sock
is the transport's socket descriptor, and xprt->xp_port is the
transport's port number. This routine returns NULL if it fails.
Warning: Since UDP-based RPC messages can only hold up to 8 Kbytes of
encoded data, this transport cannot be used for procedures that take
large arguments or return huge results.
SEE ALSO
rpc-clnt(3), rpc-misc(3), rpc-xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specification - RFC 1050
|
Index for
Section 3 |
|
|
Alphabetical
listing for R |
|
 |
Top of
page |
|