| .\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4 |
| .\" Copyright 1989 AT&T |
| .Dd May 7, 1993 |
| .Dt RPC 3 |
| .Os |
| .Sh NAME |
| .Nm rpc |
| .Nd library routines for remote procedure calls |
| .Sh LIBRARY |
| .Lb libc |
| .Sh SYNOPSIS |
| .In rpc/rpc.h |
| .In netconfig.h |
| .Sh 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. |
| .Pp |
| 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. |
| .Sh 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. |
| .Pp |
| The |
| .Fa nettype |
| argument |
| can be one of the following: |
| .Bl -tag -width datagram_v |
| .It netpath |
| Choose from the transports which have been |
| indicated by their token names in the |
| .Ev NETPATH |
| environment variable. |
| .Ev NETPATH |
| is unset or |
| .Dv NULL , |
| it defaults to |
| .Qq visible . |
| .Qq netpath |
| is the default |
| .Fa nettype . |
| .It visible |
| Choose the transports which have the visible flag (v) |
| set in the |
| .Pa /etc/netconfig |
| file. |
| .It 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 |
| .Pa /etc/netconfig |
| file. |
| .It 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 |
| .Pa /etc/netconfig |
| file. |
| .It 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 ) . |
| .It datagram_n |
| This is same as |
| .Qq netpath |
| except that it chooses only the connectionless datagram transports |
| (semantics |
| .Qq tpi_clts ) . |
| .It udp |
| This refers to Internet UDP, both version 4 and 6. |
| .It tcp |
| This refers to Internet TCP, both version 4 and 6. |
| .El |
| .Pp |
| If |
| .Fa nettype |
| is |
| .Dv NULL , |
| it defaults to |
| .Qq netpath . |
| The transports are tried in left to right order in the |
| .Ev NETPATH |
| variable or in top to down order in the |
| .Pa /etc/netconfig |
| file. |
| .Sh Derived Types |
| The derived types used in the RPC interfaces are defined as follows: |
| .Bd -literal |
| 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; |
| .Ed |
| .Sh "Data Structures" |
| Some of the data structures used by the |
| RPC package are shown below. |
| .Sh "The AUTH Structure" |
| .Bd -literal |
| /* |
| * 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; |
| .Ed |
| .Sh "The CLIENT Structure" |
| .Bd -literal |
| /* |
| * 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; |
| .Ed |
| .Sh "The SVCXPRT structure" |
| .Bd -literal |
| 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; |
| .Ed |
| .Sh "The svc_reg structure" |
| .Bd -literal |
| 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 */ |
| }; |
| .Ed |
| .Sh "The XDR structure" |
| .Bd -literal |
| /* |
| * 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) \e * 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; |
| }; |
| .Ed |
| .Sh "Index to Routines" |
| The following table lists RPC routines and the manual reference |
| pages on which they are described: |
| .Pp |
| .Bl -tag -width "authunix_create_default()" -compact |
| .It Em "RPC Routine" |
| .Em "Manual Reference Page" |
| .Pp |
| .It Fn auth_destroy |
| .Xr rpc_clnt_auth 3 |
| .It Fn authdes_create |
| .Xr rpc_soc 3 |
| .It Fn authnone_create |
| .Xr rpc_clnt_auth 3 |
| .It Fn authsys_create |
| .Xr rpc_clnt_auth 3 |
| .It Fn authsys_create_default |
| .Xr rpc_clnt_auth 3 |
| .It Fn authunix_create |
| .Xr rpc_soc 3 |
| .It Fn authunix_create_default |
| .Xr rpc_soc 3 |
| .It Fn callrpc |
| .Xr rpc_soc 3 |
| .It Fn clnt_broadcast |
| .Xr rpc_soc 3 |
| .It Fn clnt_call |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_control |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_create |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_create_timed |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_create_vers |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_create_vers_timed |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_destroy |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_dg_create |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_freeres |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_geterr |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_pcreateerror |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_perrno |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_perror |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_raw_create |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_spcreateerror |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_sperrno |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_sperror |
| .Xr rpc_clnt_calls 3 |
| .It Fn clnt_tli_create |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_tp_create |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_tp_create_timed |
| .Xr rpc_clnt_create 3 |
| .It Fn clnt_udpcreate |
| .Xr rpc_soc 3 |
| .It Fn clnt_vc_create |
| .Xr rpc_clnt_create 3 |
| .It Fn clntraw_create |
| .Xr rpc_soc 3 |
| .It Fn clnttcp_create |
| .Xr rpc_soc 3 |
| .It Fn clntudp_bufcreate |
| .Xr rpc_soc 3 |
| .It Fn get_myaddress |
| .Xr rpc_soc 3 |
| .It Fn pmap_getmaps |
| .Xr rpc_soc 3 |
| .It Fn pmap_getport |
| .Xr rpc_soc 3 |
| .It Fn pmap_rmtcall |
| .Xr rpc_soc 3 |
| .It Fn pmap_set |
| .Xr rpc_soc 3 |
| .It Fn pmap_unset |
| .Xr rpc_soc 3 |
| .It Fn registerrpc |
| .Xr rpc_soc 3 |
| .It Fn rpc_broadcast |
| .Xr rpc_clnt_calls 3 |
| .It Fn rpc_broadcast_exp |
| .Xr rpc_clnt_calls 3 |
| .It Fn rpc_call |
| .Xr rpc_clnt_calls 3 |
| .It Fn rpc_reg |
| .Xr rpc_svc_calls 3 |
| .It Fn svc_create |
| .Xr rpc_svc_create 3 |
| .It Fn svc_destroy |
| .Xr rpc_svc_create 3 |
| .It Fn svc_dg_create |
| .Xr rpc_svc_create 3 |
| .It Fn svc_dg_enablecache |
| .Xr rpc_svc_calls 3 |
| .It Fn svc_fd_create |
| .Xr rpc_svc_create 3 |
| .It Fn svc_fds |
| .Xr rpc_soc 3 |
| .It Fn svc_freeargs |
| .Xr rpc_svc_reg 3 |
| .It Fn svc_getargs |
| .Xr rpc_svc_reg 3 |
| .It Fn svc_getcaller |
| .Xr rpc_soc 3 |
| .It Fn svc_getreq |
| .Xr rpc_soc 3 |
| .It Fn svc_getreqset |
| .Xr rpc_svc_calls 3 |
| .It Fn svc_getrpccaller |
| .Xr rpc_svc_calls 3 |
| .It Fn svc_kerb_reg |
| .Xr kerberos_rpc 3 |
| .It Fn svc_raw_create |
| .Xr rpc_svc_create 3 |
| .It Fn svc_reg |
| .Xr rpc_svc_calls 3 |
| .It Fn svc_register |
| .Xr rpc_soc 3 |
| .It Fn svc_run |
| .Xr rpc_svc_reg 3 |
| .It Fn svc_sendreply |
| .Xr rpc_svc_reg 3 |
| .It Fn svc_tli_create |
| .Xr rpc_svc_create 3 |
| .It Fn svc_tp_create |
| .Xr rpc_svc_create 3 |
| .It Fn svc_unreg |
| .Xr rpc_svc_calls 3 |
| .It Fn svc_unregister |
| .Xr rpc_soc 3 |
| .It Fn svc_vc_create |
| .Xr rpc_svc_create 3 |
| .It Fn svcerr_auth |
| .Xr rpc_svc_err 3 |
| .It Fn svcerr_decode |
| .Xr rpc_svc_err 3 |
| .It Fn svcerr_noproc |
| .Xr rpc_svc_err 3 |
| .It Fn svcerr_noprog |
| .Xr rpc_svc_err 3 |
| .It Fn svcerr_progvers |
| .Xr rpc_svc_err 3 |
| .It Fn svcerr_systemerr |
| .Xr rpc_svc_err 3 |
| .It Fn svcerr_weakauth |
| .Xr rpc_svc_err 3 |
| .It Fn svcfd_create |
| .Xr rpc_soc 3 |
| .It Fn svcraw_create |
| .Xr rpc_soc 3 |
| .It Fn svctcp_create |
| .Xr rpc_soc 3 |
| .It Fn svcudp_bufcreate |
| .Xr rpc_soc 3 |
| .It Fn svcudp_create |
| .Xr rpc_soc 3 |
| .It Fn xdr_accepted_reply |
| .Xr rpc_xdr 3 |
| .It Fn xdr_authsys_parms |
| .Xr rpc_xdr 3 |
| .It Fn xdr_authunix_parms |
| .Xr rpc_soc 3 |
| .It Fn xdr_callhdr |
| .Xr rpc_xdr 3 |
| .It Fn xdr_callmsg |
| .Xr rpc_xdr 3 |
| .It Fn xdr_opaque_auth |
| .Xr rpc_xdr 3 |
| .It Fn xdr_rejected_reply |
| .Xr rpc_xdr 3 |
| .It Fn xdr_replymsg |
| .Xr rpc_xdr 3 |
| .It Fn xprt_register |
| .Xr rpc_svc_calls 3 |
| .It Fn xprt_unregister |
| .Xr rpc_svc_calls 3 |
| .El |
| .Sh FILES |
| .Bl -tag -width /etc/netconfig |
| .It Pa /etc/netconfig |
| .El |
| .Sh SEE ALSO |
| .Xr getnetconfig 3 , |
| .Xr getnetpath 3 , |
| .Xr rpcbind 3 , |
| .Xr rpc_clnt_auth 3 , |
| .Xr rpc_clnt_calls 3 , |
| .Xr rpc_clnt_create 3 , |
| .Xr rpc_svc_calls 3 , |
| .Xr rpc_svc_create 3 , |
| .Xr rpc_svc_err 3 , |
| .Xr rpc_svc_reg 3 , |
| .Xr rpc_xdr 3 , |
| .Xr xdr 3 , |
| .Xr netconfig 5 |
