Tribblix: manual page: rpc

RPC_SOC(3NSL) Networking Services Library Functions RPC_SOC(3NSL)

NAME

rpc_soc, authdes_create, authunix_create, authunix_create_default,
callrpc, clnt_broadcast, clntraw_create, clnttcp_create,
clntudp_bufcreate, clntudp_create, get_myaddress, getrpcport,
pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, pmap_unset,
registerrpc, svc_fds, svc_getcaller, svc_getreq, svc_register,
svc_unregister, svcfd_create, svcraw_create, svctcp_create,
svcudp_bufcreate, svcudp_create, xdr_authunix_parms - obsolete
library routines for RPC

SYNOPSIS

#define PORTMAP
#include <rpc/rpc.h>

AUTH *authdes_create(char *name, uint_t window,
struct sockaddr_in *syncaddr, des_block *ckey,
int calltype, AUTH **retauth);

AUTH *authunix_create(char *host, uid_t uid, gid_t gid,
int grouplen, gid_t *gidlistp);

AUTH *authunix_create_default(void)

int callrpc(char *host, rpcprog_t prognum, rpcvers_t versnum,
rpcproc_t procnum, xdrproc_t inproc, char *in,
xdrproc_t outproc, char *out);

enum clnt_stat_clnt_broadcast(rpcprog_t prognum, rpcvers_t versnum,
rpcproc_t procnum, xdrproc_t inproc, char *in,
xdrproc_t outproc, char *out, resultproc_t eachresult);

CLIENT *clntraw_create(rpcproc_t procnum, rpcvers_t versnum);

CLIENT *clnttcp_create(struct sockaddr_in *addr,
rpcprog_t prognum, rpcvers_t versnum, int *fdp,
uint_t sendz, uint_t recvsz);

CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, rpcprog_t prognum,
rpcvers_t versnum, struct timeval wait,
int *fdp, uint_t sendz, uint_t recvsz);

CLIENT *clntudp_create(struct sockaddr_in *addr, rpcprog_t prognum,
rpcvers_t versnum, struct timeval wait, int *fdp);

void get_myaddress(struct sockaddr_in *addr);

ushort getrpcport(char *host, rpcprog_t prognum,
rpcvers_t versnum, rpcprot_t proto);

struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);

ushort pmap_getport(struct sockaddr_in *addr,
rpcprog_t prognum, rpcvers_t versnum,
rpcprot_t protocol);

enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr,
rpcprog_t prognum, rpcvers_t versnum,
rpcproc_t progcnum, caddr_t in, xdrproct_t inproc,
caddr_t out, cdrproct_t outproc,
struct timeval tout, rpcport_t *portp);

bool_t pmap_set(rpcprog_t prognum, rpcvers_t versnum,
rpcprot_t protocol, u_short port);

bool_t pmap_unset(rpcprog_t prognum, rpcvers_t versnum);

int svc_fds;

struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);

void svc_getreq(int rdfds);

SVCXPRT *svcfd_create(int fd, uint_t sendsz,
uint_t recvsz);

SVCXPRT *svcraw_create(void)

SVCXPRT *svctcp_create(int fd, uint_t sendsz,
uint_t recvsz);

SVCXPRT *svcudp_bufcreate(int fd, uint_t sendsz,
uint_t recvsz);

SVCXPRT *svcudp_create(int fd);

int registerrpc(rpcprog_t prognum, rpcvers_t versnum, rpcproc_t procnum,
char *(*procname)(), xdrproc_t inproc, xdrproc_t outproc);

bool_t svc_register(SVCXPRT *xprt, rpcprog_t prognum, rpcvers_t versnum,
void (*)dispatch(), int protocol);

void svc_unregister(rpcprog_t prognum, rpcvers_t versnum);

bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *supp);

DESCRIPTION

RPC routines allow C programs to make procedure calls on other
machines across the network. First, the client calls a procedure to
send a request to the server. Upon receipt of the request, 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.

The routines described in this manual page have been superseded by
other routines. The preferred routine is given after the description
of the routine. New programs should use the preferred routines, as
support for the older interfaces may be dropped in future releases.

File Descriptors

Transport independent RPC uses TLI as its transport interface instead
of sockets.

