May 7, 1993 RPC 3

### NAME

rpc - library routines for remote procedure calls

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

All RPC routines require the header <```rpc/rpc.h`>. Routines that take a ```netconfig` structure also require that <```netconfig.h`> be included.

#### Nettype

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
  Choose from the transports which have been indicated by their token names in the ```NETPATH` environment variable. If ```NETPATH` is unset or ```NULL` , it defaults to ```visible`. ```netpath` is the default ```nettype`.

visible
  Choose the transports which have the visible flag (v) set in the ```/etc/netconfig` file.

circuit_v
  This is same as ```visible` except that it chooses only the connection oriented transports (semantics ```tpi_cots` or ```tpi_cots_ord`) from the entries in the ```/etc/netconfig` file.

datagram_v
  This is same as ```visible` except that it chooses only the connectionless datagram transports (semantics ```tpi_clts`) from the entries in the ```/etc/netconfig` file.

circuit_n
  This is same as ```netpath` except that it chooses only the connection oriented datagram transports (semantics ```tpi_cots` or ```tpi_cots_ord`).

datagram_n
  This is same as ```netpath` except that it chooses only the connectionless datagram transports (semantics ```tpi_clts`).

udp
  This refers to Internet UDP, both version 4 and 6.

tcp
  This refers to Internet TCP, both version 4 and 6.

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.

#### Derived Types

The derived types used in the RPC interfaces 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;

`

#### Data Structures

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

#### The AUTH Structure

`

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

`

#### The CLIENT Structure

`

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

`

#### The SVCXPRT structure

`

    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;

`

#### The svc_req structure

`

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

`

#### The XDR structure

`

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

`

#### Index to Routines

The following table lists RPC routines and the manual reference pages on which they are described:

RPC Routine | Manual Reference Page
auth_destroy(`` | rpc_clnt_auth(3)),
authdes_create(`` | rpc_soc(3)),
authnone_create(`` | rpc_clnt_auth(3)),
authsys_create(`` | rpc_clnt_auth(3)),
authsys_create_default(`` | rpc_clnt_auth(3)),
authunix_create(`` | rpc_soc(3)),
authunix_create_default(`` | rpc_soc(3)),
callrpc(`` | rpc_soc(3)),
clnt_broadcast(`` | rpc_soc(3)),
clnt_call(`` | rpc_clnt_calls(3)),
clnt_control(`` | rpc_clnt_create(3)),
clnt_create(`` | rpc_clnt_create(3)),
clnt_destroy(`` | rpc_clnt_create(3)),
clnt_dg_create(`` | rpc_clnt_create(3)),
clnt_freeres(`` | rpc_clnt_calls(3)),
clnt_geterr(`` | rpc_clnt_calls(3)),
clnt_pcreateerror(`` | rpc_clnt_create(3)),
clnt_perrno(`` | rpc_clnt_calls(3)),
clnt_perror(`` | rpc_clnt_calls(3)),
clnt_raw_create(`` | rpc_clnt_create(3)),
clnt_spcreateerror(`` | rpc_clnt_create(3)),
clnt_sperrno(`` | rpc_clnt_calls(3)),
clnt_sperror(`` | rpc_clnt_calls(3)),
clnt_tli_create(`` | rpc_clnt_create(3)),
clnt_tp_create(`` | rpc_clnt_create(3)),
clnt_udpcreate(`` | rpc_soc(3)),
clnt_vc_create(`` | rpc_clnt_create(3)),
clntraw_create(`` | rpc_soc(3)),
clnttcp_create(`` | rpc_soc(3)),
clntudp_bufcreate(`` | rpc_soc(3)),
get_myaddress(`` | rpc_soc(3)),
pmap_getmaps(`` | rpc_soc(3)),
pmap_getport(`` | rpc_soc(3)),
pmap_rmtcall(`` | rpc_soc(3)),
pmap_set(`` | rpc_soc(3)),
pmap_unset(`` | rpc_soc(3)),
registerrpc(`` | rpc_soc(3)),
rpc_broadcast(`` | rpc_clnt_calls(3)),
rpc_broadcast_exp(`` | rpc_clnt_calls(3)),
rpc_call(`` | rpc_clnt_calls(3)),
rpc_reg(`` | rpc_svc_calls(3)),
svc_create(`` | rpc_svc_create(3)),
svc_destroy(`` | rpc_svc_create(3)),
svc_dg_create(`` | rpc_svc_create(3)),
svc_dg_enablecache(`` | rpc_svc_calls(3)),
svc_fd_create(`` | rpc_svc_create(3)),
svc_fds(`` | rpc_soc(3)),
svc_freeargs(`` | rpc_svc_reg(3)),
svc_getargs(`` | rpc_svc_reg(3)),
svc_getcaller(`` | rpc_soc(3)),
svc_getreq(`` | rpc_soc(3)),
svc_getreqset(`` | rpc_svc_calls(3)),
svc_getrpccaller(`` | rpc_svc_calls(3)),
svc_kerb_reg(`` | kerberos_rpc(3)),
svc_raw_create(`` | rpc_svc_create(3)),
svc_reg(`` | rpc_svc_calls(3)),
svc_register(`` | rpc_soc(3)),
svc_run(`` | rpc_svc_reg(3)),
svc_sendreply(`` | rpc_svc_reg(3)),
svc_tli_create(`` | rpc_svc_create(3)),
svc_tp_create(`` | rpc_svc_create(3)),
svc_unreg(`` | rpc_svc_calls(3)),
svc_unregister(`` | rpc_soc(3)),
svc_vc_create(`` | rpc_svc_create(3)),
svcerr_auth(`` | rpc_svc_err(3)),
svcerr_decode(`` | rpc_svc_err(3)),
svcerr_noproc(`` | rpc_svc_err(3)),
svcerr_noprog(`` | rpc_svc_err(3)),
svcerr_progvers(`` | rpc_svc_err(3)),
svcerr_systemerr(`` | rpc_svc_err(3)),
svcerr_weakauth(`` | rpc_svc_err(3)),
svcfd_create(`` | rpc_soc(3)),
svcraw_create(`` | rpc_soc(3)),
svctcp_create(`` | rpc_soc(3)),
svcudp_bufcreate(`` | rpc_soc(3)),
svcudp_create(`` | rpc_soc(3)),
xdr_accepted_reply(`` | rpc_xdr(3)),
xdr_authsys_parms(`` | rpc_xdr(3)),
xdr_authunix_parms(`` | rpc_soc(3)),
xdr_callhdr(`` | rpc_xdr(3)),
xdr_callmsg(`` | rpc_xdr(3)),
xdr_opaque_auth(`` | rpc_xdr(3)),
xdr_rejected_reply(`` | rpc_xdr(3)),
xdr_replymsg(`` | rpc_xdr(3)),
xprt_register(`` | rpc_svc_calls(3)),
xprt_unregister(`` | rpc_svc_calls(3)),

### FILES

```/etc/netconfig`

### SEE ALSO

getnetconfig(3), getnetpath(3), rpc_clnt_auth(3), rpc_clnt_calls(3), rpc_clnt_create(3), rpc_svc_calls(3), rpc_svc_create(3), rpc_svc_err(3), rpc_svc_reg(3), rpc_xdr(3), rpcbind(3), xdr(3), netconfig(5)