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