Some of the routines described in this section (such as
clnttcp_create()) take a pointer to a file descriptor as one of the
parameters. If the user wants the file descriptor to be a socket,
then the application will have to be linked with both librpcsoc and
libnsl. If the user passed RPC_ANYSOCK as the file descriptor, and
the application is linked with libnsl only, then the routine will
return a TLI file descriptor and not a socket.

Routines

The following routines require that the header <rpc/rpc.h> be
included. The symbol PORTMAP should be defined so that the
appropriate function declarations for the old interfaces are included
through the header files.

authdes_create()
authdes_create() is the first of two
routines which interface to the RPC
secure authentication system, known as
DES authentication. The second is
authdes_getucred(), see
secure_rpc(3NSL). Note: the keyserver
daemon keyserv(8) must be running for
the DES authentication system to work.

authdes_create(), used on the client
side, returns an authentication handle
that will enable the use of the secure
authentication system. The first
parameter name is the network name, or
netname, of the owner of the server
process. This field usually represents
a hostname derived from the utility
routine host2netname(), but could also
represent a user name using
user2netname(). See secure_rpc(3NSL).
The second field is window on the
validity of the client credential,
given in seconds. A small window is
more secure than a large one, but
choosing too small of a window will
increase the frequency of
resynchronizations because of clock
drift. The third parameter syncaddr is
optional. If it is NULL, then the
authentication system will assume that
the local clock is always in sync with
the server's clock, and will not
attempt resynchronizations. If an
address is supplied, however, then the
system will use the address for
consulting the remote time service
whenever resynchronization is required.
This parameter is usually the address
of the RPC server itself. The final
parameter ckey is also optional. If it
is NULL, then the authentication system
will generate a random DES key to be
used for the encryption of credentials.
If it is supplied, however, then it
will be used instead.

This routine exists for backward
compatibility only, and it is made
obsolete by authdes_seccreate(). See
secure_rpc(3NSL).

authunix_create()
Create and return an RPC authentication
handle that contains UNIX
authentication information. The
parameter host is the name of the
machine on which the information was
created; uid is the user's user ID; gid
is the user's current group ID;
grouplen and gidlistp refer to a
counted array of groups to which the
user belongs.

It is not very difficult to impersonate
a user.

This routine exists for backward
compatibility only, and it is made
obsolete by authsys_create(). See
rpc_clnt_auth(3NSL).

authunix_create_default()
Call authunix_create() with the
appropriate parameters.

This routine exists for backward
compatibility only, and it is made
obsolete by authsys_create_default().
See rpc_clnt_auth(3NSL).

callrpc()
Call the remote procedure associated
with prognum, versnum, and procnum on
the machine, host. The parameter inproc
is used to encode the procedure's
parameters, and outproc is used to
decode the procedure's results; in is
the address of the procedure's
argument, and out is the address of
where to place the result(s). This
routine returns 0 if it succeeds, or
the value of enum clnt_stat cast to an
integer if it fails. The routine
clnt_perrno() is handy for translating
failure statuses into messages. See
rpc_clnt_calls(3NSL).

You do not have control of timeouts or
authentication using this routine. This
routine exists for backward
compatibility only, and is made
obsolete by rpc_call(). See
rpc_clnt_calls(3NSL).

clnt_stat_clnt_broadcast()
Like callrpc(), except the call message
is broadcast to all locally connected
broadcast nets. Each time the caller
receives a response, this routine calls
eachresult(), whose form is:

eachresult(char *out, struct sockaddr_in *addr);

where out is the same as out passed to
clnt_broadcast(), except that the
remote procedure's output is decoded
there; addr points to the address of
the machine that sent the results. If
eachresult() returns 0,
clnt_broadcast() waits for more
replies; otherwise it returns with
appropriate status. If eachresult() is
NULL, clnt_broadcast() returns without
waiting for any replies.

Broadcast packets are limited in size
to the maximum transfer unit of the
transports involved. For Ethernet, the
caller's argument size is approximately
1500 bytes. Since the call message is
sent to all connected networks, it may
potentially lead to broadcast storms.
clnt_broadcast() uses AUTH_SYS
credentials by default. See
rpc_clnt_auth(3NSL). This routine
exists for backward compatibility only,
and is made obsolete by
rpc_broadcast(). See
rpc_clnt_calls(3NSL).

