\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4
\" Copyright 1989 AT&T
\"      $NetBSD: rpc.3,v 1.25 2017/07/03 21:32:49 wiz 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
In rpc/rpc.h .
Routines that take a
Fa netconfig
structure also require that
In 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 & 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.
*/
typedef  bool_t (*xdrproc_t)(XDR *, const void *);

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.