lib/libc/rpc/rpc.3

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