clntraw_create()
This routine creates an internal,
memory-based RPC client for the remote
program prognum, version versnum. The
transport used to pass messages to the
service is actually a buffer within the
process's address space, so the
corresponding RPC server should live in
the same address space. See
svcraw_create(). This 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.

This routine exists for backward
compatibility only. It has the same
functionality as clnt_raw_create(). See
rpc_clnt_create(3NSL), which obsoletes
it.

clnttcp_create()
This routine creates an RPC client for
the remote program prognum, version
versnum; the client uses TCP/IP as a
transport. The remote program is
located at Internet address addr. If
addr->sin_port is 0, then it is set to
the actual port that the remote program
is listening on. The remote rpcbind
service is consulted for this
information. The parameter *fdp is a
file descriptor, which may be open and
bound; if it is RPC_ANYSOCK, then this
routine opens a new one and sets *fdp.
Refer to the File Descriptor section
for more information. Since TCP-based
RPC uses buffered I/O, 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.

This routine exists for backward
compatibility only. clnt_create(),
clnt_tli_create(), or clnt_vc_create()
should be used instead. See
rpc_clnt_create(3NSL).

clntudp_bufcreate()
Create a client handle for the remote
program prognum, version versnum; the
client uses UDP/IP as the transport.
The remote program is located at the
Internet address addr. If
addr->sin_port is 0, it is set to port
on which the remote program is
listening on (the remote rpcbind
service is consulted for this
information). The parameter *fdp is a
file descriptor, which may be open and
bound. If it is RPC_ANYSOCK, then this
routine opens a new one and sets *fdp.
Refer to the File Descriptor section
for more information. The UDP transport
resends the call message in intervals
of wait time until a response is
received or until the call times out.
The total time for the call to time out
is specified by clnt_call(). See
rpc_clnt_calls(3NSL). If successful it
returns a client handle, otherwise it
returns NULL. The error can be printed
using the clnt_pcreateerror() routine.
See rpc_clnt_create(3NSL).

The user can specify the maximum packet
size for sending and receiving by using
sendsz and recvsz arguments for
UDP-based RPC messages.

If addr->sin_port is 0 and the
requested version number versnum is not
registered with the remote portmap
service, it returns a handle if at
least a version number for the given
program number is registered. The
version mismatch is discovered by a
clnt_call() later (see
rpc_clnt_calls(3NSL)).

This routine exists for backward
compatibility only. clnt_tli_create()
or clnt_dg_create() should be used
instead. See rpc_clnt_create(3NSL).

clntudp_create()
This routine creates an RPC client
handle for the remote program prognum,
version versnum; the client uses UDP/IP
as a transport. The remote program is
located at Internet address addr. If
addr->sin_port is 0, then it is set to
the actual port that the remote program
is listening on. The remote rpcbind
service is consulted for this
information. The parameter *fdp is a
file descriptor, which may be open and
bound; if it is RPC_ANYSOCK, then this
routine opens a new one and sets *fdp.
Refer to the File Descriptor section
for more information. The UDP transport
resends the call message in intervals
of wait time until a response is
received or until the call times out.
The total time for the call to time out
is specified by clnt_call(). See
rpc_clnt_calls(3NSL). clntudp_create()
returns a client handle on success,
otherwise it returns NULL. The error
can be printed using the
clnt_pcreateerror() routine. See
rpc_clnt_create(3NSL).

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.

This routine exists for backward
compatibility only. clnt_create(),
clnt_tli_create(), or clnt_dg_create()
should be used instead. See
rpc_clnt_create(3NSL).

get_myaddress()
Places the local system's IP address
into *addr, without consulting the
library routines that deal with
/etc/hosts. The port number is always
set to htons(PMAPPORT).

This routine is only intended for use
with the RPC library. It returns the
local system's address in a form
compatible with the RPC library, and
should not be taken as the system's
actual IP address. In fact, the *addr
buffer's host address part is actually
zeroed. This address may have only
local significance and should not be
assumed to be an address that can be
used to connect to the local system by
remote systems or processes.

This routine remains for backward
compatibility only. The routine
netdir_getbyname() should be used with
the name HOST_SELF to retrieve the
local system's network address as a
netbuf structure. See netdir(3NSL).

