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