SYNOPSIS

In rpc/rpc.h In 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 In rpc/rpc.h . Routines that take a Vt struct netconfig also require that In netconfig.h be included.

Nettype

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

The Fa 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 Qq visible . Qq netpath is the default Fa nettype .

visible

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

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 /etc/netconfig file.

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 /etc/netconfig file.

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

datagram_n

This is same as Qq netpath except that it chooses only the connectionless datagram transports (semantics Qq 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 Fa nettype is NULL it defaults to Qq 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 */
    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_reg 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 */
    u_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 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

Fn auth_destroy

rpc_clnt_auth3

Fn authdes_create

rpc_soc3

Fn authnone_create

rpc_clnt_auth3

Fn authsys_create

rpc_clnt_auth3

Fn authsys_create_default

rpc_clnt_auth3

Fn authunix_create

rpc_soc3

Fn authunix_create_default

rpc_soc3

Fn callrpc

rpc_soc3

Fn clnt_broadcast

rpc_soc3

Fn clnt_call

rpc_clnt_calls3

Fn clnt_control

rpc_clnt_create3

Fn clnt_create

rpc_clnt_create3

Fn clnt_create_timed

rpc_clnt_create3

Fn clnt_create_vers

rpc_clnt_create3

Fn clnt_create_vers_timed

rpc_clnt_create3

Fn clnt_destroy

rpc_clnt_create3

Fn clnt_dg_create

rpc_clnt_create3

Fn clnt_freeres

rpc_clnt_calls3

Fn clnt_geterr

rpc_clnt_calls3

Fn clnt_pcreateerror

rpc_clnt_create3

Fn clnt_perrno

rpc_clnt_calls3

Fn clnt_perror

rpc_clnt_calls3

Fn clnt_raw_create

rpc_clnt_create3

Fn clnt_spcreateerror

rpc_clnt_create3

Fn clnt_sperrno

rpc_clnt_calls3

Fn clnt_sperror

rpc_clnt_calls3

Fn clnt_tli_create

rpc_clnt_create3

Fn clnt_tp_create

rpc_clnt_create3

Fn clnt_tp_create_timed

rpc_clnt_create3

Fn clnt_udpcreate

rpc_soc3

Fn clnt_vc_create

rpc_clnt_create3

Fn clntraw_create

rpc_soc3

Fn clnttcp_create

rpc_soc3

Fn clntudp_bufcreate

rpc_soc3

Fn get_myaddress

rpc_soc3

Fn pmap_getmaps

rpc_soc3

Fn pmap_getport

rpc_soc3

Fn pmap_rmtcall

rpc_soc3

Fn pmap_set

rpc_soc3

Fn pmap_unset

rpc_soc3

Fn registerrpc

rpc_soc3

Fn rpc_broadcast

rpc_clnt_calls3

Fn rpc_broadcast_exp

rpc_clnt_calls3

Fn rpc_call

rpc_clnt_calls3

Fn rpc_reg

rpc_svc_calls3

Fn svc_create

rpc_svc_create3

Fn svc_destroy

rpc_svc_create3

Fn svc_dg_create

rpc_svc_create3

Fn svc_dg_enablecache

rpc_svc_calls3

Fn svc_fd_create

rpc_svc_create3

Fn svc_fds

rpc_soc3

Fn svc_freeargs

rpc_svc_reg3

Fn svc_getargs

rpc_svc_reg3

Fn svc_getcaller

rpc_soc3

Fn svc_getreq

rpc_soc3

Fn svc_getreqset

rpc_svc_calls3

Fn svc_getrpccaller

rpc_svc_calls3

Fn svc_kerb_reg

kerberos_rpc3

Fn svc_raw_create

rpc_svc_create3

Fn svc_reg

rpc_svc_calls3

Fn svc_register

rpc_soc3

Fn svc_run

rpc_svc_reg3

Fn svc_sendreply

rpc_svc_reg3

Fn svc_tli_create

rpc_svc_create3

Fn svc_tp_create

rpc_svc_create3

Fn svc_unreg

rpc_svc_calls3

Fn svc_unregister

rpc_soc3

Fn svc_vc_create

rpc_svc_create3

Fn svcerr_auth

rpc_svc_err3

Fn svcerr_decode

rpc_svc_err3

Fn svcerr_noproc

rpc_svc_err3

Fn svcerr_noprog

rpc_svc_err3

Fn svcerr_progvers

rpc_svc_err3

Fn svcerr_systemerr

rpc_svc_err3

Fn svcerr_weakauth

rpc_svc_err3

Fn svcfd_create

rpc_soc3

Fn svcraw_create

rpc_soc3

Fn svctcp_create

rpc_soc3

Fn svcudp_bufcreate

rpc_soc3

Fn svcudp_create

rpc_soc3

Fn xdr_accepted_reply

rpc_xdr3

Fn xdr_authsys_parms

rpc_xdr3

Fn xdr_authunix_parms

rpc_soc3

Fn xdr_callhdr

rpc_xdr3

Fn xdr_callmsg

rpc_xdr3

Fn xdr_opaque_auth

rpc_xdr3

Fn xdr_rejected_reply

rpc_xdr3

Fn xdr_replymsg

rpc_xdr3

Fn xprt_register

rpc_svc_calls3

Fn xprt_unregister

rpc_svc_calls3

FILES

/etc/netconfig

AVAILABILITY

These functions are part of libtirpc.