man/rpc.3t

   1 .\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4
   2 .\" Copyright 1989 AT&T
   3 .Dd May 7, 1993
   4 .Dt RPC 3
   5 .Os
   6 .Sh NAME
   7 .Nm rpc
   8 .Nd library routines for remote procedure calls
   9 .Sh LIBRARY
  10 .Lb libc
  11 .Sh SYNOPSIS
  12 .In rpc/rpc.h
  13 .In netconfig.h
  14 .Sh DESCRIPTION
  15 These
  16 routines allow C language programs to make procedure
  17 calls on other machines across a network.
  18 First, the client sends a request to the server.
  19 On receipt of the request, the server calls a dispatch routine
  20 to perform the requested service, and then sends back a reply.
  21 .Pp
  22 All
  23 RPC routines require the header
  24 .In rpc/rpc.h .
  25 Routines that take a
  26 .Vt "struct netconfig"
  27 also require that
  28 .In netconfig.h
  29 be included.
  30 .Sh Nettype
  31 Some of the high-level
  32 RPC interface routines take a
  33 .Fa nettype
  34 string as one of the arguments
  35 (for example,
  36 .Fn clnt_create ,
  37 .Fn svc_create ,
  38 .Fn rpc_reg ,
  39 .Fn rpc_call ) .
  40 This string defines a class of transports which can be used
  41 for a particular application.
  42 .Pp
  43 The
  44 .Fa nettype
  45 argument
  46 can be one of the following:
  47 .Bl -tag -width datagram_v
  48 .It netpath
  49 Choose from the transports which have been
  50 indicated by their token names in the
  51 .Ev NETPATH
  52 environment variable.
  53 .Ev NETPATH
  54 is unset or
  55 .Dv NULL ,
  56 it defaults to
  57 .Qq visible .
  58 .Qq netpath
  59 is the default
  60 .Fa nettype .
  61 .It visible
  62 Choose the transports which have the visible flag (v)
  63 set in the
  64 .Pa /etc/netconfig
  65 file.
  66 .It circuit_v
  67 This is same as
  68 .Qq visible
  69 except that it chooses only the connection oriented transports
  70 (semantics
  71 .Qq tpi_cots
  72 or
  73 .Qq tpi_cots_ord )
  74 from the entries in the
  75 .Pa /etc/netconfig
  76 file.
  77 .It datagram_v
  78 This is same as
  79 .Qq visible
  80 except that it chooses only the connectionless datagram transports
  81 (semantics
  82 .Qq tpi_clts )
  83 from the entries in the
  84 .Pa /etc/netconfig
  85 file.
  86 .It circuit_n
  87 This is same as
  88 .Qq netpath
  89 except that it chooses only the connection oriented datagram transports
  90 (semantics
  91 .Qq tpi_cots
  92 or
  93 .Qq tpi_cots_ord ) .
  94 .It datagram_n
  95 This is same as
  96 .Qq netpath
  97 except that it chooses only the connectionless datagram transports
  98 (semantics
  99 .Qq tpi_clts ) .
 100 .It udp
 101 This refers to Internet UDP, both version 4 and 6.
 102 .It tcp
 103 This refers to Internet TCP, both version 4 and 6.
 104 .El
 105 .Pp
 106 If
 107 .Fa nettype
 108 is
 109 .Dv NULL ,
 110 it defaults to
 111 .Qq netpath .
 112 The transports are tried in left to right order in the
 113 .Ev NETPATH
 114 variable or in top to down order in the
 115 .Pa /etc/netconfig
 116 file.
 117 .Sh Derived Types
 118 The 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 .Sh "Data Structures"
 128 Some of the data structures used by the
 129 RPC package are shown below.
 130 .Sh "The AUTH Structure"
 131 .Bd -literal
 132 /*
 133  * Authentication info. Opaque to client.
 134  */
 135 struct 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  */
 144 typedef 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 & 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 .Sh "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
 165 typedef 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 .Sh "The SVCXPRT structure"
 181 .Bd -literal
 182 enum xprt_stat {
 183     XPRT_DIED,
 184     XPRT_MOREREQS,
 185     XPRT_IDLE
 186 };
 187
 188 /*
 189  * Server side transport handle
 190  */
 191 typedef 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 .Sh "The svc_reg structure"
 219 .Bd -literal
 220 struct 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 .Sh  "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  */
 238 enum 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  */
 259 typedef  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  */
 266 typedef 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     u_int    x_handy;    /* extra private word */
 282 } XDR;
 283
 284 /*
 285  * The netbuf structure. This structure is defined in <xti.h> on SysV
 286  * systems, but NetBSD / FreeBSD do 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  */
 292 struct netbuf {
 293         unsigned int maxlen;
 294         unsigned int len;
 295         void *buf;
 296 };
 297
 298 /*
 299  * The format of the address 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
 304 struct t_bind {
 305         struct netbuf   addr;
 306         unsigned int    qlen;
 307 };
 308 .Ed
 309 .Sh "Index to Routines"
 310 The following table lists RPC routines and the manual reference
 311 pages on which they are described:
 312 .Pp
 313 .Bl -tag -width "authunix_create_default()" -compact
 314 .It Em "RPC Routine"
 315 .Em "Manual Reference Page"
 316 .Pp
 317 .It Fn auth_destroy
 318 .Xr rpc_clnt_auth 3
 319 .It Fn authdes_create
 320 .Xr rpc_soc 3
 321 .It Fn authnone_create
 322 .Xr rpc_clnt_auth 3
 323 .It Fn authsys_create
 324 .Xr rpc_clnt_auth 3
 325 .It Fn authsys_create_default
 326 .Xr rpc_clnt_auth 3
 327 .It Fn authunix_create
 328 .Xr rpc_soc 3
 329 .It Fn authunix_create_default
 330 .Xr rpc_soc 3
 331 .It Fn callrpc
 332 .Xr rpc_soc 3
 333 .It Fn clnt_broadcast
 334 .Xr rpc_soc 3
 335 .It Fn clnt_call
 336 .Xr rpc_clnt_calls 3
 337 .It Fn clnt_control
 338 .Xr rpc_clnt_create 3
 339 .It Fn clnt_create
 340 .Xr rpc_clnt_create 3
 341 .It Fn clnt_create_timed
 342 .Xr rpc_clnt_create 3
 343 .It Fn clnt_create_vers
 344 .Xr rpc_clnt_create 3
 345 .It Fn clnt_create_vers_timed
 346 .Xr rpc_clnt_create 3
 347 .It Fn clnt_destroy
 348 .Xr rpc_clnt_create 3
 349 .It Fn clnt_dg_create
 350 .Xr rpc_clnt_create 3
 351 .It Fn clnt_freeres
 352 .Xr rpc_clnt_calls 3
 353 .It Fn clnt_geterr
 354 .Xr rpc_clnt_calls 3
 355 .It Fn clnt_pcreateerror
 356 .Xr rpc_clnt_create 3
 357 .It Fn clnt_perrno
 358 .Xr rpc_clnt_calls 3
 359 .It Fn clnt_perror
 360 .Xr rpc_clnt_calls 3
 361 .It Fn clnt_raw_create
 362 .Xr rpc_clnt_create 3
 363 .It Fn clnt_spcreateerror
 364 .Xr rpc_clnt_create 3
 365 .It Fn clnt_sperrno
 366 .Xr rpc_clnt_calls 3
 367 .It Fn clnt_sperror
 368 .Xr rpc_clnt_calls 3
 369 .It Fn clnt_tli_create
 370 .Xr rpc_clnt_create 3
 371 .It Fn clnt_tp_create
 372 .Xr rpc_clnt_create 3
 373 .It Fn clnt_tp_create_timed
 374 .Xr rpc_clnt_create 3
 375 .It Fn clnt_udpcreate
 376 .Xr rpc_soc 3
 377 .It Fn clnt_vc_create
 378 .Xr rpc_clnt_create 3
 379 .It Fn clntraw_create
 380 .Xr rpc_soc 3
 381 .It Fn clnttcp_create
 382 .Xr rpc_soc 3
 383 .It Fn clntudp_bufcreate
 384 .Xr rpc_soc 3
 385 .It Fn get_myaddress
 386 .Xr rpc_soc 3
 387 .It Fn pmap_getmaps
 388 .Xr rpc_soc 3
 389 .It Fn pmap_getport
 390 .Xr rpc_soc 3
 391 .It Fn pmap_rmtcall
 392 .Xr rpc_soc 3
 393 .It Fn pmap_set
 394 .Xr rpc_soc 3
 395 .It Fn pmap_unset
 396 .Xr rpc_soc 3
 397 .It Fn registerrpc
 398 .Xr rpc_soc 3
 399 .It Fn rpc_broadcast
 400 .Xr rpc_clnt_calls 3
 401 .It Fn rpc_broadcast_exp
 402 .Xr rpc_clnt_calls 3
 403 .It Fn rpc_call
 404 .Xr rpc_clnt_calls 3
 405 .It Fn rpc_reg
 406 .Xr rpc_svc_calls 3
 407 .It Fn svc_create
 408 .Xr rpc_svc_create 3
 409 .It Fn svc_destroy
 410 .Xr rpc_svc_create 3
 411 .It Fn svc_dg_create
 412 .Xr rpc_svc_create 3
 413 .It Fn svc_dg_enablecache
 414 .Xr rpc_svc_calls 3
 415 .It Fn svc_fd_create
 416 .Xr rpc_svc_create 3
 417 .It Fn svc_fds
 418 .Xr rpc_soc 3
 419 .It Fn svc_freeargs
 420 .Xr rpc_svc_reg 3
 421 .It Fn svc_getargs
 422 .Xr rpc_svc_reg 3
 423 .It Fn svc_getcaller
 424 .Xr rpc_soc 3
 425 .It Fn svc_getreq
 426 .Xr rpc_soc 3
 427 .It Fn svc_getreqset
 428 .Xr rpc_svc_calls 3
 429 .It Fn svc_getrpccaller
 430 .Xr rpc_svc_calls 3
 431 .It Fn svc_kerb_reg
 432 .Xr kerberos_rpc 3
 433 .It Fn svc_raw_create
 434 .Xr rpc_svc_create 3
 435 .It Fn svc_reg
 436 .Xr rpc_svc_calls 3
 437 .It Fn svc_register
 438 .Xr rpc_soc 3
 439 .It Fn svc_run
 440 .Xr rpc_svc_reg 3
 441 .It Fn svc_sendreply
 442 .Xr rpc_svc_reg 3
 443 .It Fn svc_tli_create
 444 .Xr rpc_svc_create 3
 445 .It Fn svc_tp_create
 446 .Xr rpc_svc_create 3
 447 .It Fn svc_unreg
 448 .Xr rpc_svc_calls 3
 449 .It Fn svc_unregister
 450 .Xr rpc_soc 3
 451 .It Fn svc_vc_create
 452 .Xr rpc_svc_create 3
 453 .It Fn svcerr_auth
 454 .Xr rpc_svc_err 3
 455 .It Fn svcerr_decode
 456 .Xr rpc_svc_err 3
 457 .It Fn svcerr_noproc
 458 .Xr rpc_svc_err 3
 459 .It Fn svcerr_noprog
 460 .Xr rpc_svc_err 3
 461 .It Fn svcerr_progvers
 462 .Xr rpc_svc_err 3
 463 .It Fn svcerr_systemerr
 464 .Xr rpc_svc_err 3
 465 .It Fn svcerr_weakauth
 466 .Xr rpc_svc_err 3
 467 .It Fn svcfd_create
 468 .Xr rpc_soc 3
 469 .It Fn svcraw_create
 470 .Xr rpc_soc 3
 471 .It Fn svctcp_create
 472 .Xr rpc_soc 3
 473 .It Fn svcudp_bufcreate
 474 .Xr rpc_soc 3
 475 .It Fn svcudp_create
 476 .Xr rpc_soc 3
 477 .It Fn xdr_accepted_reply
 478 .Xr rpc_xdr 3
 479 .It Fn xdr_authsys_parms
 480 .Xr rpc_xdr 3
 481 .It Fn xdr_authunix_parms
 482 .Xr rpc_soc 3
 483 .It Fn xdr_callhdr
 484 .Xr rpc_xdr 3
 485 .It Fn xdr_callmsg
 486 .Xr rpc_xdr 3
 487 .It Fn xdr_opaque_auth
 488 .Xr rpc_xdr 3
 489 .It Fn xdr_rejected_reply
 490 .Xr rpc_xdr 3
 491 .It Fn xdr_replymsg
 492 .Xr rpc_xdr 3
 493 .It Fn xprt_register
 494 .Xr rpc_svc_calls 3
 495 .It Fn xprt_unregister
 496 .Xr rpc_svc_calls 3
 497 .El
 498 .Sh FILES
 499 .Bl -tag -width /etc/netconfig
 500 .It Pa /etc/netconfig
 501 .El
 502 .Sh SEE ALSO
 503 .Xr getnetconfig 3 ,
 504 .Xr getnetpath 3 ,
 505 .Xr rpcbind 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 xdr 3 ,
 515 .Xr netconfig 5