RPC(3)

RPC(3) | Library Functions Manual | RPC(3)

# NAME

rpc — library routines for remote procedure calls

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

#include <rpc/rpc.h>
#include <netconfig.h>

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

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

May 7, 1993 | NetBSD 8.3