freebsd-skq/lib/libc/rpc/rpc.3
alfred f67e4a8fc7 Bring in a hybrid of SunSoft's transport-independent RPC (TI-RPC) and
associated changes that had to happen to make this possible as well as
bugs fixed along the way.

  Bring in required TLI library routines to support this.

  Since we don't support TLI we've essentially copied what NetBSD
  has done, adding a thin layer to emulate direct the TLI calls
  into BSD socket calls.

  This is mostly from Sun's tirpc release that was made in 1994,
  however some fixes were backported from the 1999 release (supposedly
  only made available after this porting effort was underway).

  The submitter has agreed to continue on and bring us up to the
  1999 release.

  Several key features are introduced with this update:
    Client calls are thread safe. (1999 code has server side thread
    safe)
    Updated, a more modern interface.

  Many userland updates were done to bring the code up to par with
  the recent RPC API.

  There is an update to the pthreads library, a function
  pthread_main_np() was added to emulate a function of Sun's threads
  library.

  While we're at it, bring in NetBSD's lockd, it's been far too
  long of a wait.

  New rpcbind(8) replaces portmap(8) (supporting communication over
  an authenticated Unix-domain socket, and by default only allowing
  set and unset requests over that channel). It's much more secure
  than the old portmapper.

  Umount(8), mountd(8), mount_nfs(8), nfsd(8) have also been upgraded
  to support TI-RPC and to support IPV6.

  Umount(8) is also fixed to unmount pathnames longer than 80 chars,
  which are currently truncated by the Kernel statfs structure.

Submitted by: Martin Blapp <mb@imp.ch>
Manpage review: ru
Secure RPC implemented by: wpaul
2001-03-19 12:50:13 +00:00

508 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
.Fd #include <rpc/rpc.h>
.Fd #include <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
.Vt "struct netconfig"
also require that
.Aq Pa netconfig.h
be included.
.Sh 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.
.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 u_int32_t rpcprog_t;
typedef u_int32_t rpcvers_t;
typedef u_int32_t rpcproc_t;
typedef u_int32_t rpcprot_t;
typedef u_int32_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 */
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 addres 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_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_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