1.\" Copyright 1989 AT&T 2.\" $NetBSD: rpc.3,v 1.10 2000/06/02 23:11:12 fvdl Exp $ 3.Dd May 7, 1993 4.Dt RPC 3 5.Os 6.Sh NAME 7.Nm rpc 8.Nd library routines for remote procedure calls 9.Sh LIBRARY 10.Lb libc 11.Sh SYNOPSIS 12.In rpc/rpc.h 13.In netconfig.h 14.Sh DESCRIPTION 15These 16routines allow C language programs to make procedure 17calls on other machines across a network. 18First, the client sends a request to the server. 19On receipt of the request, the server calls a dispatch routine 20to perform the requested service, and then sends back a reply. 21.Pp 22All 23RPC routines require the header 24.In rpc/rpc.h . 25Routines that take a 26.Vt "struct netconfig" 27also require that 28.In netconfig.h 29be included. 30.Sh Nettype 31Some of the high-level 32RPC interface routines take a 33.Fa nettype 34string as one of the arguments 35(for example, 36.Fn clnt_create , 37.Fn svc_create , 38.Fn rpc_reg , 39.Fn rpc_call ) . 40This string defines a class of transports which can be used 41for a particular application. 42.Pp 43The 44.Fa nettype 45argument 46can be one of the following: 47.Bl -tag -width datagram_v 48.It netpath 49Choose from the transports which have been 50indicated by their token names in the 51.Ev NETPATH 52environment variable. 53.Ev NETPATH 54is unset or 55.Dv NULL , 56it defaults to 57.Qq visible . 58.Qq netpath 59is the default 60.Fa nettype . 61.It visible 62Choose the transports which have the visible flag (v) 63set in the 64.Pa /etc/netconfig 65file. 66.It circuit_v 67This is same as 68.Qq visible 69except that it chooses only the connection oriented transports 70(semantics 71.Qq tpi_cots 72or 73.Qq tpi_cots_ord ) 74from the entries in the 75.Pa /etc/netconfig 76file. 77.It datagram_v 78This is same as 79.Qq visible 80except that it chooses only the connectionless datagram transports 81(semantics 82.Qq tpi_clts ) 83from the entries in the 84.Pa /etc/netconfig 85file. 86.It circuit_n 87This is same as 88.Qq netpath 89except that it chooses only the connection oriented datagram transports 90(semantics 91.Qq tpi_cots 92or 93.Qq tpi_cots_ord ) . 94.It datagram_n 95This is same as 96.Qq netpath 97except that it chooses only the connectionless datagram transports 98(semantics 99.Qq tpi_clts ) . 100.It udp 101This refers to Internet UDP, both version 4 and 6. 102.It tcp 103This refers to Internet TCP, both version 4 and 6. 104.El 105.Pp 106If 107.Fa nettype 108is 109.Dv NULL , 110it defaults to 111.Qq netpath . 112The transports are tried in left to right order in the 113.Ev NETPATH 114variable or in top to down order in the 115.Pa /etc/netconfig 116file. 117.Sh Derived Types 118The derived types used in the RPC interfaces are defined as follows: 119.Bd -literal 120 typedef uint32_t rpcprog_t; 121 typedef uint32_t rpcvers_t; 122 typedef uint32_t rpcproc_t; 123 typedef uint32_t rpcprot_t; 124 typedef uint32_t rpcport_t; 125 typedef int32_t rpc_inline_t; 126.Ed 127.Sh "Data Structures" 128Some of the data structures used by the 129RPC package are shown below. 130.Sh "The AUTH Structure" 131.Bd -literal 132/* 133 * Authentication info. Opaque to client. 134 */ 135struct opaque_auth { 136 enum_t oa_flavor; /* flavor of auth */ 137 caddr_t oa_base; /* address of more auth stuff */ 138 u_int oa_length; /* not to exceed MAX_AUTH_BYTES */ 139}; 140 141/* 142 * Auth handle, interface to client side authenticators. 143 */ 144typedef struct { 145 struct opaque_auth ah_cred; 146 struct opaque_auth ah_verf; 147 struct auth_ops { 148 void (*ah_nextverf)(\|); 149 int (*ah_marshal)(\|); /* nextverf & serialize */ 150 int (*ah_validate)(\|); /* validate verifier */ 151 int (*ah_refresh)(\|); /* refresh credentials */ 152 void (*ah_destroy)(\|); /* destroy this structure */ 153 } *ah_ops; 154 caddr_t ah_private; 155} AUTH; 156.Ed 157.Sh "The CLIENT Structure" 158.Bd -literal 159/* 160 * Client rpc handle. 161 * Created by individual implementations. 162 * Client is responsible for initializing auth. 163 */ 164 165typedef struct { 166 AUTH *cl_auth; /* authenticator */ 167 struct clnt_ops { 168 enum clnt_stat (*cl_call)(); /* call remote procedure */ 169 void (*cl_abort)(); /* abort a call */ 170 void (*cl_geterr)(); /* get specific error code */ 171 bool_t (*cl_freeres)(); /* frees results */ 172 void (*cl_destroy)(); /* destroy this structure */ 173 bool_t (*cl_control)(); /* the ioctl() of rpc */ 174 } *cl_ops; 175 caddr_t cl_private; /* private stuff */ 176 char *cl_netid; /* network identifier */ 177 char *cl_tp; /* device name */ 178} CLIENT; 179.Ed 180.Sh "The SVCXPRT structure" 181.Bd -literal 182enum xprt_stat { 183 XPRT_DIED, 184 XPRT_MOREREQS, 185 XPRT_IDLE 186}; 187 188/* 189 * Server side transport handle 190 */ 191typedef struct { 192 int xp_fd; /* file descriptor for the server handle */ 193 u_short xp_port; /* obsolete */ 194 const struct xp_ops { 195 bool_t (*xp_recv)(); /* receive incoming requests */ 196 enum xprt_stat (*xp_stat)(); /* get transport status */ 197 bool_t (*xp_getargs)(); /* get arguments */ 198 bool_t (*xp_reply)(); /* send reply */ 199 bool_t (*xp_freeargs)(); /* free mem allocated for args */ 200 void (*xp_destroy)(); /* destroy this struct */ 201 } *xp_ops; 202 int xp_addrlen; /* length of remote addr. Obsolete */ 203 struct sockaddr_in xp_raddr; /* Obsolete */ 204 const struct xp_ops2 { 205 bool_t (*xp_control)(); /* catch-all function */ 206 } *xp_ops2; 207 char *xp_tp; /* transport provider device name */ 208 char *xp_netid; /* network identifier */ 209 struct netbuf xp_ltaddr; /* local transport address */ 210 struct netbuf xp_rtaddr; /* remote transport address */ 211 struct opaque_auth xp_verf; /* raw response verifier */ 212 caddr_t xp_p1; /* private: for use by svc ops */ 213 caddr_t xp_p2; /* private: for use by svc ops */ 214 caddr_t xp_p3; /* private: for use by svc lib */ 215 int xp_type /* transport type */ 216} SVCXPRT; 217.Ed 218.Sh "The svc_reg structure" 219.Bd -literal 220struct svc_req { 221 rpcprog_t rq_prog; /* service program number */ 222 rpcvers_t rq_vers; /* service protocol version */ 223 rpcproc_t rq_proc; /* the desired procedure */ 224 struct opaque_auth rq_cred; /* raw creds from the wire */ 225 caddr_t rq_clntcred; /* read only cooked cred */ 226 SVCXPRT *rq_xprt; /* associated transport */ 227}; 228.Ed 229.Sh "The XDR structure" 230.Bd -literal 231/* 232 * XDR operations. 233 * XDR_ENCODE causes the type to be encoded into the stream. 234 * XDR_DECODE causes the type to be extracted from the stream. 235 * XDR_FREE can be used to release the space allocated by an XDR_DECODE 236 * request. 237 */ 238enum xdr_op { 239 XDR_ENCODE=0, 240 XDR_DECODE=1, 241 XDR_FREE=2 242}; 243/* 244 * This is the number of bytes per unit of external data. 245 */ 246#define BYTES_PER_XDR_UNIT (4) 247#define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) / 248 BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT) 249 250/* 251 * A xdrproc_t exists for each data type which is to be encoded or 252 * decoded. The second argument to the xdrproc_t is a pointer to 253 * an opaque pointer. The opaque pointer generally points to a 254 * structure of the data type to be decoded. If this points to 0, 255 * then the type routines should allocate dynamic storage of the 256 * appropriate size and return it. 257 * bool_t (*xdrproc_t)(XDR *, caddr_t *); 258 */ 259typedef bool_t (*xdrproc_t)(); 260 261/* 262 * The XDR handle. 263 * Contains operation which is being applied to the stream, 264 * an operations vector for the particular implementation 265 */ 266typedef struct { 267 enum xdr_op x_op; /* operation; fast additional param */ 268 struct xdr_ops { 269 bool_t (*x_getlong)(); /* get a long from underlying stream */ 270 bool_t (*x_putlong)(); /* put a long to underlying stream */ 271 bool_t (*x_getbytes)(); /* get bytes from underlying stream */ 272 bool_t (*x_putbytes)(); /* put bytes to underlying stream */ 273 u_int (*x_getpostn)(); /* returns bytes off from beginning */ 274 bool_t (*x_setpostn)(); /* lets you reposition the stream */ 275 long * (*x_inline)(); /* buf quick ptr to buffered data */ 276 void (*x_destroy)(); /* free privates of this xdr_stream */ 277 } *x_ops; 278 caddr_t x_public; /* users' data */ 279 caddr_t x_private; /* pointer to private data */ 280 caddr_t x_base; /* private used for position info */ 281 u_int x_handy; /* extra private word */ 282} XDR; 283 284/* 285 * The netbuf structure. This structure is defined in <xti.h> on SysV 286 * systems, but NetBSD / FreeBSD do not use XTI. 287 * 288 * Usually, buf will point to a struct sockaddr, and len and maxlen 289 * will contain the length and maximum length of that socket address, 290 * respectively. 291 */ 292struct netbuf { 293 unsigned int maxlen; 294 unsigned int len; 295 void *buf; 296}; 297 298/* 299 * The format of the address and options arguments of the XTI t_bind call. 300 * Only provided for compatibility, it should not be used other than 301 * as an argument to svc_tli_create(). 302 */ 303 304struct t_bind { 305 struct netbuf addr; 306 unsigned int qlen; 307}; 308.Ed 309.Sh "Index to Routines" 310The following table lists RPC routines and the manual reference 311pages on which they are described: 312.Pp 313.Bl -tag -width "authunix_create_default()" -compact 314.It Em "RPC Routine" 315.Em "Manual Reference Page" 316.Pp 317.It Fn auth_destroy 318.Xr rpc_clnt_auth 3 319.It Fn authdes_create 320.Xr rpc_soc 3 321.It Fn authnone_create 322.Xr rpc_clnt_auth 3 323.It Fn authsys_create 324.Xr rpc_clnt_auth 3 325.It Fn authsys_create_default 326.Xr rpc_clnt_auth 3 327.It Fn authunix_create 328.Xr rpc_soc 3 329.It Fn authunix_create_default 330.Xr rpc_soc 3 331.It Fn callrpc 332.Xr rpc_soc 3 333.It Fn clnt_broadcast 334.Xr rpc_soc 3 335.It Fn clnt_call 336.Xr rpc_clnt_calls 3 337.It Fn clnt_control 338.Xr rpc_clnt_create 3 339.It Fn clnt_create 340.Xr rpc_clnt_create 3 341.It Fn clnt_create_timed 342.Xr rpc_clnt_create 3 343.It Fn clnt_create_vers 344.Xr rpc_clnt_create 3 345.It Fn clnt_create_vers_timed 346.Xr rpc_clnt_create 3 347.It Fn clnt_destroy 348.Xr rpc_clnt_create 3 349.It Fn clnt_dg_create 350.Xr rpc_clnt_create 3 351.It Fn clnt_freeres 352.Xr rpc_clnt_calls 3 353.It Fn clnt_geterr 354.Xr rpc_clnt_calls 3 355.It Fn clnt_pcreateerror 356.Xr rpc_clnt_create 3 357.It Fn clnt_perrno 358.Xr rpc_clnt_calls 3 359.It Fn clnt_perror 360.Xr rpc_clnt_calls 3 361.It Fn clnt_raw_create 362.Xr rpc_clnt_create 3 363.It Fn clnt_spcreateerror 364.Xr rpc_clnt_create 3 365.It Fn clnt_sperrno 366.Xr rpc_clnt_calls 3 367.It Fn clnt_sperror 368.Xr rpc_clnt_calls 3 369.It Fn clnt_tli_create 370.Xr rpc_clnt_create 3 371.It Fn clnt_tp_create 372.Xr rpc_clnt_create 3 373.It Fn clnt_tp_create_timed 374.Xr rpc_clnt_create 3 375.It Fn clnt_udpcreate 376.Xr rpc_soc 3 377.It Fn clnt_vc_create 378.Xr rpc_clnt_create 3 379.It Fn clntraw_create 380.Xr rpc_soc 3 381.It Fn clnttcp_create 382.Xr rpc_soc 3 383.It Fn clntudp_bufcreate 384.Xr rpc_soc 3 385.It Fn get_myaddress 386.Xr rpc_soc 3 387.It Fn pmap_getmaps 388.Xr rpc_soc 3 389.It Fn pmap_getport 390.Xr rpc_soc 3 391.It Fn pmap_rmtcall 392.Xr rpc_soc 3 393.It Fn pmap_set 394.Xr rpc_soc 3 395.It Fn pmap_unset 396.Xr rpc_soc 3 397.It Fn registerrpc 398.Xr rpc_soc 3 399.It Fn rpc_broadcast 400.Xr rpc_clnt_calls 3 401.It Fn rpc_broadcast_exp 402.Xr rpc_clnt_calls 3 403.It Fn rpc_call 404.Xr rpc_clnt_calls 3 405.It Fn rpc_reg 406.Xr rpc_svc_calls 3 407.It Fn svc_create 408.Xr rpc_svc_create 3 409.It Fn svc_destroy 410.Xr rpc_svc_create 3 411.It Fn svc_dg_create 412.Xr rpc_svc_create 3 413.It Fn svc_dg_enablecache 414.Xr rpc_svc_calls 3 415.It Fn svc_fd_create 416.Xr rpc_svc_create 3 417.It Fn svc_fds 418.Xr rpc_soc 3 419.It Fn svc_freeargs 420.Xr rpc_svc_reg 3 421.It Fn svc_getargs 422.Xr rpc_svc_reg 3 423.It Fn svc_getcaller 424.Xr rpc_soc 3 425.It Fn svc_getreq 426.Xr rpc_soc 3 427.It Fn svc_getreqset 428.Xr rpc_svc_calls 3 429.It Fn svc_getrpccaller 430.Xr rpc_svc_calls 3 431.It Fn svc_kerb_reg 432.Xr kerberos_rpc 3 433.It Fn svc_raw_create 434.Xr rpc_svc_create 3 435.It Fn svc_reg 436.Xr rpc_svc_calls 3 437.It Fn svc_register 438.Xr rpc_soc 3 439.It Fn svc_run 440.Xr rpc_svc_reg 3 441.It Fn svc_sendreply 442.Xr rpc_svc_reg 3 443.It Fn svc_tli_create 444.Xr rpc_svc_create 3 445.It Fn svc_tp_create 446.Xr rpc_svc_create 3 447.It Fn svc_unreg 448.Xr rpc_svc_calls 3 449.It Fn svc_unregister 450.Xr rpc_soc 3 451.It Fn svc_vc_create 452.Xr rpc_svc_create 3 453.It Fn svcerr_auth 454.Xr rpc_svc_err 3 455.It Fn svcerr_decode 456.Xr rpc_svc_err 3 457.It Fn svcerr_noproc 458.Xr rpc_svc_err 3 459.It Fn svcerr_noprog 460.Xr rpc_svc_err 3 461.It Fn svcerr_progvers 462.Xr rpc_svc_err 3 463.It Fn svcerr_systemerr 464.Xr rpc_svc_err 3 465.It Fn svcerr_weakauth 466.Xr rpc_svc_err 3 467.It Fn svcfd_create 468.Xr rpc_soc 3 469.It Fn svcraw_create 470.Xr rpc_soc 3 471.It Fn svctcp_create 472.Xr rpc_soc 3 473.It Fn svcudp_bufcreate 474.Xr rpc_soc 3 475.It Fn svcudp_create 476.Xr rpc_soc 3 477.It Fn xdr_accepted_reply 478.Xr rpc_xdr 3 479.It Fn xdr_authsys_parms 480.Xr rpc_xdr 3 481.It Fn xdr_authunix_parms 482.Xr rpc_soc 3 483.It Fn xdr_callhdr 484.Xr rpc_xdr 3 485.It Fn xdr_callmsg 486.Xr rpc_xdr 3 487.It Fn xdr_opaque_auth 488.Xr rpc_xdr 3 489.It Fn xdr_rejected_reply 490.Xr rpc_xdr 3 491.It Fn xdr_replymsg 492.Xr rpc_xdr 3 493.It Fn xprt_register 494.Xr rpc_svc_calls 3 495.It Fn xprt_unregister 496.Xr rpc_svc_calls 3 497.El 498.Sh FILES 499.Bl -tag -width /etc/netconfig 500.It Pa /etc/netconfig 501.El 502.Sh SEE ALSO 503.Xr getnetconfig 3 , 504.Xr getnetpath 3 , 505.Xr rpc_clnt_auth 3 , 506.Xr rpc_clnt_calls 3 , 507.Xr rpc_clnt_create 3 , 508.Xr rpc_svc_calls 3 , 509.Xr rpc_svc_create 3 , 510.Xr rpc_svc_err 3 , 511.Xr rpc_svc_reg 3 , 512.Xr rpc_xdr 3 , 513.Xr rpcbind 3 , 514.Xr xdr 3 , 515.Xr netconfig 5 516