Networking Services Library Functions rpc(3NSL)
NAME
rpc - library routines for remote procedure calls
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
#include
#include
DESCRIPTION
These routines allow C language programs to make procedure
calls on other machines across a network. First, the client
sends a request to the server. On receipt of the request,
the server calls a dispatch routine to perform the requested
service, and then sends back a reply.
All RPC routines require the header . Routines
that take a netconfig structure also require that
be included. Applications using RPC and XDR
routines should be linked with the libnsl library.
Multithread Considerations
In the case of multithreaded applications, the -mt option
must be specified on the command line at compilation time to
enable a thread-specific version of rpccreateerr(). See
rpcclntcreate(3NSL) and threads(5).
When used in multithreaded applications, client-side rou-
tines are MT-Safe. CLIENT handles can be shared between
threads; however, in this implementation, requests by dif-
ferent threads are serialized (that is, the first request
will receive its results before the second request is sent).
See rpcclntcreate(3NSL).
When used in multithreaded applications, server-side rou-
tines are usually Unsafe. In this implementation the service
transport handle, SVCXPRT contains a single data area for
decoding arguments and encoding results. See
rpcsvccreate(3NSL). Therefore, this structure cannot be
freely shared between threads that call functions that do
this. Routines that are affected by this restriction are
marked as unsafe for MT applications. See
rpcsvccalls(3NSL).
Nettyp
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
SunOS 5.11 Last change: 5 Jun 2001 1
Networking Services Library Functions rpc(3NSL)
application.
nettype can be one of the following:
netpath Choose from the transports which have been
indicated by their token names in the NETPATH
environment variable. If NETPATH is unset or
NUL, 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 same as visible except that it chooses
only the connection oriented transports
(semantics tpicots or tpicotsord) from the
entries in the /etc/netconfig file.
datagramv This is same as visible except that it chooses
only the connectionless datagram transports
(semantics tpiclts) from the entries in the
/etc/netconfig file.
circuitn This is same as netpath except that it chooses
only the connection oriented datagram tran-
sports (semantics tpicots or tpicotsord).
datagramn This is same as netpath except that it chooses
only the connectionless datagram transports
(semantics tpiclts).
udp This refers to Internet UDP.
tcp This refers to Internet TCP.
If nettype is NUL, it defaults to netpath. The transports
are tried in left to right order in the NETPATH variable or
in top to down order in the /etc/netconfig file.
Derived Types
In a 64-bit environment, the derived types are defined as
follows:
SunOS 5.11 Last change: 5 Jun 2001 2
Networking Services Library Functions rpc(3NSL)
typedef uint32t rpcprogt;
typedef uint32t rpcverst;
typedef uint32t rpcproct;
typedef uint32t rpcprott;
typedef uint32t rpcportt;
typedef int32t rpcinlinet;
In a 32-bit environment, the derived types are defined as
follows:
typedef unsigned long rpcprogt;
typedef unsigned long rpcverst;
typedef unsigned long rpcproct;
typedef unsigned long rpcprott;
typedef unsigned long rpcportt;
typedef long rpcinlinet;
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 */
uintt 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 {
SunOS 5.11 Last change: 5 Jun 2001 3
Networking Services Library Functions rpc(3NSL)
void(*ahnextverf)();
int(*ahmarshal)(); /* nextverf & serialize */
int(*ahvalidate)(); /* validate verifier */
int(*ahrefresh)(); /* refresh credentials */
void(*ahdestroy)(); /* destroy this structure */
} *ahops;
caddrt ahprivate;
} AUTH;
The CLIENT Structure
/*
* Client rpc handle.
* Created by individual implementations.
* Client is responsible for initializing auth.
*/
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 */
int (*clsettimers)(); /* set rpc level timers */
} *clops;
caddrt clprivate; /* private stuff */
char *clnetid; /* network identifier */
char *cltp; /* device name */
} CLIENT;
The SVCXPRT Structure
enum xprtstat {
XPRTDIED,
XPRTMOREREQS,
XPRTIDLE
};
/*
* Server side transport handle
*/
typedef struct {
int xpfd; /* file descriptor for the
ushortt xpport; /* obsolete */
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 */
SunOS 5.11 Last change: 5 Jun 2001 4
Networking Services Library Functions rpc(3NSL)
void (*xpdestroy)(); /* destroy this struct */
} *xpops;
int xpaddrlen; /* length of remote addr.
Obsolete */
char *xptp; /* transport provider device
name */
char *xpnetid; /* network identifier */
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 */
int xptype /* transport type */
} SVCXPRT;
The svcreg Structure
struct svcreq {
rpcprogt rqprog; /* service program number */
rpcverst rqvers; /* service protocol version */
rpcproct rqproc; /* the desired procedure */
struct opaqueauth rqcred; /* raw creds from the wire */
caddrt rqclntcred; /* read only cooked cred */
SVCXPRT *rqxprt; /* associated transport */
};
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.
* XDRFRE can be used to release the space allocated by an XDRDECODE
* request.
*/
enum xdrop {
XDRENCODE=0,
XDRDECODE=1,
XDRFRE=2
};
/*
* This is the number of bytes per unit of external data.
*/
#define BYTESPERXDRUNIT (4)
#define RNDUP(x) ((((x) ] BYTESPERXDRUNIT - 1) /
BYTESPERXDRUNIT) \ * BYTESPERXDRUNIT)
SunOS 5.11 Last change: 5 Jun 2001 5
Networking Services Library Functions rpc(3NSL)
/*
* 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 points to 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
*/
typedef struct {
enum xdrop xop; /* operation; fast additional param */
struct xdrops {
boolt (*xgetlong)(); /* get long from underlying stream */
boolt (*xputlong)(); /* put long to underlying stream */
boolt (*xgetbytes)(); /* get bytes from underlying stream */
boolt (*xputbytes)(); /* put bytes to underlying stream */
uintt (*xgetpostn)(); /* returns bytes off from beginning */
boolt (*xsetpostn)(); /* reposition the stream */
rpcinlinet *(*xinline)(); /* buf quick ptr to buffered data */
void (*xdestroy)(); /* free privates of this xdrstream */
boolt (*xcontrol)(); /* changed/retrieve client object info*/
boolt (*xgetint32)(); /* get int from underlying stream */
boolt (*xputint32)(); /* put int to underlying stream */
} *xops;
caddrt xpublic; /* users' data */
caddrt xpriv /* pointer to private data */
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 Manual Reference Page
authdestroy rpcclntauth(3NSL)
SunOS 5.11 Last change: 5 Jun 2001 6
Networking Services Library Functions rpc(3NSL)
authdescreate rpcsoc(3NSL)
authdesgetucred securerpc(3NSL)
authdesseccreate securerpc(3NSL)
authnonecreate rpcclntauth(3NSL)
authsyscreate rpcclntauth(3NSL)
authsyscreatedefault rpcclntauth(3NSL)
authunixcreate rpcsoc(3NSL)
authunixcreatedefault rpcsoc(3NSL)
callrpc rpcsoc(3NSL)
clntbroadcast rpcsoc(3NSL)
clntcall rpcclntcalls(3NSL)
clntcontrol rpcclntcreate(3NSL)
clntcreate rpcclntcreate(3NSL)
clntdestroy rpcclntcreate(3NSL)
clntdgcreate rpcclntcreate(3NSL)
clntfreeres rpcclntcalls(3NSL)
clntgeterr rpcclntcalls(3NSL)
SunOS 5.11 Last change: 5 Jun 2001 7
Networking Services Library Functions rpc(3NSL)
clntpcreateerror rpcclntcreate(3NSL)
clntperrno rpcclntcalls(3NSL)
clntperror rpcclntcalls(3NSL)
clntrawcreate rpcclntcreate(3NSL)
clntspcreateerror rpcclntcreate(3NSL)
clntsperrno rpcclntcalls(3NSL)
clntsperror rpcclntcalls(3NSL)
clnttlicreate rpcclntcreate(3NSL)
clnttpcreate rpcclntcreate(3NSL)
clntudpcreate rpcsoc(3NSL)
clntvccreate rpcclntcreate(3NSL)
clntrawcreate rpcsoc(3NSL)
clnttcpcreate rpcsoc(3NSL)
clntudpbufcreate rpcsoc(3NSL)
getmyaddress rpcsoc(3NSL)
getnetname securerpc(3NSL)
host2netname securerpc(3NSL)
SunOS 5.11 Last change: 5 Jun 2001 8
Networking Services Library Functions rpc(3NSL)
keydecryptsession securerpc(3NSL)
keyencryptsession securerpc(3NSL)
keygendes securerpc(3NSL)
keysetsecret securerpc(3NSL)
netname2host securerpc(3NSL)
netname2user securerpc(3NSL)
pmapgetmaps rpcsoc(3NSL)
pmapgetport rpcsoc(3NSL)
pmaprmtcall rpcsoc(3NSL)
pmapset rpcsoc(3NSL)
pmapunset rpcsoc(3NSL)
registerrpc rpcsoc(3NSL)
rpcbroadcast rpcclntcalls(3NSL)
rpcbroadcastexp rpcclntcalls(3NSL)
rpccall rpcclntcalls(3NSL)
rpcreg rpcsvccalls(3NSL)
svccreate rpcsvccreate(3NSL)
SunOS 5.11 Last change: 5 Jun 2001 9
Networking Services Library Functions rpc(3NSL)
svcdestroy rpcsvccreate(3NSL)
svcdgcreate rpcsvccreate(3NSL)
svcdgenablecache rpcsvccalls(3NSL)
svcfdcreate rpcsvccreate(3NSL)
svcfds rpcsoc(3NSL)
svcfreeargs rpcsvcreg(3NSL)
svcgetargs rpcsvcreg(3NSL)
svcgetcaller rpcsoc(3NSL)
svcgetreq rpcsoc(3NSL)
svcgetreqset rpcsvccalls(3NSL)
svcgetrpccaller rpcsvccalls(3NSL)
svcrawcreate rpcsvccreate(3NSL)
svcreg rpcsvccalls(3NSL)
svcregister rpcsoc(3NSL)
svcrun rpcsvcreg(3NSL)
svcsendreply rpcsvcreg(3NSL)
svctlicreate rpcsvccreate(3NSL)
SunOS 5.11 Last change: 5 Jun 2001 10
Networking Services Library Functions rpc(3NSL)
svctpcreate rpcsvccreate(3NSL)
svcunreg rpcsvccalls(3NSL)
svcunregister rpcsoc(3NSL)
svcvccreate rpcsvccreate(3NSL)
svcerrauth rpcsvcerr(3NSL)
svcerrdecode rpcsvcerr(3NSL)
svcerrnoproc rpcsvcerr(3NSL)
svcerrnoprog rpcsvcerr(3NSL)
svcerrprogvers rpcsvcerr(3NSL)
svcerrsystemerr rpcsvcerr(3NSL)
svcerrweakauth rpcsvcerr(3NSL)
svcfdcreate rpcsoc(3NSL)
svcrawcreate rpcsoc(3NSL)
svctcpcreate rpcsoc(3NSL)
svcudpbufcreate rpcsoc(3NSL)
svcudpcreate rpcsoc(3NSL)
user2netname securerpc(3NSL)
SunOS 5.11 Last change: 5 Jun 2001 11
Networking Services Library Functions rpc(3NSL)
xdracceptedreply rpcxdr(3NSL)
xdrauthsysparms rpcxdr(3NSL)
xdrauthunixparms rpcsoc(3NSL)
xdrcallhdr rpcxdr(3NSL)
xdrcallmsg rpcxdr(3NSL)
xdropaqueauth rpcxdr(3NSL)
xdrrejectedreply rpcxdr(3NSL)
xdrreplymsg rpcxdr(3NSL)
xprtregister rpcsvccalls(3NSL)
xprtunregister rpcsvccalls(3NSL)
FILES
/etc/netconfig
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe with exceptions
SEE ALSO
getnetconfig(3NSL), getnetpath(3NSL), rpcclntauth(3NSL),
rpcclntcalls(3NSL), rpcclntcreate(3NSL),
rpcsvccalls(3NSL), rpcsvccreate(3NSL),
rpcsvcerr(3NSL), rpcsvcreg(3NSL), rpcxdr(3NSL),
rpcbind(3NSL), securerpc(3NSL), threads(5), xdr(3NSL),
SunOS 5.11 Last change: 5 Jun 2001 12
Networking Services Library Functions rpc(3NSL)
netconfig(4), rpc(4), attributes(5), environ(5)
SunOS 5.11 Last change: 5 Jun 2001 13
|
