rpc_svc_create(3R)rpc_svc_create(3R)NAME
rpc_svc_create: svc_create, svc_destroy, svc_dg_create, svc_fd_create,
svc_raw_create, svc_tli_create, svc_tp_create, svc_vc_create,
svcraw_create, svctcp_create, svcudp_bufcreate, svcudp_create - library
routines for dealing with the creation of server handles
DESCRIPTION
These routines are part of the RPC library which allows C language
programs to make procedure calls on servers across the network. These
routines deal with the creation of service handles. Once the handle is
created, the server can be invoked by calling svc_run.
This page describes functions in the IRIX standard C library (libc).
Some of these functions are part of the new Transport Independent RPC
(TI-RPC) functionality added to the IRIX standard C library in IRIX
release 6.5.21 (known as BSD TI-RPC) and should not be confused with the
older TI-RPC functionality in the UNIX System V Networking Library (known
as System V TI-RPC, see intro(3N)). In particular, the BSD TI-RPC
functions use the BSD socket network API instead of the System V TLI
network API.
BSD TI-RPC functions are marked in this page as BSD TI-RPC only. To use
them code must be compiled with:
cc -D_BSD_TIRPC prog.c
The BSD TI-RPC functions in this page did not exist in IRIX before
release 6.5.21. Applications using them should use the
_MIPS_SYMBOL_PRESENT macro to provide a graceful failure mode when run on
older IRIX releases.
Routines
#include <rpc/rpc.h>
#ifdef _BSD_TIRPC
#include <netconfig.h>
#endif
int
svc_create(
void (*dispatch)(struct svc_req *, SVCXPRT *),
rpcprog_t prognum, rpcvers_t versnum,
const char *nettype);
BSD TI-RPC only. svc_create creates server handles for all the
transports belonging to the class nettype.
nettype defines a class of transports which can be used for a
particular application. The transports are tried in left to right
order in NETPATH variable or in top to down order in the netconfig
database.
Page 1
rpc_svc_create(3R)rpc_svc_create(3R)
If nettype is NULL, it defaults to netpath. svc_create registers
itself with the rpcbind service [see rpcbind(1M)]. dispatch is
called when there is a remote procedure call for the given prognum
and versnum; this requires calling svc_run [see svc_run in rpc(3R)].
If it succeeds, svc_create returns the number of server handles it
created, otherwise it returns 0 and the error message is logged.
void
svc_destroy(SVCXPRT *xprt);
A function 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.
SVCXPRT *
svc_dg_create(int fd, u_int sendsz, u_int recvsz);
BSD TI-RPC only. This routine creates a connectionless RPC service
handle, and returns a pointer to it. This routine returns NULL if
it fails, and an error message is logged. sendsz and recvsz are
parameters used to specify the size of the buffers. If they are 0,
suitable defaults are chosen. The file descriptor fd should be open
and bound.
Note: since connectionless-based RPC messages can only hold limited
amount of encoded data, this transport cannot be used for procedures
that take large arguments or return huge results.
SVCXPRT *
svc_fd_create(int fd, u_int sendsz, u_int recvsz);
BSD TI-RPC only. This routine creates a service on top of any open
and bound descriptor, and returns the handle to it. Typically, this
descriptor is a connected file descriptor for a connection-oriented
transport. sendsz and recvsz indicate sizes for the send and
receive buffers. If they are 0, a reasonable default is chosen.
This routine returns NULL, if it fails, and an error message is
logged.
SVCXPRT *
svc_raw_create(void);
BSD TI-RPC only. This routine 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 clnt_raw_create in
rpc_clnt_create(3R)]. 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, and an
error message is logged.
Page 2
rpc_svc_create(3R)rpc_svc_create(3R)
SVCXPRT *
svc_tli_create(int fd, struct netconfig *netconf,
struct t_bind *bindaddr, u_int sendsz,
u_int recvsz);
BSD TI-RPC only. This routine creates an RPC server handle, and
returns a pointer to it. fd is the file descriptor on which the
service is listening. If fd is RPC_ANYFD, it opens a file descriptor
on the transport specified by netconf. If the file descriptor is
unbound, it is bound to the address specified by bindaddr, if
bindaddr is non-null, otherwise it is bound to a default address
chosen by the transport. In the case where the default address is
chosen, the number of outstanding connect requests is set to 8 for
connection-oriented transports. The user may specify the size of
the send and receive buffers with the parameters sendsz and recvsz;
values of 0 choose suitable defaults. This routine returns NULL if
it fails, and an error message is logged.
SVCPRT *
svc_tp_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
rpcprog_t prognum, rpcvers_t versnum,
struct netconfig *netconf);
BSD TI-RPC only. svc_tp_create creates a server handle for the
network specified by netconf, and registers itself with the rpcbind
service. dispatch is called when there is a remote procedure call
for the given prognum and versnum; this requires calling svc_run.
svc_tp_create returns the service handle if it succeeds, otherwise a
NULL is returned, and an error message is logged.
SVCXPRT *
svc_vc_create(int fd, u_int sendsz, u_int recvsz);
BSD TI-RPC only. This routine creates a connection-oriented RPC
service and returns a pointer to it. This routine returns NULL if
it fails, and an error message is logged. The users may specify the
size of the send and receive buffers with the parameters sendsz and
recvsz; values of 0 choose suitable defaults. The file descriptor
fd should be open and bound.
SVCXPRT *
svcraw_create(void)
This routine 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.
Page 3
rpc_svc_create(3R)rpc_svc_create(3R)
SVCXPRT *
svctcp_create(int sock, u_int sendsize, u_int recvsize)
This routine creates a TCP/IP-based RPC service transport, to which
it returns a pointer. The transport is associated with the socket
sock, which may be RPC_ANYSOCK, in which case a new socket is
created. If the socket is not bound to a local TCP 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. Since TCP-based RPC uses buffered I/O, users may
specify the size of the send and receive buffers; values of 0 choose
suitable defaults.
SVCXPRT *
svcfd_create(int fd, u_int sendsize, u_int recvsize)
Create a service on top of any open descriptor. Typically, this
descriptor is a connected socket for a stream protocol such as TCP.
sendsize and recvsize indicate sizes for the send and receive
buffers. If they are zero, a reasonable default is chosen.
SVCXPRT *
svcudp_bufcreate(int sock, u_int sendsize, u_int recvsize)
This routine creates a UDP/IP-based RPC service transport, to which
it returns a pointer. The transport is associated with the socket
sock, 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.
This allows the user to specify the maximun packet size for sending
and receiving UDP-based RPC messages.
SVCXPRT *
svcudp_create(int sock)
This routine creates a UDP/IP-based RPC service transport, to which
it returns a pointer. The transport is associated with the socket
sock, 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 number, and xprt->xp_port is
the transport's port number. This routine returns NULL if it fails.
Page 4
rpc_svc_create(3R)rpc_svc_create(3R)
Warning: since UDP-based RPC messages can only hold up to 8
kilobytes of encoded data, this transport cannot be used for
procedures that take large arguments or return huge results.
SEE ALSOgetnetconfigent(3R), rpcbind(1M), rpc(3R), rpc_svc_calls(3R),
rpc_svc_err(3R), rpc_svc_reg(3R)
Page 5