getrpcport()
getrpcport() returns the port number
for the version versnum of the RPC
program prognum running on host and
using protocol proto. getrpcport()
returns 0 if the RPC system failed to
contact the remote portmap service, the
program associated with prognum is not
registered, or there is no mapping
between the program and a port.

This routine exists for backward
compatibility only. Enhanced
functionality is provided by
rpcb_getaddr(). See rpcbind(3NSL).

pmaplist()
A user interface to the portmap
service, which returns a list of the
current RPC program-to-port mappings on
the host located at IP address addr.
This routine can return NULL. The
command `rpcinfo -p' uses this routine.

This routine exists for backward
compatibility only, enhanced
functionality is provided by
rpcb_getmaps(). See rpcbind(3NSL).

pmap_getport()
A user interface to the portmap
service, which returns the port number
on which waits a service that supports
program prognum, version versnum, and
speaks the transport protocol
associated with protocol. The value of
protocol is most likely IPPROTO_UDP or
IPPROTO_TCP. A return value of 0 means
that the mapping does not exist or that
the RPC system failed to contact the
remote portmap service. In the latter
case, the global variable rpc_createerr
contains the RPC status.

This routine exists for backward
compatibility only, enhanced
functionality is provided by
rpcb_getaddr(). See rpcbind(3NSL).

pmap_rmtcall()
Request that the portmap on the host at
IP address *addr make an RPC on the
behalf of the caller to a procedure on
that host. *portp is modified to the
program's port number if the procedure
succeeds. The definitions of other
parameters are discussed in callrpc()
and clnt_call(). See
rpc_clnt_calls(3NSL).

This procedure is only available for
the UDP transport.

If the requested remote procedure is
not registered with the remote portmap
then no error response is returned and
the call times out. Also, no
authentication is done.

This routine exists for backward
compatibility only, enhanced
functionality is provided by
rpcb_rmtcall(). See rpcbind(3NSL).

pmap_set()
A user interface to the portmap
service, that establishes a mapping
between the triple [prognum, versnum,
protocol] and port on the machine's
portmap service. The value of protocol
may be IPPROTO_UDP or IPPROTO_TCP.
Formerly, the routine failed if the
requested port was found to be in use.
Now, the routine only fails if it finds
that port is still bound. If port is
not bound, the routine completes the
requested registration. This routine
returns 1 if it succeeds, 0 otherwise.
Automatically done by svc_register().

This routine exists for backward
compatibility only, enhanced
functionality is provided by
rpcb_set(). See rpcbind(3NSL).

pmap_unset()
A user interface to the portmap
service, which destroys all mapping
between the triple [prognum, versnum,
all-protocols] and port on the
machine's portmap service. This
routine returns 1 if it succeeds, 0
otherwise.

This routine exists for backward
compatibility only, enhanced
functionality is provided by
rpcb_unset(). See rpcbind(3NSL).

svc_fds()
A global variable reflecting the RPC
service side's read file descriptor bit
mask; it is suitable as a parameter to
the select() 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, yet it may
change after calls to svc_getreq() or
any creation routines. Do not pass its
address to select()! Similar to
svc_fdset, but limited to 32
descriptors.

This interface is made obsolete by
svc_fdset. See rpc_svc_calls(3NSL).

svc_getcaller()
This routine returns the network
address, represented as a struct
sockaddr_in, of the caller of a
procedure associated with the RPC
service transport handle, xprt.

This routine exists for backward
compatibility only, and is obsolete.
The preferred interface is
svc_getrpccaller(). See
rpc_svc_reg(3NSL), which returns the
address as a struct netbuf.

svc_getreq()
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() call has
determined that an RPC request has
arrived on some RPC file descriptors;
rdfds is the resultant read file
descriptor bit mask. The routine
returns when all file descriptors
associated with the value of rdfds have
been serviced. This routine is similar
to svc_getreqset() but is limited to 32
descriptors.

This interface is made obsolete by
svc_getreqset().

svcfd_create()
Create a service on top of any open and
bound descriptor. Typically, this
descriptor is a connected file
descriptor for a stream protocol. Refer
to the File Descriptor section for more
information. sendsz and recvsz indicate
sizes for the send and receive buffers.
If they are 0, a reasonable default is
chosen.

This interface is made obsolete by
svc_fd_create() (see
rpc_svc_create(3NSL)).

svcraw_create()
This routine creates an internal,
memory-based 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.

This routine exists for backward
compatibility only, and has the same
functionality of svc_raw_create(). See
rpc_svc_create(3NSL), which obsoletes
it.

svctcp_create()
This routine creates a TCP/IP-based RPC
service transport, to which it returns
a pointer. The transport is associated
with the file descriptor fd, which may
be RPC_ANYSOCK, in which case a new
file descriptor is created. If the file
descriptor is not bound to a local TCP
port, then this routine binds it to an
arbitrary port. Refer to the File
Descriptor section for more
information. Upon completion,
xprt->xp_fd is the transport's file
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 0 choose suitable defaults.

This routine exists for backward
compatibility only. svc_create(),
svc_tli_create(), or svc_vc_create()
should be used instead. See
rpc_svc_create(3NSL).

svcudp_bufcreate()
This routine creates a UDP/IP-based RPC
service transport, to which it returns
a pointer. The transport is associated
with the file descriptor fd. If fd is
RPC_ANYSOCK then a new file descriptor
is created. If the file descriptor is
not bound to a local UDP port, then
this routine binds it to an arbitrary
port. Upon completion, xprt->xp_fd is
the transport's file descriptor, and
xprt->xp_port is the transport's port
number. Refer to the File Descriptor
section for more information. This
routine returns NULL if it fails.

The user specifies the maximum packet
size for sending and receiving
UDP-based RPC messages by using the
sendsz and recvsz parameters.

This routine exists for backward
compatibility only. svc_tli_create(),
or svc_dg_create() should be used
instead. See rpc_svc_create(3NSL).

svcudp_create()
This routine creates a UDP/IP-based RPC
service transport, to which it returns
a pointer. The transport is associated
with the file descriptor fd, which may
be RPC_ANYSOCK, in which case a new
file descriptor is created. If the file
descriptor is not bound to a local UDP
port, then this routine binds it to an
arbitrary port. Upon completion,
xprt->xp_fd is the transport's file
descriptor, and xprt->xp_port is the
transport's port number. This routine
returns NULL if it fails.

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.

This routine exists for backward
compatibility only. svc_create(),
svc_tli_create(), or svc_dg_create()
should be used instead. See
rpc_svc_create(3NSL).

registerrpc()
Register program prognum, procedure
procnum, and version versnum with the
RPC service package. If a request
arrives for program prognum, version
versnum, and procedure procnum,
procname is called with a pointer to
its parameter(s). procname should
return a pointer to its static
result(s). inproc is used to decode the
parameters while outproc is used to
encode the results. This routine
returns 0 if the registration
succeeded, -1 otherwise.

svc_run() must be called after all the
services are registered.

This routine exists for backward
compatibility only, and it is made
obsolete by rpc_reg().

svc_register()
Associates prognum and versnum with the
service dispatch procedure, dispatch.
If protocol is 0, the service is not
registered with the portmap service. If
protocol is non-zero, then a mapping of
the triple [prognum, versnum, protocol]
to xprt->xp_port is established with
the local portmap service (generally
protocol is 0, IPPROTO_UDP or
IPPROTO_TCP). The procedure dispatch
has the following form:

dispatch(struct svc_req *request, SVCXPRT *xprt);

The svc_register() routine returns one
if it succeeds, and 0 otherwise.

This routine exists for backward
compatibility only. Enhanced
functionality is provided by svc_reg().

svc_unregister()
Remove all mapping of the double
[prognum, versnum] to dispatch
routines, and of the triple [prognum,
versnum, all-protocols] to port number
from portmap.

This routine exists for backward
compatibility. Enhanced functionality
is provided by svc_unreg().

xdr_authunix_parms()
Used for describing UNIX credentials.
This routine is useful for users who
wish to generate these credentials
without using the RPC authentication
package.

This routine exists for backward
compatibility only, and is made
obsolete by xdr_authsys_parms(). See
rpc_xdr(3NSL).

ATTRIBUTES

NOTES

These interfaces are unsafe in multithreaded applications. Unsafe
interfaces should be called only from the main thread.

May 22, 2022 RPC_SOC(3NSL)