1.\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4 2.\" Copyright 1989 AT&T 3.\" $NetBSD: rpc.3,v 1.24 2012/05/13 15:47:38 wiz 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.Fa netconfig 28structure also require that 29.In netconfig.h 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.Fa 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 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.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_req 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 */ 258typedef bool_t (*xdrproc_t)(XDR *, const void *); 259 260/* 261 * The XDR handle. 262 * Contains operation which is being applied to the stream, 263 * an operations vector for the particular implementation 264 */ 265typedef struct { 266 enum xdr_op x_op; /* operation; fast additional param */ 267 struct xdr_ops { 268 bool_t (*x_getlong)(); /* get a long from underlying stream */ 269 bool_t (*x_putlong)(); /* put a long to underlying stream */ 270 bool_t (*x_getbytes)(); /* get bytes from underlying stream */ 271 bool_t (*x_putbytes)(); /* put bytes to underlying stream */ 272 u_int (*x_getpostn)(); /* returns bytes off from beginning */ 273 bool_t (*x_setpostn)(); /* lets you reposition the stream */ 274 long * (*x_inline)(); /* buf quick ptr to buffered data */ 275 void (*x_destroy)(); /* free privates of this xdr_stream */ 276 } *x_ops; 277 caddr_t x_public; /* users' data */ 278 caddr_t x_private; /* pointer to private data */ 279 caddr_t x_base; /* private used for position info */ 280 int x_handy; /* extra private word */ 281} XDR; 282 283/* 284 * The netbuf structure. This structure is defined in \*[Lt]xti.h\*[Gt] on SysV 285 * systems, but NetBSD does not use XTI. 286 * 287 * Usually, buf will point to a struct sockaddr, and len and maxlen 288 * will contain the length and maximum length of that socket address, 289 * respectively. 290 */ 291struct netbuf { 292 unsigned int maxlen; 293 unsigned int len; 294 void *buf; 295}; 296 297/* 298 * The format of the address and options arguments of the XTI t_bind call. 299 * Only provided for compatibility, it should not be used other than 300 * as an argument to svc_tli_create(). 301 */ 302 303struct t_bind { 304 struct netbuf addr; 305 unsigned int qlen; 306}; 307.Ed 308.Ss Index to Routines 309The following table lists RPC routines and the manual reference 310pages on which they are described: 311.Bl -column "authunix_create_default()" "rpc_clnt_create(3)" 312.It Em "RPC Routine" Ta Em "Manual Reference Page" 313.Pp 314.It Fn auth_destroy Ta Xr rpc_clnt_auth 3 315.It Fn authdes_create Ta Xr rpc_soc 3 316.It Fn authnone_create Ta Xr rpc_clnt_auth 3 317.It Fn authsys_create Ta Xr rpc_clnt_auth 3 318.It Fn authsys_create_default Ta Xr rpc_clnt_auth 3 319.It Fn authunix_create Ta Xr rpc_soc 3 320.It Fn authunix_create_default Ta Xr rpc_soc 3 321.It Fn callrpc Ta Xr rpc_soc 3 322.It Fn clnt_broadcast Ta Xr rpc_soc 3 323.It Fn clnt_call Ta Xr rpc_clnt_calls 3 324.It Fn clnt_control Ta Xr rpc_clnt_create 3 325.It Fn clnt_create Ta Xr rpc_clnt_create 3 326.It Fn clnt_destroy Ta Xr rpc_clnt_create 3 327.It Fn clnt_dg_create Ta Xr rpc_clnt_create 3 328.It Fn clnt_freeres Ta Xr rpc_clnt_calls 3 329.It Fn clnt_geterr Ta Xr rpc_clnt_calls 3 330.It Fn clnt_pcreateerror Ta Xr rpc_clnt_create 3 331.It Fn clnt_perrno Ta Xr rpc_clnt_calls 3 332.It Fn clnt_perror Ta Xr rpc_clnt_calls 3 333.It Fn clnt_raw_create Ta Xr rpc_clnt_create 3 334.It Fn clnt_spcreateerror Ta Xr rpc_clnt_create 3 335.It Fn clnt_sperrno Ta Xr rpc_clnt_calls 3 336.It Fn clnt_sperror Ta Xr rpc_clnt_calls 3 337.It Fn clnt_tli_create Ta Xr rpc_clnt_create 3 338.It Fn clnt_tp_create Ta Xr rpc_clnt_create 3 339.It Fn clnt_udpcreate Ta Xr rpc_soc 3 340.It Fn clnt_vc_create Ta Xr rpc_clnt_create 3 341.It Fn clntraw_create Ta Xr rpc_soc 3 342.It Fn clnttcp_create Ta Xr rpc_soc 3 343.It Fn clntudp_bufcreate Ta Xr rpc_soc 3 344.It Fn get_myaddress Ta Xr rpc_soc 3 345.It Fn pmap_getmaps Ta Xr rpc_soc 3 346.It Fn pmap_getport Ta Xr rpc_soc 3 347.It Fn pmap_rmtcall Ta Xr rpc_soc 3 348.It Fn pmap_set Ta Xr rpc_soc 3 349.It Fn pmap_unset Ta Xr rpc_soc 3 350.It Fn registerrpc Ta Xr rpc_soc 3 351.It Fn rpc_broadcast Ta Xr rpc_clnt_calls 3 352.It Fn rpc_broadcast_exp Ta Xr rpc_clnt_calls 3 353.It Fn rpc_call Ta Xr rpc_clnt_calls 3 354.It Fn rpc_reg Ta Xr rpc_svc_calls 3 355.It Fn svc_create Ta Xr rpc_svc_create 3 356.It Fn svc_destroy Ta Xr rpc_svc_create 3 357.It Fn svc_dg_create Ta Xr rpc_svc_create 3 358.It Fn svc_dg_enablecache Ta Xr rpc_svc_calls 3 359.It Fn svc_fd_create Ta Xr rpc_svc_create 3 360.It Fn svc_fds Ta Xr rpc_soc 3 361.It Fn svc_freeargs Ta Xr rpc_svc_reg 3 362.It Fn svc_getargs Ta Xr rpc_svc_reg 3 363.It Fn svc_getcaller Ta Xr rpc_soc 3 364.It Fn svc_getreq Ta Xr rpc_soc 3 365.It Fn svc_getreqset Ta Xr rpc_svc_calls 3 366.It Fn svc_getrpccaller Ta Xr rpc_svc_calls 3 367.It Fn svc_kerb_reg Ta Xr kerberos_rpc 3 368.It Fn svc_raw_create Ta Xr rpc_svc_create 3 369.It Fn svc_reg Ta Xr rpc_svc_calls 3 370.It Fn svc_register Ta Xr rpc_soc 3 371.It Fn svc_run Ta Xr rpc_svc_reg 3 372.It Fn svc_sendreply Ta Xr rpc_svc_reg 3 373.It Fn svc_tli_create Ta Xr rpc_svc_create 3 374.It Fn svc_tp_create Ta Xr rpc_svc_create 3 375.It Fn svc_unreg Ta Xr rpc_svc_calls 3 376.It Fn svc_unregister Ta Xr rpc_soc 3 377.It Fn svc_vc_create Ta Xr rpc_svc_create 3 378.It Fn svcerr_auth Ta Xr rpc_svc_err 3 379.It Fn svcerr_decode Ta Xr rpc_svc_err 3 380.It Fn svcerr_noproc Ta Xr rpc_svc_err 3 381.It Fn svcerr_noprog Ta Xr rpc_svc_err 3 382.It Fn svcerr_progvers Ta Xr rpc_svc_err 3 383.It Fn svcerr_systemerr Ta Xr rpc_svc_err 3 384.It Fn svcerr_weakauth Ta Xr rpc_svc_err 3 385.It Fn svcfd_create Ta Xr rpc_soc 3 386.It Fn svcraw_create Ta Xr rpc_soc 3 387.It Fn svctcp_create Ta Xr rpc_soc 3 388.It Fn svcudp_bufcreate Ta Xr rpc_soc 3 389.It Fn svcudp_create Ta Xr rpc_soc 3 390.It Fn xdr_accepted_reply Ta Xr rpc_xdr 3 391.It Fn xdr_authsys_parms Ta Xr rpc_xdr 3 392.It Fn xdr_authunix_parms Ta Xr rpc_soc 3 393.It Fn xdr_callhdr Ta Xr rpc_xdr 3 394.It Fn xdr_callmsg Ta Xr rpc_xdr 3 395.It Fn xdr_opaque_auth Ta Xr rpc_xdr 3 396.It Fn xdr_rejected_reply Ta Xr rpc_xdr 3 397.It Fn xdr_replymsg Ta Xr rpc_xdr 3 398.It Fn xprt_register Ta Xr rpc_svc_calls 3 399.It Fn xprt_unregister Ta Xr rpc_svc_calls 3 400.El 401.Sh FILES 402.Pa /etc/netconfig 403.Sh SEE ALSO 404.Xr getnetconfig 3 , 405.Xr getnetpath 3 , 406.Xr rpc_clnt_auth 3 , 407.Xr rpc_clnt_calls 3 , 408.Xr rpc_clnt_create 3 , 409.Xr rpc_svc_calls 3 , 410.Xr rpc_svc_create 3 , 411.Xr rpc_svc_err 3 , 412.Xr rpc_svc_reg 3 , 413.Xr rpc_xdr 3 , 414.Xr rpcbind 3 , 415.Xr xdr 3 , 416.Xr netconfig 5 417