RPC_SOC(3)

NAME
rpc_soc, auth_destroy, authnone_create, authunix_create, authunix_create_default, clnt_call, clnt_control, clnt_create, clnt_destroy, clnt_freeres, clnt_perrno, clnt_sperrno, rpc_perror, rpc_sperror, SVC_DESTROY, svc_sendreply, svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth, xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_pmap, xdr_pmaplist, xdr_rejected_reply, xdr_replymsg - library routines for remote procedure calls

LIBRARY
libc

SYNOPSIS
#include <rpc/rpc.h>

See DESCRIPTION for function declarations.

DESCRIPTION
The svc_*() and clnt_*() functions described in this page are the old, TS-RPC interface to the XDR and RPC library, and exist for backward compatibility. The new interface is described in the pages referenced from rpc(3).

These routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a data packet to the server. Upon receipt of the packet, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client.

Routines that are used for Secure RPC (DES authentication) are described in rpc_secure(3). Secure RPC can be used only if DES encryption is available.

    void
    auth_destroy(AUTH *auth)

    A macro that destroys the authentication information associated with auth. Destruction usually involves deallocation of private data structures. The use of auth is undefined after calling auth_destroy().

    AUTH *
    authnone_create()

    Create and return an RPC authentication handle that passes nonusable authentication information with each remote procedure call. This is the default authentication used by RPC.

    AUTH *
    authunix_create(char *host, int uid, int gid, int len, int *aup_gids)

    Create and return an RPC authentication handle that contains UNIX authentication information. The host argument is the name of the machine on which the information was created; uid is the user's user ID; gid is the user's current group ID; len and aup_gids refer to a counted array of groups to which the user belongs. It is easy to impersonate a user.

    AUTH *
    authunix_create_default()

    Calls authunix_create() with the appropriate arguments.

    enum clnt_stat
    clnt_call(CLIENT *clnt, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out, struct timeval tout)

    A macro that calls the remote procedure procnum associated with the client handle, clnt, which is obtained with an RPC client creation routine such as clnt_create(). The in argument is the address of the procedure's argument(s), and out is the address of where to place the result(s); inproc is used to encode the procedure's arguments, and outproc is used to decode the procedure's results; tout is the time allowed for results to come back.

    void CLNT_DESTROY(CLIENT *clnt)

    A macro that destroys the client's RPC handle. Destruction usually involves deallocation of private data structures, including clnt itself. Use of clnt is undefined after calling CLNT_DESTROY(). If the RPC library opened the associated socket, it will close it also. Otherwise, the socket remains open.

    CLIENT *
    clnt_create(char *host, u_long prog, u_long vers, char *proto)

    Generic client creation routine. The host argument identifies the name of the remote host where the server is located. The proto argument indicates which kind of transport protocol to use. The currently supported values for this field are "udp" and "tcp". Default timeouts are set, but can be modified using clnt_control().

    Warning: Using UDP has its shortcomings. Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results.

    bool_t
    clnt_control(CLIENT *cl, u_int req, char *info)

    A macro used to change or retrieve various information about a client object. The req argument indicates the type of operation, and info is a pointer to the information. For both UDP and TCP, the supported values of req and their argument types and what they do are:
    CLGET_SERVER_ADDR |
    struct sockaddr_in | get server's address

    bool_t clnt_freeres(CLIENT *clnt, xdrproc_t outproc, char *out)

    A macro that frees any data allocated by the RPC/XDR system when it decoded the results of an RPC call. The out argument is the address of the results, and outproc is the XDR routine describing the results. This routine returns one if the results were successfully freed, and zero otherwise.

    void
    clnt_perrno(enum clnt_stat stat)

    Print a message to standard error corresponding to the condition indicated by stat. A newline is appended at the end of the message.

    char *
    clnt_sperrno(enum clnt_stat stat)

    Take the same arguments as clnt_perrno(), but instead of sending a message to the standard error indicating why an RPC call failed, return a pointer to a string which contains the message.

    The clnt_sperrno() function is used instead of clnt_perrno() if the program does not have a standard error (as a program running as a server quite likely does not), or if the programmer does not want the message to be output with printf(), or if a message format different from that supported by clnt_perrno() is to be used.

    Note: clnt_sperrno() returns pointer to static data, but the result will not get overwritten on each call.

    void rpc_perror(const struct rpc_err *e, const char *s)

    Print a message to standard error indicating why an RPC call failed; struct rpc_err e is the error value. The message is prepended with string s and a colon. A newline is appended at the end of the message.

    char *
    rpc_sperror(const struct rpc_err *e, const char *s)

    Like rpc_perror(), except that (like clnt_sperrno()) it returns a string instead of printing to standard error. This string must be freed after use.

    bool_t SVC_DESTROY(SVCXPRT * xprt)

    A macro that destroys the RPC service transport handle, xprt. Destruction usually involves deallocation of private data structures, including xprt itself. Use of xprt is undefined after calling this routine.

    enum xprt_stat svc_sendreply(struct svc_req *request)

    Called by an RPC service's dispatch routine to send the results of a remote procedure call. The request argument is the request. Its struct rpc_msg ar_results fields must be set: proc is the XDR routine which is used to encode the results; and where is the address of the results. This routine returns XPRT_IDLE (0) for success, XPRT_DIED or greater otherwise.

    enum xprt_stat
    svcerr_auth(SVCXPRT *xprt, enum auth_stat why)

    Called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error.

    enum xprt_stat
    svcerr_decode(SVCXPRT *xprt)

    Called by a service dispatch routine that cannot successfully decode its arguments.

    enum xprt_stat
    svcerr_noproc(SVCXPRT *xprt)

    Called by a service dispatch routine that does not implement the procedure number that the caller requests.

    enum xprt_stat
    svcerr_noprog(SVCXPRT *xprt)

    Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine.

    enum xprt_stat
    svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long high_vers)

    Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine.

    enum xprt_stat
    svcerr_systemerr(SVCXPRT *xprt)

    Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine.

    enum xprt_stat
    svcerr_weakauth(SVCXPRT *xprt)

    Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication arguments. The routine calls svcerr_auth(xprt, AUTH_TOOWEAK).

    bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *aupp)

    Used for describing UNIX credentials. This routine is useful for users who wish to generate these credentials without using the RPC authentication package.

    void
    bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdr)

    Used for describing RPC call header messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.

    bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg)

    Used for describing RPC call messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.

    bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap)

    Used for describing RPC authentication information messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.

    struct pmap;
    bool_t xdr_pmap(XDR *xdrs, struct pmap *regs)

    Used for describing arguments to various rpcbind(8) procedures, externally. This routine is useful for users who wish to generate these arguments without using the pmap_*() interface.

    bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rp)

    Used for describing a list of port mappings, externally. This routine is useful for users who wish to generate these arguments without using the pmap_*() interface.

    bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr)

    Used for describing RPC reply messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.

    bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg)

    Used for describing RPC reply messages. This routine is useful for users who wish to generate RPC style messages without using the RPC package.

SEE ALSO
rpc_secure(3), xdr(3) Remote Procedure Calls: Protocol Specification. Remote Procedure Call Programming Guide. rpcgen Programming Guide. RPC: Remote Procedure Call Protocol Specification, RFC1050, Sun Microsystems, Inc., USC-ISI.