te
Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
Copyright 1989 AT&T
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
rpc - library routines for remote procedure calls

cc [ flag ... ] file ... -lnsl [ library ... ]
#include <rpc/rpc.h>
#include <netconfig.h>

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 <rpc/rpc.h>. Routines that take a netconfig structure also require that <netconfig.h> be included. Applications using RPC and XDR routines should be linked with the libnsl library.

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(5).

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).

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.

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

typedef uint32_t rpcprog_t;

typedef uint32_t rpcvers_t;

typedef uint32_t rpcproc_t;

typedef uint32_t rpcprot_t;

typedef uint32_t rpcport_t;

typedef int32_t rpc_inline_t;

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

typedef unsigned long rpcprog_t;

typedef unsigned long rpcvers_t;

typedef unsigned long rpcproc_t;

typedef unsigned long rpcprot_t;

typedef unsigned long rpcport_t;

typedef long rpc_inline_t;

Some of the data structures used by the RPC package are shown below.

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;

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

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;

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

};

/*
 * 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) \e * 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;

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_udpcreate clnt_vc_create clntraw_create clnttcp_create clntudp_bufcreate 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

/etc/netconfig

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level MT-Safe with exceptions

getnetconfig(3NSL), getnetpath(3NSL), rpc_clnt_auth(3NSL), rpc_clnt_calls(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL), rpc_svc_create(3NSL), rpc_svc_err(3NSL), rpc_svc_reg(3NSL), rpc_xdr(3NSL), rpcbind(3NSL), secure_rpc(3NSL), threads(5), xdr(3NSL), netconfig(4), rpc(4), attributes(5), environ(5)