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