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 switching 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, clntcreate, svccreate, rpcreg,
rpccall). 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 descending 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.
circuitv This is the same as visible except that it chooses only
the connection oriented transports from the entries in
/etc/netconfig file.
datagramv This is the same as visible except that it chooses only
the connectionless datagram transports from the entries in
/etc/netconfig file.
circuitn This is the same as netpath except that it chooses only
the connection oriented datagram transports.
datagramn This is the same as netpath except that it chooses only
the connectionless datagram transports.
udp Selects Internet UDP.
tcp Selects Internet TCP.
raw Exclusively for performance reports via pseudo-RPC.
If nettype is NULL, it defaults to netpath.
Page 1 Reliant UNIX 5.44 Printed 11/98
rpc(3N) rpc(3N)
DATA STRUCTURES
Some of the data structures used by the RPC package are shown below.
The AUTH Structure
union desblock {
struct {
uint32 high;
uint32 low;
} key;
char c[8];
};
typedef union desblock desblock;
extern boolt xdrdesblock();
/*
* Authentication info. Opaque to client.
*/
struct opaqueauth {
enumt oaflavor; /* flavor of auth */
caddrt oabase; /* address of more auth stuff */
uint oalength; /* not to exceed MAXAUTHBYTES */
};
/*
* Auth handle, interface to client side authenticators.
*/
typedef struct {
struct opaqueauth ahcred;
struct opaqueauth ahverf;
union desblock ahkey;
struct authops {
void (*ahnextverf)();
int (*ahmarshal)(); /* nextverf & serialize */
int (*ahvalidate)(); /* validate verifier */
int (*ahrefresh)(); /* refresh credentials */
void (*ahdestroy)(); /* destroy this structure */
} *ahops;
caddrt ahprivate;
} AUTH;
Page 2 Reliant UNIX 5.44 Printed 11/98
rpc(3N) rpc(3N)
The CLIENT Structure
/*
* Client rpc handle.
* Created by individual implementations.
* Client is responsible for initializing auth, see e.g. authnone.c.
*/
typedef struct {
AUTH *clauth; /* authenticator */
struct clntops {
enum clntstat (*clcall)(); /* call remote procedure */
void (*clabort)(); /* abort a call */
void (*clgeterr)(); /* get specific error code */
boolt (*clfreeres)(); /* frees results */
void (*cldestroy)(); /* destroy this structure */
boolt (*clcontrol)(); /* the ioctl() of rpc */
} *clops;
caddrt clprivate; /* private stuff */
char *clnetid; /* network token */
char *cltp; /* device name */
} CLIENT;
Page 3 Reliant UNIX 5.44 Printed 11/98
rpc(3N) rpc(3N)
The SVCXPRT Structure
enum xprtstat {
XPRTDIED,
XPRTMOREREQS,
XPRTIDLE
};
/*
* Server side transport handle
*/
typedef struct {
int xpfd;
#define xpsock xpfd
#endif
ushort xpport; /* associated port number.
* Obsolete, but still used to
* specify whether rendezvouser
* or normal connection.
*/
struct xpops {
boolt (*xprecv)(); /* receive incoming requests */
enum xprtstat (*xpstat)(); /* get transport status */
boolt (*xpgetargs)(); /* get arguments */
boolt (*xpreply)(); /* send reply */
boolt (*xpfreeargs)(); /* free mem allocated for args */
void (*xpdestroy)(); /* destroy this struct */
} *xpops;
int xpaddrlen; /* length of remote addr. Obsolete */
char *xptp; /* transport provider device name */
char *xpnetid; /* network token */
struct netbuf xpltaddr; /* local transport address */
struct netbuf xprtaddr; /* remote transport address */
char xpraddr[16]; /* remote address. Obsolete */
struct opaqueauth xpverf; /* raw response verifier */
caddrt xpp1; /* private: for use by svc ops */
caddrt xpp2; /* private: for use by svc ops */
caddrt xpp3; /* private: for use by svc lib */
} SVCXPRT;
Page 4 Reliant UNIX 5.44 Printed 11/98
rpc(3N) rpc(3N)
The XDR Structure
/*
* Xdr operations. XDRENCODE causes the type to be encoded into the
* stream. XDRDECODE causes the type to be extracted from the stream.
* XDRFREE can be used to release the space allocated by an XDRDECODE
* request.
*/
enum xdrop {
XDRENCODE=0,
XDRDECODE=1,
XDRFREE=2
};
/*
* This is the number of bytes per unit of external data.
*/
#define BYTESPERXDRUNIT (4)
#define RNDUP(x) ((((x) + BYTESPERXDRUNIT - 1) / BYTESPERXDRUNIT) \
* BYTESPERXDRUNIT)
/*
* A xdrproct exists for each data type which is to be encoded or decoded.
*
* The second argument to the xdrproct 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
* allocate dynamic storage of the appropriate size and return it.
* boolt (*xdrproct)(XDR *, caddrt *);
*/
typedef boolt (*xdrproct)();
/*
* The XDR handle.
* Contains operation which is being applied to the stream, an operations
* vector for the particular implementation (e.g. see xdrmem.c), and
* two private fields for the use of the particular implementation.
*/
typedef struct {
enum xdrop xop; /* operation; fast additional param */
struct xdrops {
boolt (*xgetlong)(); /* get a long from underlying stream */
boolt (*xputlong)(); /* put a long to " */
boolt (*xgetbytes)(); /* get some bytes from " */
boolt (*xputbytes)(); /* put some bytes to " */
uint (*xgetpostn)(); /* returns bytes off from beginning */
boolt (*xsetpostn)(); /* lets you reposition the stream */
long * (*xinline)(); /* buf quick ptr to buffered data */
void (*xdestroy)(); /* free privates of this xdrstream */
} *xops;
caddrt xpublic; /* users' data */
caddrt xprivate; /* pointer to private data */
Page 5 Reliant UNIX 5.44 Printed 11/98
rpc(3N) rpc(3N)
caddrt xbase; /* private used for position info */
int xhandy; /* 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 Name Manual Page Name
_____________________________________________
authdestroy rpc_clnt_auth(3N)
authnonecreate rpc_clnt_auth(3N)
authsyscreate rpc_clnt_auth(3N)
authsyscreatedefault rpc_clnt_auth(3N)
clntcall rpc_clnt_calls(3N)
clntcontrol rpc_clnt_create(3N)
clntcreate rpc_clnt_create(3N)
clntdestroy rpc_clnt_create(3N)
clntdgcreate rpc_clnt_create(3N)
clntfreeres rpc_clnt_calls(3N)
clntgeterr rpc_clnt_calls(3N)
clntpcreateerror rpc_clnt_create(3N)
clntperrno rpc_clnt_calls(3N)
clntperror rpc_clnt_calls(3N)
clntrawcreate rpc_clnt_create(3N)
clntspcreateerror rpc_clnt_create(3N)
clntsperrno rpc_clnt_calls(3N)
clntsperror rpc_clnt_calls(3N)
clnttlicreate rpc_clnt_create(3N)
clnttpcreate rpc_clnt_create(3N)
clntvccreate rpc_clnt_create(3N)
rpcbroadcast rpc_clnt_calls(3N)
rpccall rpc_clnt_calls(3N)
rpcreg rpc_svc_calls(3N)
svccreate rpc_svc_create(3N)
svcdestroy rpc_svc_create(3N)
svcdgcreate rpc_svc_create(3N)
svcfdcreate rpc_svc_create(3N)
svcfreeargs rpc_svc_reg(3N)
svcgetargs rpc_svc_reg(3N)
svcgetreqset rpc_svc_reg(3N)
svcgetrpccaller rpc_svc_reg(3N)
svcrawcreate rpc_svc_create(3N)
svcreg rpc_svc_calls(3N)
svcrun rpc_svc_reg(3N)
svcsendreply rpc_svc_reg(3N)
Page 6 Reliant UNIX 5.44 Printed 11/98
rpc(3N) rpc(3N)
svctlicreate rpc_svc_create(3N)
svctpcreate rpc_svc_create(3N)
svcunreg rpc_svc_calls(3N)
svcvccreate rpc_svc_create(3N)
svcerrauth rpc_svc_err(3N)
svcerrdecode rpc_svc_err(3N)
svcerrnoproc rpc_svc_err(3N)
svcerrnoprog rpc_svc_err(3N)
svcerrprogvers rpc_svc_err(3N)
svcerrsystemerr rpc_svc_err(3N)
svcerrweakauth rpc_svc_err(3N)
xdracceptedreply rpc_xdr(3N)
xdrauthsysparms rpc_xdr(3N)
xdrcallhdr rpc_xdr(3N)
xdrcallmsg rpc_xdr(3N)
xdropaqueauth rpc_xdr(3N)
xdrrejectedreply rpc_xdr(3N)
xdrreplymsg rpc_xdr(3N)
xprtregister rpc_svc_calls(3N)
xprtunregister rpc_svc_calls(3N)
NOTES
If you use one of the RPC functions, you must link the libnsl library
at compilation (cc -lnsl).
FILES
/etc/netconfig
SEE ALSO
getnetconfig(3N), getnetpath(3N), rpcclntauth(3N),
rpcclntcalls(3N), rpcclntcreate(3N), rpcsvccalls(3N),
rpcsvccreate(3N), rpcsvcerr(3N), rpcsvcreg(3N), rpcxdr(3N),
rpcbind(3N), xdr(3N), netconfig(4), environ(5).
Page 7 Reliant UNIX 5.44 Printed 11/98