rpc(3N) rpc(3N)
NAME
rpc - library routines for remote procedure calls
DESCRIPTION
RPC routines allow C language programs to make procedure calls
on other machines across a network. First, the client calls a
procedure to send a data packet to the server. On receipt of
the packet, the server calls a dispatch routine to perform the
requested service, and then sends back a reply.
The following sections describe data objects use by the RPC
package.
Nettype
Some of the high-level RPC interface routines take a nettype
string as one of the parameters [for example, clnt_create,
svc_create, rpc_reg, rpc_call]. This string defines a class
of transports which can be used for a particular application.
The transports are tried in left to right order in the NETPATH
variable or in top to down order in the /etc/netconfig file.
nettype can be one of the following:
netpath Choose from the transports which have been indicated
by their token names in the NETPATH variable. If
NETPATH is unset or NULL, it defaults to visible.
netpath is the default nettype.
visible Choose the transports which have the visible flag
(v) set in the /etc/netconfig file.
circuit_v This is same as visible except that it chooses only
the connection oriented transports from the entries
in /etc/netconfig file.
datagram_v
This is same as visible except that it chooses only
the connectionless datagram transports from the
entries in /etc/netconfig file.
circuit_n This is same as netpath except that it chooses only
the connection oriented datagram transports
datagram_n
This is same as netpath except that it chooses only
the connectionless datagram transports.
Copyright 1994 Novell, Inc. Page 1
rpc(3N) rpc(3N)
udp It refers to Internet UDP (for backwards
compatibility).
tcp It refers to Internet TCP (for backwards
compatibility).
raw This is for memory based RPC, mainly for performance
evaluation.
If nettype is NULL, it defaults to netpath.
Data Structures
Some of the data structures used by the RPC package are shown
below.
The AUTH Structure
union des_block {
struct {
u_int32 high;
u_int32 low;
} key;
char c[8];
};
typedef union des_block des_block;
extern bool_t xdr_des_block();
/*
* Authentication info. Opaque to client.
*/
struct opaque_auth {
enum_t oa_flavor; /* flavor of auth */
caddr_t oa_base; /* address of more auth stuff */
u_int oa_length; /* not to exceed MAX_AUTH_BYTES */
};
/*
* Auth handle, interface to client side authenticators.
*/
typedef struct {
struct opaque_auth ah_cred;
struct opaque_auth ah_verf;
union des_block ah_key;
struct auth_ops {
void (*ah_nextverf)();
int (*ah_marshal)(); /* nextverf & serialize */
int (*ah_validate)(); /* validate varifier */
Copyright 1994 Novell, Inc. Page 2
rpc(3N) rpc(3N)
int (*ah_refresh)(); /* refresh credentials */
void (*ah_destroy)(); /* destroy this structure */
} *ah_ops;
caddr_t ah_private;
} AUTH;
The CLIENT Structure
/*
* Client rpc handle.
* Created by individual implementations
* Client is responsible for initializing auth, see e.g. auth_none.c.
*/
typedef struct {
AUTH *cl_auth; /* authenticator */
struct clnt_ops {
enum clnt_stat (*cl_call)(); /* call remote procedure */
void (*cl_abort)(); /* abort a call */
void (*cl_geterr)(); /* get specific error code */
bool_t (*cl_freeres)(); /* frees results */
void (*cl_destroy)(); /* destroy this structure */
bool_t (*cl_control)(); /* the ioctl() of rpc */
} *cl_ops;
caddr_t cl_private; /* private stuff */
char *cl_netid; /* network token */
char *cl_tp; /* device name */
} CLIENT;
The SVCXPRT Structure
enum xprt_stat {
XPRT_DIED,
XPRT_MOREREQS,
XPRT_IDLE
};
/*
* Server side transport handle
*/
typedef struct {
int xp_fd;
#define xp_sock xp_fd
#endif
ushort_t xp_port; /* associated port number.
* Obsolete, but still used to
* specify whether rendezvouser
* or normal connection
*/
Copyright 1994 Novell, Inc. Page 3
rpc(3N) rpc(3N)
struct xp_ops {
bool_t (*xp_recv)(); /* receive incoming requests */
enum xprt_stat (*xp_stat)(); /* get transport status */
bool_t (*xp_getargs)(); /* get arguments */
bool_t (*xp_reply)(); /* send reply */
bool_t (*xp_freeargs)(); /* free mem allocated for args */
void (*xp_destroy)(); /* destroy this struct */
} *xp_ops;
int xp_addrlen; /* length of remote addr. Obsolete */
char *xp_tp; /* transport provider device name */
char *xp_netid; /* network token */
struct netbuf xp_ltaddr; /* local transport address */
struct netbuf xp_rtaddr; /* remote transport address */
char xp_raddr[16]; /* remote address. Obsolete */
struct opaque_auth xp_verf; /* raw response verifier */
caddr_t xp_p1; /* private: for use by svc ops */
caddr_t xp_p2; /* private: for use by svc ops */
caddr_t xp_p3; /* private: for use by svc lib */
} SVCXPRT;
The XDR Structure
/*
* Xdr operations. XDR_ENCODE causes the type to be encoded into the
* stream. XDR_DECODE causes the type to be extracted from the stream.
* XDR_FREE can be used to release the space allocated by an XDR_DECODE
* request.
*/
enum xdr_op {
XDR_ENCODE=0,
XDR_DECODE=1,
XDR_FREE=2
};
/*
* This is the number of bytes per unit of external data.
*/
#define BYTES_PER_XDR_UNIT (4)
#define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) / BYTES_PER_XDR_UNIT) \
* BYTES_PER_XDR_UNIT)
/*
* A xdrproc_t exists for each data type which is to be encoded or decoded.
*
* The second argument to the xdrproc_t is a pointer to an opaque pointer.
* The opaque pointer generally points to a structure of the data type
* to be decoded. If this pointer is 0, then the type routines should
Copyright 1994 Novell, Inc. Page 4
rpc(3N) rpc(3N)
* allocate dynamic storage of the appropriate size and return it.
* bool_t (*xdrproc_t)(XDR *, caddr_t *);
*/
typedef bool_t (*xdrproc_t)();
/*
* The XDR handle.
* Contains operation which is being applied to the stream,
* an operations vector for the particular implementation (for example,
* see xdr_mem.c), and two private fields for the use of the
* particular implementation.
*/
typedef struct {
enum xdr_op x_op; /* operation; fast additional param */
struct xdr_ops {
bool_t (*x_getlong)(); /* get a long from underlying stream */
bool_t (*x_putlong)(); /* put a long to " */
bool_t (*x_getbytes)(); /* get some bytes from " */
bool_t (*x_putbytes)(); /* put some bytes to " */
u_int (*x_getpostn)(); /* returns bytes off from beginning */
bool_t (*x_setpostn)(); /* lets you reposition the stream */
long * (*x_inline)(); /* buf quick ptr to buffered data */
void (*x_destroy)(); /* free privates of this xdr_stream */
} *x_ops;
caddr_t x_public; /* users' data */
caddr_t x_private; /* pointer to private data */
caddr_t x_base; /* private used for position info */
int x_handy; /* extra private word */
} XDR;
Index to Routines
The following table lists RPC routines and the manual
reference pages on which they are described:
RPC Routine Manual Reference Page
________________________________________________
auth_destroy rpc_clnt_auth(3N)
authdes_getucred secure_rpc(3N)
authdes_seccreate secure_rpc(3N)
authnone_create rpc_clnt_auth(3N)
authsys_create rpc_clnt_auth(3N)
authsys_create_default rpc_clnt_auth(3N)
clnt_call rpc_clnt_calls(3N)
clnt_control rpc_clnt_create(3N)
clnt_create rpc_clnt_create(3N)
Copyright 1994 Novell, Inc. Page 5
rpc(3N) rpc(3N)
RPC Routine Manual Reference Page
________________________________________________
clnt_destroy rpc_clnt_create(3N)
clnt_dg_create rpc_clnt_create(3N)
clnt_freeres rpc_clnt_calls(3N)
clnt_geterr rpc_clnt_calls(3N)
clnt_pcreateerror rpc_clnt_create(3N)
clnt_perrno rpc_clnt_calls(3N)
clnt_perror rpc_clnt_calls(3N)
clnt_raw_create rpc_clnt_create(3N)
clnt_spcreateerror rpc_clnt_create(3N)
clnt_sperrno rpc_clnt_calls(3N)
clnt_sperror rpc_clnt_calls(3N)
clnt_tli_create rpc_clnt_create(3N)
clnt_tp_create rpc_clnt_create(3N)
clnt_vc_create rpc_clnt_create(3N)
getnetname secure_rpc(3N)
host2netname secure_rpc(3N)
key_decryptsession secure_rpc(3N)
key_encryptsession secure_rpc(3N)
key_gendes secure_rpc(3N)
key_setsecret secure_rpc(3N)
netname2host secure_rpc(3N)
netname2user secure_rpc(3N)
rpc_broadcast rpc_clnt_calls(3N)
rpc_call rpc_clnt_calls(3N)
rpc_reg rpc_svc_calls(3N)
svc_auth_reg rpc_svc_reg(3N)
svc_create rpc_svc_create(3N)
svc_destroy rpc_svc_create(3N)
svc_dg_create rpc_svc_create(3N)
svc_fd_create rpc_svc_create(3N)
svc_freeargs rpc_svc_reg(3N)
svc_getargs rpc_svc_reg(3N)
svc_getreqset rpc_svc_reg(3N)
svc_getreq_common rpc_svc_reg(3N)
svc_getreq_poll rpc_svc_reg(3N)
svc_getreq_poll_parallel rpc_svc_reg(3N)
svc_getrpccaller rpc_svc_reg(3N)
svc_raw_create rpc_svc_create(3N)
svc_reg rpc_svc_calls(3N)
svc_run rpc_svc_reg(3N)
svc_run_parallel rpc_svc_reg(3N)
svc_sendreply rpc_svc_reg(3N)
Copyright 1994 Novell, Inc. Page 6
rpc(3N) rpc(3N)
RPC Routine Manual Reference Page
________________________________________________
svc_tli_create rpc_svc_create(3N)
svc_tp_create rpc_svc_create(3N)
svc_unreg rpc_svc_calls(3N)
svc_vc_create rpc_svc_create(3N)
svcerr_auth rpc_svc_err(3N)
svcerr_decode rpc_svc_err(3N)
svcerr_noproc rpc_svc_err(3N)
svcerr_noprog rpc_svc_err(3N)
svcerr_progvers rpc_svc_err(3N)
svcerr_systemerr rpc_svc_err(3N)
svcerr_weakauth rpc_svc_err(3N)
user2netname secure_rpc(3N)
xdr_accepted_reply rpc_xdr(3N)
xdr_authsys_parms rpc_xdr(3N)
xdr_callhdr rpc_xdr(3N)
xdr_callmsg rpc_xdr(3N)
xdr_opaque_auth rpc_xdr(3N)
xdr_rejected_reply rpc_xdr(3N)
xdr_replymsg rpc_xdr(3N)
xprt_register rpc_svc_calls(3N)
xprt_unregister rpc_svc_calls(3N)
Files
/etc/netconfig
/usr/lib/locale/locale/LC_MESSAGES/uxnsl
REFERENCES
environ(5), getnetconfig(3N), getnetpath(3N),
rpc_clnt_auth(3N), rpc_clnt_calls(3N), rpc_clnt_create(3N),
rpc_svc_calls(3N), rpc_svc_create(3N), rpc_svc_err(3N),
rpc_svc_reg(3N), rpc_xdr(3N), rpcbind(3N), secure_rpc(3N),
xdr(3N), netconfig(4)
Copyright 1994 Novell, Inc. Page 7