RPC(3)

NAME
rpc - library routines for remote procedure calls

LIBRARY
libc

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 struct netconfig also require that <netconfig.h> be included.

Nettype
Some of the high-level RPC interface routines take a nettype string as one of the arguments (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.

The nettype argument can be one of the following:

netpath
    Choose from the transports which have been indicated by their token names in the NETPATH environment variable. 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 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;

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 */
        u_int    oa_length;    /* not to exceed MAX_AUTH_BYTES */
        char    oa_body[MAX_AUTH_BYTES];
    };
    /*
     * Auth handle, interface to client side authenticators.
     */
    typedef struct {
        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;
        struct opaque_auth  ah_cred;
        struct opaque_auth  ah_verf;
        void *ah_private;
    } AUTH;

The CLIENT Structure

    /*
     * Client rpc handle.
     * Created by individual implementations.
     * Client is responsible for initializing auth.
     */
    typedef struct {
        struct clnt_ops {
            enum clnt_stat    (*cl_call)();    /* call remote procedure */
            void    (*cl_abort)();        /* abort a call */
            bool_t    (*cl_freeres)();    /* frees results */
            void    (*cl_destroy)();    /* destroy this structure */
            bool_t    (*cl_control)();    /* the ioctl() of rpc */
        } *cl_ops;
        char    *cl_netid;    /* network identifier */
        char    *cl_tp;        /* device name */
        void *cl_u1;           /* client user data */
        void *cl_u2;           /* client user data */
        struct rpc_err cl_error; /* specific error code */
    } CLIENT;

The SVCXPRT structure

    enum xprt_stat {
        XPRT_IDLE = 0,
        XPRT_DIED,
        XPRT_DESTROYED
    };
    /*
     * Server side transport handle
     */
    typedef struct {
        const struct xp_ops {
            enum xprt_stat    (*xp_recv)();    /* receive incoming requests */
            enum xprt_stat    (*xp_stat)();    /* get transport status */
            enum xprt_stat    (*xp_decode)();  /* get arguments */
            enum xprt_stat    (*xp_reply)();   /* send reply */
            void    (*xp_checksum)();          /* checksum for cache */
            void    (*xp_destroy)();    /* destroy this struct */
            bool_t    (*xp_control)();    /* catch-all function */
        } *xp_ops;
        char    *xp_tp;    /* transport provider device name */
        char    *xp_netid;    /* network identifier */
        void *xp_p1;    /* private: for use by svc ops */
        void *xp_p2;    /* private: for use by svc ops */
        void *xp_p3;    /* private: for use by svc lib */
        void *xp_u1;    /* public: user data */
        void *xp_u2;    /* public: user data */
        struct rpc_address xp_local;	/* local address, length, port */
        struct rpc_address xp_remote;	/* remote address, length, port */
        int    xp_fd;    /* file descriptor for the server handle */
        int    xp_type    /* transport type */
    } SVCXPRT;

The svc_req structure

    struct svc_req {
        SVCXPRT    *rq_xprt;    /* associated transport */
        struct rpc_msg rq_msg;
    };

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 *, ...);
     */
    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 */
        const 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;
        void *x_public; /* users' data */
        void *x_private; /* pointer to private data */
        void *x_lib[2]; /* RPC library private */
        uint8_t *x_data;  /* private used for position inline */
        void *x_base;  /* private used for position info */
        struct xdr_vio x_v; /* private buffer vector */
        u_int x_handy; /* extra private word */
        u_int x_flags; /* shared flags */
    } 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;
    };

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)
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)
clnt_call()
    rpc_clnt_calls(3)
clnt_control()
    rpc_clnt_create(3)
clnt_create()
    rpc_clnt_create(3)
clnt_create_timed()
    rpc_clnt_create(3)
clnt_create_vers()
    rpc_clnt_create(3)
clnt_create_vers_timed()
    rpc_clnt_create(3)
clnt_destroy()
    rpc_clnt_create(3)
clnt_dg_create()
    rpc_clnt_create(3)
clnt_freeres()
    rpc_clnt_calls(3)
clnt_perrno()
    rpc_clnt_calls(3)
clnt_raw_create()
    rpc_clnt_create(3)
clnt_sperrno()
    rpc_clnt_calls(3)
clnt_tli_create()
    rpc_clnt_create(3)
clnt_tp_create()
    rpc_clnt_create(3)
clnt_tp_create_timed()
    rpc_clnt_create(3)
clnt_udpcreate()
    rpc_soc(3)
clnt_vc_create()
    rpc_clnt_create(3)
rpc_broadcast()
    rpc_clnt_calls(3)
rpc_broadcast_exp()
    rpc_clnt_calls(3)
rpc_call()
    rpc_clnt_calls(3)
rpc_perror()
    rpc_soc(3)
rpc_sperror()
    rpc_soc(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_fd_create()
    rpc_svc_create(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_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_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)
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)

FILES

/etc/netconfig

SEE ALSO
getnetconfig(3), getnetpath(3), rpcbind(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), xdr(3), netconfig(5)