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