1.\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4 2.\" Copyright 1989 AT&T 3.\" $NetBSD: rpc.3,v 1.14 2002/02/07 09:24:06 ross Exp $ 4.Dd May 7, 1993 5.Dt RPC 3 6.Os 7.Sh NAME 8.Nm rpc 9.Nd library routines for remote procedure calls 10.Sh LIBRARY 11.Lb libc 12.Sh SYNOPSIS 13.Fd #include \*[Lt]rpc/rpc.h\*[Gt] 14.Fd #include \*[Lt]netconfig.h\*[Gt] 15.Sh DESCRIPTION 16These 17routines allow C language programs to make procedure 18calls on other machines across a network. 19First, the client sends a request to the server. 20On receipt of the request, the server calls a dispatch routine 21to perform the requested service, and then sends back a reply. 22.Pp 23All 24RPC routines require the header 25.Fd \*[Lt]rpc/rpc.h\*[Gt] . 26Routines that take a 27.Fa netconfig 28structure also require that 29.Fd \*[Lt]netconfig.h\*[Gt] 30be included. 31.Ss Nettype 32Some of the high-level 33RPC interface routines take a 34.Fa nettype 35string as one of the parameters 36(for example, 37.Fn clnt_create , 38.Fn svc_create , 39.Fn rpc_reg , 40.Fn rpc_call . 41This string defines a class of transports which can be used 42for a particular application. 43.Pp 44.Fa nettype 45can be one of the following: 46.Bl -tag -width datagram_v 47.It netpath 48Choose from the transports which have been 49indicated by their token names in the 50.Ev NETPATH 51environment variable. 52If 53.Ev NETPATH 54is unset or 55.Dv NULL 56, it defaults to 57.Fa visible . 58.Fa 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.Fa visible 69except that it chooses only the connection oriented transports 70(semantics 71.Fa tpi_cots 72or 73.Fa tpi_cots_ord ) 74from the entries in the 75.Pa /etc/netconfig 76file. 77.It datagram_v 78This is same as 79.Fa visible 80except that it chooses only the connectionless datagram transports 81(semantics 82.Fa tpi_clts ) 83from the entries in the 84.Pa /etc/netconfig 85file. 86.It circuit_n 87This is same as 88.Fa netpath 89except that it chooses only the connection oriented datagram transports 90(semantics 91.Fa tpi_cots 92or 93.Fa tpi_cots_ord ) . 94.It datagram_n 95This is same as 96.Fa netpath 97except that it chooses only the connectionless datagram transports 98(semantics 99.Fa 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.I nettype 108is 109.Dv NULL , 110it defaults to 111.Fa 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.Ss Derived Types 118The derived types used in the RPC interfaces are defined as follows: 119.Bd -literal 120 typedef u_int32_t rpcprog_t; 121 typedef u_int32_t rpcvers_t; 122 typedef u_int32_t rpcproc_t; 123 typedef u_int32_t rpcprot_t; 124 typedef u_int32_t rpcport_t; 125 typedef int32_t rpc_inline_t; 126.Ed 127.Ss Data Structures 128Some of the data structures used by the 129RPC package are shown below. 130.Ss 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 \*[Am] 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.Ss 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.Ss 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.Ss 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.Ss 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 int x_handy; /* extra private word */ 282} XDR; 283 284/* 285 * The netbuf structure. This structure is defined in \*[Lt]xti.h\*[Gt] on SysV 286 * systems, but NetBSD does 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 addres 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.Ss Index to Routines 310The following table lists RPC routines and the manual reference 311pages on which they are described: 312.Bl -column "authunix_create_default()" "rpc_clnt_create(3)" 313.It Em "RPC Routine" Ta Em "Manual Reference Page" 314.Pp 315.It Fn auth_destroy Ta 316.Xr rpc_clnt_auth 3 , 317.It Fn authdes_create Ta 318.Xr rpc_soc 3 , 319.It Fn authnone_create Ta 320.Xr rpc_clnt_auth 3 , 321.It Fn authsys_create Ta 322.Xr rpc_clnt_auth 3 , 323.It Fn authsys_create_default Ta 324.Xr rpc_clnt_auth 3 , 325.It Fn authunix_create Ta 326.Xr rpc_soc 3 , 327.It Fn authunix_create_default Ta 328.Xr rpc_soc 3 , 329.It Fn callrpc Ta 330.Xr rpc_soc 3 , 331.It Fn clnt_broadcast Ta 332.Xr rpc_soc 3 , 333.It Fn clnt_call Ta 334.Xr rpc_clnt_calls 3 , 335.It Fn clnt_control Ta 336.Xr rpc_clnt_create 3 , 337.It Fn clnt_create Ta 338.Xr rpc_clnt_create 3 , 339.It Fn clnt_destroy Ta 340.Xr rpc_clnt_create 3 , 341.It Fn clnt_dg_create Ta 342.Xr rpc_clnt_create 3 , 343.It Fn clnt_freeres Ta 344.Xr rpc_clnt_calls 3 , 345.It Fn clnt_geterr Ta 346.Xr rpc_clnt_calls 3 , 347.It Fn clnt_pcreateerror Ta 348.Xr rpc_clnt_create 3 , 349.It Fn clnt_perrno Ta 350.Xr rpc_clnt_calls 3 , 351.It Fn clnt_perror Ta 352.Xr rpc_clnt_calls 3 , 353.It Fn clnt_raw_create Ta 354.Xr rpc_clnt_create 3 , 355.It Fn clnt_spcreateerror Ta 356.Xr rpc_clnt_create 3 , 357.It Fn clnt_sperrno Ta 358.Xr rpc_clnt_calls 3 , 359.It Fn clnt_sperror Ta 360.Xr rpc_clnt_calls 3 , 361.It Fn clnt_tli_create Ta 362.Xr rpc_clnt_create 3 , 363.It Fn clnt_tp_create Ta 364.Xr rpc_clnt_create 3 , 365.It Fn clnt_udpcreate Ta 366.Xr rpc_soc 3 , 367.It Fn clnt_vc_create Ta 368.Xr rpc_clnt_create 3 , 369.It Fn clntraw_create Ta 370.Xr rpc_soc 3 , 371.It Fn clnttcp_create Ta 372.Xr rpc_soc 3 , 373.It Fn clntudp_bufcreate Ta 374.Xr rpc_soc 3 , 375.It Fn get_myaddress Ta 376.Xr rpc_soc 3 , 377.It Fn pmap_getmaps Ta 378.Xr rpc_soc 3 , 379.It Fn pmap_getport Ta 380.Xr rpc_soc 3 , 381.It Fn pmap_rmtcall Ta 382.Xr rpc_soc 3 , 383.It Fn pmap_set Ta 384.Xr rpc_soc 3 , 385.It Fn pmap_unset Ta 386.Xr rpc_soc 3 , 387.It Fn registerrpc Ta 388.Xr rpc_soc 3 , 389.It Fn rpc_broadcast Ta 390.Xr rpc_clnt_calls 3 , 391.It Fn rpc_broadcast_exp Ta 392.Xr rpc_clnt_calls 3 , 393.It Fn rpc_call Ta 394.Xr rpc_clnt_calls 3 , 395.It Fn rpc_reg Ta 396.Xr rpc_svc_calls 3 , 397.It Fn svc_create Ta 398.Xr rpc_svc_create 3 , 399.It Fn svc_destroy Ta 400.Xr rpc_svc_create 3 , 401.It Fn svc_dg_create Ta 402.Xr rpc_svc_create 3 , 403.It Fn svc_dg_enablecache Ta 404.Xr rpc_svc_calls 3 , 405.It Fn svc_fd_create Ta 406.Xr rpc_svc_create 3 , 407.It Fn svc_fds Ta 408.Xr rpc_soc 3 , 409.It Fn svc_freeargs Ta 410.Xr rpc_svc_reg 3 , 411.It Fn svc_getargs Ta 412.Xr rpc_svc_reg 3 , 413.It Fn svc_getcaller Ta 414.Xr rpc_soc 3 , 415.It Fn svc_getreq Ta 416.Xr rpc_soc 3 , 417.It Fn svc_getreqset Ta 418.Xr rpc_svc_calls 3 , 419.It Fn svc_getrpccaller Ta 420.Xr rpc_svc_calls 3 , 421.It Fn svc_kerb_reg Ta 422.Xr kerberos_rpc 3 , 423.It Fn svc_raw_create Ta 424.Xr rpc_svc_create 3 , 425.It Fn svc_reg Ta 426.Xr rpc_svc_calls 3 , 427.It Fn svc_register Ta 428.Xr rpc_soc 3 , 429.It Fn svc_run Ta 430.Xr rpc_svc_reg 3 , 431.It Fn svc_sendreply Ta 432.Xr rpc_svc_reg 3 , 433.It Fn svc_tli_create Ta 434.Xr rpc_svc_create 3 , 435.It Fn svc_tp_create Ta 436.Xr rpc_svc_create 3 , 437.It Fn svc_unreg Ta 438.Xr rpc_svc_calls 3 , 439.It Fn svc_unregister Ta 440.Xr rpc_soc 3 , 441.It Fn svc_vc_create Ta 442.Xr rpc_svc_create 3 , 443.It Fn svcerr_auth Ta 444.Xr rpc_svc_err 3 , 445.It Fn svcerr_decode Ta 446.Xr rpc_svc_err 3 , 447.It Fn svcerr_noproc Ta 448.Xr rpc_svc_err 3 , 449.It Fn svcerr_noprog Ta 450.Xr rpc_svc_err 3 , 451.It Fn svcerr_progvers Ta 452.Xr rpc_svc_err 3 , 453.It Fn svcerr_systemerr Ta 454.Xr rpc_svc_err 3 , 455.It Fn svcerr_weakauth Ta 456.Xr rpc_svc_err 3 , 457.It Fn svcfd_create Ta 458.Xr rpc_soc 3 , 459.It Fn svcraw_create Ta 460.Xr rpc_soc 3 , 461.It Fn svctcp_create Ta 462.Xr rpc_soc 3 , 463.It Fn svcudp_bufcreate Ta 464.Xr rpc_soc 3 , 465.It Fn svcudp_create Ta 466.Xr rpc_soc 3 , 467.It Fn xdr_accepted_reply Ta 468.Xr rpc_xdr 3 , 469.It Fn xdr_authsys_parms Ta 470.Xr rpc_xdr 3 , 471.It Fn xdr_authunix_parms Ta 472.Xr rpc_soc 3 , 473.It Fn xdr_callhdr Ta 474.Xr rpc_xdr 3 , 475.It Fn xdr_callmsg Ta 476.Xr rpc_xdr 3 , 477.It Fn xdr_opaque_auth Ta 478.Xr rpc_xdr 3 , 479.It Fn xdr_rejected_reply Ta 480.Xr rpc_xdr 3 , 481.It Fn xdr_replymsg Ta 482.Xr rpc_xdr 3 , 483.It Fn xprt_register Ta 484.Xr rpc_svc_calls 3 , 485.It Fn xprt_unregister Ta 486.Xr rpc_svc_calls 3 , 487.El 488.Sh FILES 489.Pa /etc/netconfig 490.Sh SEE ALSO 491.Xr getnetconfig 3 , 492.Xr getnetpath 3 , 493.Xr rpc_clnt_auth 3 , 494.Xr rpc_clnt_calls 3 , 495.Xr rpc_clnt_create 3 , 496.Xr rpc_svc_calls 3 , 497.Xr rpc_svc_create 3 , 498.Xr rpc_svc_err 3 , 499.Xr rpc_svc_reg 3 , 500.Xr rpc_xdr 3 , 501.Xr rpcbind 3 , 502.Xr xdr 3 , 503.Xr netconfig 5 504