NetBSD-5.0.2/lib/libc/rpc/rpc.3
.\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" $NetBSD: rpc.3,v 1.20.24.1 2009/04/12 02:25:25 snj Exp $
.Dd May 7, 1993
.Dt RPC 3
.Os
.Sh NAME
.Nm rpc
.Nd library routines for remote procedure calls
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.In netconfig.h
.Sh 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.
.Pp
All
RPC routines require the header
.Aq Pa rpc/rpc.h .
Routines that take a
.Fa netconfig
structure also require that
.Aq Pa netconfig.h
be included.
.Ss Nettype
Some of the high-level
RPC interface routines take a
.Fa nettype
string as one of the parameters
(for example,
.Fn clnt_create ,
.Fn svc_create ,
.Fn rpc_reg ,
.Fn rpc_call .
This string defines a class of transports which can be used
for a particular application.
.Pp
.Fa nettype
can be one of the following:
.Bl -tag -width datagram_v
.It netpath
Choose from the transports which have been
indicated by their token names in the
.Ev NETPATH
environment variable.
If
.Ev NETPATH
is unset or
.Dv NULL
, it defaults to
.Fa visible .
.Fa netpath
is the default
.Fa nettype .
.It visible
Choose the transports which have the visible flag (v)
set in the
.Pa /etc/netconfig
file.
.It circuit_v
This is same as
.Fa visible
except that it chooses only the connection oriented transports
(semantics
.Fa tpi_cots
or
.Fa tpi_cots_ord )
from the entries in the
.Pa /etc/netconfig
file.
.It datagram_v
This is same as
.Fa visible
except that it chooses only the connectionless datagram transports
(semantics
.Fa tpi_clts )
from the entries in the
.Pa /etc/netconfig
file.
.It circuit_n
This is same as
.Fa netpath
except that it chooses only the connection oriented datagram transports
(semantics
.Fa tpi_cots
or
.Fa tpi_cots_ord ) .
.It datagram_n
This is same as
.Fa netpath
except that it chooses only the connectionless datagram transports
(semantics
.Fa tpi_clts ) .
.It udp
This refers to Internet UDP, both version 4 and 6.
.It tcp
This refers to Internet TCP, both version 4 and 6.
.El
.Pp
If
.Fa nettype
is
.Dv NULL ,
it defaults to
.Fa netpath .
The transports are tried in left to right order in the
.Ev NETPATH
variable or in top to down order in the
.Pa /etc/netconfig
file.
.Ss Derived Types
The derived types used in the RPC interfaces are defined as follows:
.Bd -literal
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;
.Ed
.Ss Data Structures
Some of the data structures used by the
RPC package are shown below.
.Ss The AUTH Structure
.Bd -literal
/*
* 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;
struct auth_ops {
void (*ah_nextverf)(\|);
int (*ah_marshal)(\|); /* nextverf \*[Am] serialize */
int (*ah_validate)(\|); /* validate verifier */
int (*ah_refresh)(\|); /* refresh credentials */
void (*ah_destroy)(\|); /* destroy this structure */
} *ah_ops;
caddr_t ah_private;
} AUTH;
.Ed
.Ss The CLIENT Structure
.Bd -literal
/*
* 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 */
} *cl_ops;
caddr_t cl_private; /* private stuff */
char *cl_netid; /* network identifier */
char *cl_tp; /* device name */
} CLIENT;
.Ed
.Ss The SVCXPRT structure
.Bd -literal
enum xprt_stat {
XPRT_DIED,
XPRT_MOREREQS,
XPRT_IDLE
};
/*
* Server side transport handle
*/
typedef struct {
int xp_fd; /* file descriptor for the server handle */
u_short xp_port; /* obsolete */
const 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 */
struct sockaddr_in xp_raddr; /* Obsolete */
const struct xp_ops2 {
bool_t (*xp_control)(); /* catch-all function */
} *xp_ops2;
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 */
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;
.Ed
.Ss The svc_req structure
.Bd -literal
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 */
};
.Ed
.Ss The XDR structure
.Bd -literal
/*
* 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 a long from underlying stream */
bool_t (*x_putlong)(); /* put a long to underlying stream */
bool_t (*x_getbytes)(); /* get bytes from underlying stream */
bool_t (*x_putbytes)(); /* put bytes to underlying stream */
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;
/*
* The netbuf structure. This structure is defined in \*[Lt]xti.h\*[Gt] on SysV
* systems, but NetBSD does not use XTI.
*
* Usually, buf will point to a struct sockaddr, and len and maxlen
* will contain the length and maximum length of that socket address,
* respectively.
*/
struct netbuf {
unsigned int maxlen;
unsigned int len;
void *buf;
};
/*
* The format of the address and options arguments of the XTI t_bind call.
* Only provided for compatibility, it should not be used other than
* as an argument to svc_tli_create().
*/
struct t_bind {
struct netbuf addr;
unsigned int qlen;
};
.Ed
.Ss Index to Routines
The following table lists RPC routines and the manual reference
pages on which they are described:
.Bl -column "authunix_create_default()" "rpc_clnt_create(3)"
.It Em "RPC Routine" Ta Em "Manual Reference Page"
.Pp
.It Fn auth_destroy Ta Xr rpc_clnt_auth 3 ,
.It Fn authdes_create Ta Xr rpc_soc 3 ,
.It Fn authnone_create Ta Xr rpc_clnt_auth 3 ,
.It Fn authsys_create Ta Xr rpc_clnt_auth 3 ,
.It Fn authsys_create_default Ta Xr rpc_clnt_auth 3 ,
.It Fn authunix_create Ta Xr rpc_soc 3 ,
.It Fn authunix_create_default Ta Xr rpc_soc 3 ,
.It Fn callrpc Ta Xr rpc_soc 3 ,
.It Fn clnt_broadcast Ta Xr rpc_soc 3 ,
.It Fn clnt_call Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_control Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_create Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_destroy Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_dg_create Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_freeres Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_geterr Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_pcreateerror Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_perrno Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_perror Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_raw_create Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_spcreateerror Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_sperrno Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_sperror Ta Xr rpc_clnt_calls 3 ,
.It Fn clnt_tli_create Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_tp_create Ta Xr rpc_clnt_create 3 ,
.It Fn clnt_udpcreate Ta Xr rpc_soc 3 ,
.It Fn clnt_vc_create Ta Xr rpc_clnt_create 3 ,
.It Fn clntraw_create Ta Xr rpc_soc 3 ,
.It Fn clnttcp_create Ta Xr rpc_soc 3 ,
.It Fn clntudp_bufcreate Ta Xr rpc_soc 3 ,
.It Fn get_myaddress Ta Xr rpc_soc 3 ,
.It Fn pmap_getmaps Ta Xr rpc_soc 3 ,
.It Fn pmap_getport Ta Xr rpc_soc 3 ,
.It Fn pmap_rmtcall Ta Xr rpc_soc 3 ,
.It Fn pmap_set Ta Xr rpc_soc 3 ,
.It Fn pmap_unset Ta Xr rpc_soc 3 ,
.It Fn registerrpc Ta Xr rpc_soc 3 ,
.It Fn rpc_broadcast Ta Xr rpc_clnt_calls 3 ,
.It Fn rpc_broadcast_exp Ta Xr rpc_clnt_calls 3 ,
.It Fn rpc_call Ta Xr rpc_clnt_calls 3 ,
.It Fn rpc_reg Ta Xr rpc_svc_calls 3 ,
.It Fn svc_create Ta Xr rpc_svc_create 3 ,
.It Fn svc_destroy Ta Xr rpc_svc_create 3 ,
.It Fn svc_dg_create Ta Xr rpc_svc_create 3 ,
.It Fn svc_dg_enablecache Ta Xr rpc_svc_calls 3 ,
.It Fn svc_fd_create Ta Xr rpc_svc_create 3 ,
.It Fn svc_fds Ta Xr rpc_soc 3 ,
.It Fn svc_freeargs Ta Xr rpc_svc_reg 3 ,
.It Fn svc_getargs Ta Xr rpc_svc_reg 3 ,
.It Fn svc_getcaller Ta Xr rpc_soc 3 ,
.It Fn svc_getreq Ta Xr rpc_soc 3 ,
.It Fn svc_getreqset Ta Xr rpc_svc_calls 3 ,
.It Fn svc_getrpccaller Ta Xr rpc_svc_calls 3 ,
.It Fn svc_kerb_reg Ta Xr kerberos_rpc 3 ,
.It Fn svc_raw_create Ta Xr rpc_svc_create 3 ,
.It Fn svc_reg Ta Xr rpc_svc_calls 3 ,
.It Fn svc_register Ta Xr rpc_soc 3 ,
.It Fn svc_run Ta Xr rpc_svc_reg 3 ,
.It Fn svc_sendreply Ta Xr rpc_svc_reg 3 ,
.It Fn svc_tli_create Ta Xr rpc_svc_create 3 ,
.It Fn svc_tp_create Ta Xr rpc_svc_create 3 ,
.It Fn svc_unreg Ta Xr rpc_svc_calls 3 ,
.It Fn svc_unregister Ta Xr rpc_soc 3 ,
.It Fn svc_vc_create Ta Xr rpc_svc_create 3 ,
.It Fn svcerr_auth Ta Xr rpc_svc_err 3 ,
.It Fn svcerr_decode Ta Xr rpc_svc_err 3 ,
.It Fn svcerr_noproc Ta Xr rpc_svc_err 3 ,
.It Fn svcerr_noprog Ta Xr rpc_svc_err 3 ,
.It Fn svcerr_progvers Ta Xr rpc_svc_err 3 ,
.It Fn svcerr_systemerr Ta Xr rpc_svc_err 3 ,
.It Fn svcerr_weakauth Ta Xr rpc_svc_err 3 ,
.It Fn svcfd_create Ta Xr rpc_soc 3 ,
.It Fn svcraw_create Ta Xr rpc_soc 3 ,
.It Fn svctcp_create Ta Xr rpc_soc 3 ,
.It Fn svcudp_bufcreate Ta Xr rpc_soc 3 ,
.It Fn svcudp_create Ta Xr rpc_soc 3 ,
.It Fn xdr_accepted_reply Ta Xr rpc_xdr 3 ,
.It Fn xdr_authsys_parms Ta Xr rpc_xdr 3 ,
.It Fn xdr_authunix_parms Ta Xr rpc_soc 3 ,
.It Fn xdr_callhdr Ta Xr rpc_xdr 3 ,
.It Fn xdr_callmsg Ta Xr rpc_xdr 3 ,
.It Fn xdr_opaque_auth Ta Xr rpc_xdr 3 ,
.It Fn xdr_rejected_reply Ta Xr rpc_xdr 3 ,
.It Fn xdr_replymsg Ta Xr rpc_xdr 3 ,
.It Fn xprt_register Ta Xr rpc_svc_calls 3 ,
.It Fn xprt_unregister Ta Xr rpc_svc_calls 3 ,
.El
.Sh FILES
.Pa /etc/netconfig
.Sh SEE ALSO
.Xr getnetconfig 3 ,
.Xr getnetpath 3 ,
.Xr rpc_clnt_auth 3 ,
.Xr rpc_clnt_calls 3 ,
.Xr rpc_clnt_create 3 ,
.Xr rpc_svc_calls 3 ,
.Xr rpc_svc_create 3 ,
.Xr rpc_svc_err 3 ,
.Xr rpc_svc_reg 3 ,
.Xr rpc_xdr 3 ,
.Xr rpcbind 3 ,
.Xr xdr 3 ,
.Xr netconfig 5