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