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 rpc_createerr(). See rpc_clnt_create(3NSL) and threads(7).

When used in multithreaded applications, client-side routines are MT-Safe. CLIENT handles can be shared between threads; however, in this implementation, requests by different threads are serialized (that is, the first request will receive its results before the second request is sent). See rpc_clnt_create(3NSL).

When used in multithreaded applications, server-side routines are usually Unsafe. In this implementation the service transport handle, SVCXPRT contains a single data area for decoding arguments and encoding results. See rpc_svc_create(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 rpc_svc_calls(3NSL).

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.

nettype can be one of the following:

netpath

visible

circuit_v

datagram_v

circuit_n

datagram_n

udp

tcp

If nettype is NULL, 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:

In a 32-bit environment, the derived types are defined as follows:

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 */


        uint_t 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 verifier */


                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.


 */


        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 */


              int (*cl_settimers)();         /* set rpc level timers */


             } *cl_ops;


             caddr_t    cl_private;                  /* private stuff */


             char       *cl_netid;                   /* network identifier */


             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;                  /* file descriptor for the


        ushort_t xp_port;               /* obsolete */


        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 identifier */


        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 */


        int xp_type                     /* transport type */
}  SVCXPRT;

The svc_reg Structure

struct  svc_req  {


   rpcprog_t rq_prog;          /* service program number */


   rpcvers_t rq_vers;          /* service protocol version */


   rpcproc_t rq_proc;          /* the desired procedure */


   struct opaque_auth rq_cred; /* raw creds from the wire */


   caddr_t rq_clntcred;        /* read only cooked cred */


   SVCXPRT *rq_xprt;           /* associated transport */
};

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 points to 0,


 * then the type routines should 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


 */
typedef struct {
enum xdr_op x_op;    /* operation; fast additional param */
struct  xdr_ops  {
bool_t       (*x_getlong)();      /* get long from underlying stream */
bool_t       (*x_putlong)();      /* put long to underlying stream */
bool_t       (*x_getbytes)();     /* get bytes from underlying stream */
bool_t       (*x_putbytes)();     /* put bytes to underlying stream */
uint_t       (*x_getpostn)();     /* returns bytes off from beginning */
bool_t       (*x_setpostn)();     /* reposition the stream */
rpc_inline_t *(*x_inline)();      /* buf quick ptr to buffered data */
void         (*x_destroy)();      /* free privates of this xdr_stream */
bool_t       (*x_control)();      /* changed/retrieve client object info*/
bool_t       (*x_getint32)();     /* get int from underlying stream */
bool_t       (*x_putint32)();     /* put int to underlying stream */
} *x_ops;
caddr_t      x_public;             /* users' data */
caddr_t      x_priv                /* 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

auth_destroy

authdes_create

authdes_getucred

authdes_seccreate

authnone_create

authsys_create

authsys_create_default

authunix_create

authunix_create_default

callrpc

clnt_broadcast

clnt_call

clnt_control

clnt_create

clnt_destroy

clnt_dg_create

clnt_freeres

clnt_geterr

clnt_pcreateerror

clnt_perrno

clnt_perror

clnt_raw_create

clnt_spcreateerror

clnt_sperrno

clnt_sperror

clnt_tli_create

clnt_tp_create

clnt_vc_create

clntraw_create

clnttcp_create

clntudp_bufcreate

clntudp_create

get_myaddress

getnetname

host2netname

key_decryptsession

key_encryptsession

key_gendes

key_setsecret

netname2host

netname2user

pmap_getmaps

pmap_getport

pmap_rmtcall

pmap_set

pmap_unset

registerrpc

rpc_broadcast

rpc_broadcast_exp

rpc_call

rpc_reg

svc_create

svc_destroy

svc_dg_create

svc_dg_enablecache

svc_fd_create

svc_fds

svc_freeargs

svc_getargs

svc_getcaller

svc_getreq

svc_getreqset

svc_getrpccaller

svc_raw_create

svc_reg

svc_register

svc_run

svc_sendreply

svc_tli_create

svc_tp_create

svc_unreg

svc_unregister

svc_vc_create

svcerr_auth

svcerr_decode

svcerr_noproc

svcerr_noprog

svcerr_progvers

svcerr_systemerr

svcerr_weakauth

svcfd_create

svcraw_create

svctcp_create

svcudp_bufcreate

svcudp_create

user2netname

xdr_accepted_reply

xdr_authsys_parms

xdr_authunix_parms

xdr_callhdr

xdr_callmsg

xdr_opaque_auth

xdr_rejected_reply

xdr_replymsg

xprt_register

xprt_unregister