518 lines
13 KiB
Groff
518 lines
13 KiB
Groff
.\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4
|
|
.\" Copyright 1989 AT&T
|
|
.\" $NetBSD: rpc.3,v 1.10 2000/06/02 23:11:12 fvdl Exp $
|
|
.\" $FreeBSD$
|
|
.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
|
|
.In rpc/rpc.h .
|
|
Routines that take a
|
|
.Vt "struct netconfig"
|
|
also require that
|
|
.In netconfig.h
|
|
be included.
|
|
.Sh Nettype
|
|
Some of the high-level
|
|
RPC interface routines take a
|
|
.Fa nettype
|
|
string as one of the arguments
|
|
(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
|
|
The
|
|
.Fa nettype
|
|
argument
|
|
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.
|
|
.Ev NETPATH
|
|
is unset or
|
|
.Dv NULL ,
|
|
it defaults to
|
|
.Qq visible .
|
|
.Qq 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
|
|
.Qq visible
|
|
except that it chooses only the connection oriented transports
|
|
(semantics
|
|
.Qq tpi_cots
|
|
or
|
|
.Qq tpi_cots_ord )
|
|
from the entries in the
|
|
.Pa /etc/netconfig
|
|
file.
|
|
.It datagram_v
|
|
This is same as
|
|
.Qq visible
|
|
except that it chooses only the connectionless datagram transports
|
|
(semantics
|
|
.Qq tpi_clts )
|
|
from the entries in the
|
|
.Pa /etc/netconfig
|
|
file.
|
|
.It circuit_n
|
|
This is same as
|
|
.Qq netpath
|
|
except that it chooses only the connection oriented datagram transports
|
|
(semantics
|
|
.Qq tpi_cots
|
|
or
|
|
.Qq tpi_cots_ord ) .
|
|
.It datagram_n
|
|
This is same as
|
|
.Qq netpath
|
|
except that it chooses only the connectionless datagram transports
|
|
(semantics
|
|
.Qq 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
|
|
.Qq 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.
|
|
.Sh 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
|
|
.Sh "Data Structures"
|
|
Some of the data structures used by the
|
|
RPC package are shown below.
|
|
.Sh "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 & 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
|
|
.Sh "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
|
|
.Sh "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
|
|
.Sh "The svc_reg 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
|
|
.Sh "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 */
|
|
u_int x_handy; /* extra private word */
|
|
} XDR;
|
|
|
|
/*
|
|
* The netbuf structure. This structure is defined in <xti.h> on SysV
|
|
* systems, but NetBSD / FreeBSD do 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
|
|
.Sh "Index to Routines"
|
|
The following table lists RPC routines and the manual reference
|
|
pages on which they are described:
|
|
.Pp
|
|
.Bl -tag -width "authunix_create_default()" -compact
|
|
.It Em "RPC Routine"
|
|
.Em "Manual Reference Page"
|
|
.Pp
|
|
.It Fn auth_destroy
|
|
.Xr rpc_clnt_auth 3
|
|
.It Fn authdes_create
|
|
.Xr rpc_soc 3
|
|
.It Fn authnone_create
|
|
.Xr rpc_clnt_auth 3
|
|
.It Fn authsys_create
|
|
.Xr rpc_clnt_auth 3
|
|
.It Fn authsys_create_default
|
|
.Xr rpc_clnt_auth 3
|
|
.It Fn authunix_create
|
|
.Xr rpc_soc 3
|
|
.It Fn authunix_create_default
|
|
.Xr rpc_soc 3
|
|
.It Fn callrpc
|
|
.Xr rpc_soc 3
|
|
.It Fn clnt_broadcast
|
|
.Xr rpc_soc 3
|
|
.It Fn clnt_call
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_control
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_create
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_create_timed
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_create_vers
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_create_vers_timed
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_destroy
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_dg_create
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_freeres
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_geterr
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_pcreateerror
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_perrno
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_perror
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_raw_create
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_spcreateerror
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_sperrno
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_sperror
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn clnt_tli_create
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_tp_create
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_tp_create_timed
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clnt_udpcreate
|
|
.Xr rpc_soc 3
|
|
.It Fn clnt_vc_create
|
|
.Xr rpc_clnt_create 3
|
|
.It Fn clntraw_create
|
|
.Xr rpc_soc 3
|
|
.It Fn clnttcp_create
|
|
.Xr rpc_soc 3
|
|
.It Fn clntudp_bufcreate
|
|
.Xr rpc_soc 3
|
|
.It Fn get_myaddress
|
|
.Xr rpc_soc 3
|
|
.It Fn pmap_getmaps
|
|
.Xr rpc_soc 3
|
|
.It Fn pmap_getport
|
|
.Xr rpc_soc 3
|
|
.It Fn pmap_rmtcall
|
|
.Xr rpc_soc 3
|
|
.It Fn pmap_set
|
|
.Xr rpc_soc 3
|
|
.It Fn pmap_unset
|
|
.Xr rpc_soc 3
|
|
.It Fn registerrpc
|
|
.Xr rpc_soc 3
|
|
.It Fn rpc_broadcast
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn rpc_broadcast_exp
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn rpc_call
|
|
.Xr rpc_clnt_calls 3
|
|
.It Fn rpc_reg
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn svc_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_destroy
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_dg_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_dg_enablecache
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn svc_fd_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_fds
|
|
.Xr rpc_soc 3
|
|
.It Fn svc_freeargs
|
|
.Xr rpc_svc_reg 3
|
|
.It Fn svc_getargs
|
|
.Xr rpc_svc_reg 3
|
|
.It Fn svc_getcaller
|
|
.Xr rpc_soc 3
|
|
.It Fn svc_getreq
|
|
.Xr rpc_soc 3
|
|
.It Fn svc_getreqset
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn svc_getrpccaller
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn svc_kerb_reg
|
|
.Xr kerberos_rpc 3
|
|
.It Fn svc_raw_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_reg
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn svc_register
|
|
.Xr rpc_soc 3
|
|
.It Fn svc_run
|
|
.Xr rpc_svc_reg 3
|
|
.It Fn svc_sendreply
|
|
.Xr rpc_svc_reg 3
|
|
.It Fn svc_tli_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_tp_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svc_unreg
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn svc_unregister
|
|
.Xr rpc_soc 3
|
|
.It Fn svc_vc_create
|
|
.Xr rpc_svc_create 3
|
|
.It Fn svcerr_auth
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcerr_decode
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcerr_noproc
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcerr_noprog
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcerr_progvers
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcerr_systemerr
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcerr_weakauth
|
|
.Xr rpc_svc_err 3
|
|
.It Fn svcfd_create
|
|
.Xr rpc_soc 3
|
|
.It Fn svcraw_create
|
|
.Xr rpc_soc 3
|
|
.It Fn svctcp_create
|
|
.Xr rpc_soc 3
|
|
.It Fn svcudp_bufcreate
|
|
.Xr rpc_soc 3
|
|
.It Fn svcudp_create
|
|
.Xr rpc_soc 3
|
|
.It Fn xdr_accepted_reply
|
|
.Xr rpc_xdr 3
|
|
.It Fn xdr_authsys_parms
|
|
.Xr rpc_xdr 3
|
|
.It Fn xdr_authunix_parms
|
|
.Xr rpc_soc 3
|
|
.It Fn xdr_callhdr
|
|
.Xr rpc_xdr 3
|
|
.It Fn xdr_callmsg
|
|
.Xr rpc_xdr 3
|
|
.It Fn xdr_opaque_auth
|
|
.Xr rpc_xdr 3
|
|
.It Fn xdr_rejected_reply
|
|
.Xr rpc_xdr 3
|
|
.It Fn xdr_replymsg
|
|
.Xr rpc_xdr 3
|
|
.It Fn xprt_register
|
|
.Xr rpc_svc_calls 3
|
|
.It Fn xprt_unregister
|
|
.Xr rpc_svc_calls 3
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/netconfig
|
|
.It Pa /etc/netconfig
|
|
.El
|
|
.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
|