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.22 2010/03/22 19:30:54 joerg 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
  16 These
  17 routines allow C language programs to make procedure
  18 calls on other machines across a network.
  19 First, the client sends a request to the server.
  20 On receipt of the request, the server calls a dispatch routine
  21 to perform the requested service, and then sends back a reply.
  22 .Pp
  23 All
  24 RPC routines require the header
  25 .In rpc/rpc.h .
  26 Routines that take a
  27 .Fa netconfig
  28 structure also require that
  29 .In netconfig.h
  30 be included.
  31 .Ss Nettype
  32 Some of the high-level
  33 RPC interface routines take a
  34 .Fa nettype
  35 string as one of the parameters
  36 (for example,
  37 .Fn clnt_create ,
  38 .Fn svc_create ,
  39 .Fn rpc_reg ,
  40 .Fn rpc_call .
  41 This string defines a class of transports which can be used
  42 for a particular application.
  43 .Pp
  44 .Fa nettype
  45 can be one of the following:
  46 .Bl -tag -width datagram_v
  47 .It netpath
  48 Choose from the transports which have been
  49 indicated by their token names in the
  50 .Ev NETPATH
  51 environment variable.
  52 If
  53 .Ev NETPATH
  54 is unset or
  55 .Dv NULL
  56 , it defaults to
  57 .Fa visible .
  58 .Fa 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 .Fa visible
  69 except that it chooses only the connection oriented transports
  70 (semantics
  71 .Fa tpi_cots
  72 or
  73 .Fa 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 .Fa visible
  80 except that it chooses only the connectionless datagram transports
  81 (semantics
  82 .Fa tpi_clts )
  83 from the entries in the
  84 .Pa /etc/netconfig
  85 file.
  86 .It circuit_n
  87 This is same as
  88 .Fa netpath
  89 except that it chooses only the connection oriented datagram transports
  90 (semantics
  91 .Fa tpi_cots
  92 or
  93 .Fa tpi_cots_ord ) .
  94 .It datagram_n
  95 This is same as
  96 .Fa netpath
  97 except that it chooses only the connectionless datagram transports
  98 (semantics
  99 .Fa 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 .Fa 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 .Ss Derived Types
 118 The 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
 128 Some of the data structures used by the
 129 RPC package are shown below.
 130 .Ss 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 \*[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
 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 .Ss 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 .Ss The svc_req 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 .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  */
 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     int    x_handy;    /* extra private word */
 282 } XDR;
 283
 284 /*
 285  * The netbuf structure. This structure is defined in \*[Lt]xti.h\*[Gt] on SysV
 286  * systems, but NetBSD does 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 .Ss Index to Routines
 310 The following table lists RPC routines and the manual reference
 311 pages on which they are described:
 312 .Bl -column "authunix_create_default()" "rpc_clnt_create(3)"
 313 .It Em "RPC Routine" Ta Em "Manual Reference Page"
 314 .Pp
 315 .It Fn auth_destroy Ta Xr rpc_clnt_auth 3 ,
 316 .It Fn authdes_create Ta Xr rpc_soc 3 ,
 317 .It Fn authnone_create Ta Xr rpc_clnt_auth 3 ,
 318 .It Fn authsys_create Ta Xr rpc_clnt_auth 3 ,
 319 .It Fn authsys_create_default Ta Xr rpc_clnt_auth 3 ,
 320 .It Fn authunix_create Ta Xr rpc_soc 3 ,
 321 .It Fn authunix_create_default Ta Xr rpc_soc 3 ,
 322 .It Fn callrpc Ta Xr rpc_soc 3 ,
 323 .It Fn clnt_broadcast Ta Xr rpc_soc 3 ,
 324 .It Fn clnt_call Ta Xr rpc_clnt_calls 3 ,
 325 .It Fn clnt_control Ta Xr rpc_clnt_create 3 ,
 326 .It Fn clnt_create Ta Xr rpc_clnt_create 3 ,
 327 .It Fn clnt_destroy Ta Xr rpc_clnt_create 3 ,
 328 .It Fn clnt_dg_create Ta Xr rpc_clnt_create 3 ,
 329 .It Fn clnt_freeres Ta Xr rpc_clnt_calls 3 ,
 330 .It Fn clnt_geterr Ta Xr rpc_clnt_calls 3 ,
 331 .It Fn clnt_pcreateerror Ta Xr rpc_clnt_create 3 ,
 332 .It Fn clnt_perrno Ta Xr rpc_clnt_calls 3 ,
 333 .It Fn clnt_perror Ta Xr rpc_clnt_calls 3 ,
 334 .It Fn clnt_raw_create Ta Xr rpc_clnt_create 3 ,
 335 .It Fn clnt_spcreateerror Ta Xr rpc_clnt_create 3 ,
 336 .It Fn clnt_sperrno Ta Xr rpc_clnt_calls 3 ,
 337 .It Fn clnt_sperror Ta Xr rpc_clnt_calls 3 ,
 338 .It Fn clnt_tli_create Ta Xr rpc_clnt_create 3 ,
 339 .It Fn clnt_tp_create Ta Xr rpc_clnt_create 3 ,
 340 .It Fn clnt_udpcreate Ta Xr rpc_soc 3 ,
 341 .It Fn clnt_vc_create Ta Xr rpc_clnt_create 3 ,
 342 .It Fn clntraw_create Ta Xr rpc_soc 3 ,
 343 .It Fn clnttcp_create Ta Xr rpc_soc 3 ,
 344 .It Fn clntudp_bufcreate Ta Xr rpc_soc 3 ,
 345 .It Fn get_myaddress Ta Xr rpc_soc 3 ,
 346 .It Fn pmap_getmaps Ta Xr rpc_soc 3 ,
 347 .It Fn pmap_getport Ta Xr rpc_soc 3 ,
 348 .It Fn pmap_rmtcall Ta Xr rpc_soc 3 ,
 349 .It Fn pmap_set Ta Xr rpc_soc 3 ,
 350 .It Fn pmap_unset Ta Xr rpc_soc 3 ,
 351 .It Fn registerrpc Ta Xr rpc_soc 3 ,
 352 .It Fn rpc_broadcast Ta Xr rpc_clnt_calls 3 ,
 353 .It Fn rpc_broadcast_exp Ta Xr rpc_clnt_calls 3 ,
 354 .It Fn rpc_call Ta Xr rpc_clnt_calls 3 ,
 355 .It Fn rpc_reg Ta Xr rpc_svc_calls 3 ,
 356 .It Fn svc_create Ta Xr rpc_svc_create 3 ,
 357 .It Fn svc_destroy Ta Xr rpc_svc_create 3 ,
 358 .It Fn svc_dg_create Ta Xr rpc_svc_create 3 ,
 359 .It Fn svc_dg_enablecache Ta Xr rpc_svc_calls 3 ,
 360 .It Fn svc_fd_create Ta Xr rpc_svc_create 3 ,
 361 .It Fn svc_fds Ta Xr rpc_soc 3 ,
 362 .It Fn svc_freeargs Ta Xr rpc_svc_reg 3 ,
 363 .It Fn svc_getargs Ta Xr rpc_svc_reg 3 ,
 364 .It Fn svc_getcaller Ta Xr rpc_soc 3 ,
 365 .It Fn svc_getreq Ta Xr rpc_soc 3 ,
 366 .It Fn svc_getreqset Ta Xr rpc_svc_calls 3 ,
 367 .It Fn svc_getrpccaller Ta Xr rpc_svc_calls 3 ,
 368 .It Fn svc_kerb_reg Ta Xr kerberos_rpc 3 ,
 369 .It Fn svc_raw_create Ta Xr rpc_svc_create 3 ,
 370 .It Fn svc_reg Ta Xr rpc_svc_calls 3 ,
 371 .It Fn svc_register Ta Xr rpc_soc 3 ,
 372 .It Fn svc_run Ta Xr rpc_svc_reg 3 ,
 373 .It Fn svc_sendreply Ta Xr rpc_svc_reg 3 ,
 374 .It Fn svc_tli_create Ta Xr rpc_svc_create 3 ,
 375 .It Fn svc_tp_create Ta Xr rpc_svc_create 3 ,
 376 .It Fn svc_unreg Ta Xr rpc_svc_calls 3 ,
 377 .It Fn svc_unregister Ta  Xr rpc_soc 3 ,
 378 .It Fn svc_vc_create Ta Xr rpc_svc_create 3 ,
 379 .It Fn svcerr_auth Ta Xr rpc_svc_err 3 ,
 380 .It Fn svcerr_decode Ta Xr rpc_svc_err 3 ,
 381 .It Fn svcerr_noproc Ta Xr rpc_svc_err 3 ,
 382 .It Fn svcerr_noprog Ta Xr rpc_svc_err 3 ,
 383 .It Fn svcerr_progvers Ta Xr rpc_svc_err 3 ,
 384 .It Fn svcerr_systemerr Ta Xr rpc_svc_err 3 ,
 385 .It Fn svcerr_weakauth Ta Xr rpc_svc_err 3 ,
 386 .It Fn svcfd_create Ta Xr rpc_soc 3 ,
 387 .It Fn svcraw_create Ta Xr rpc_soc 3 ,
 388 .It Fn svctcp_create Ta Xr rpc_soc 3 ,
 389 .It Fn svcudp_bufcreate Ta Xr rpc_soc 3 ,
 390 .It Fn svcudp_create Ta Xr rpc_soc 3 ,
 391 .It Fn xdr_accepted_reply Ta Xr rpc_xdr 3 ,
 392 .It Fn xdr_authsys_parms Ta Xr rpc_xdr 3 ,
 393 .It Fn xdr_authunix_parms Ta Xr rpc_soc 3 ,
 394 .It Fn xdr_callhdr Ta Xr rpc_xdr 3 ,
 395 .It Fn xdr_callmsg Ta Xr rpc_xdr 3 ,
 396 .It Fn xdr_opaque_auth Ta Xr rpc_xdr 3 ,
 397 .It Fn xdr_rejected_reply Ta Xr rpc_xdr 3 ,
 398 .It Fn xdr_replymsg Ta Xr rpc_xdr 3 ,
 399 .It Fn xprt_register Ta Xr rpc_svc_calls 3 ,
 400 .It Fn xprt_unregister Ta Xr rpc_svc_calls 3 ,
 401 .El
 402 .Sh FILES
 403 .Pa /etc/netconfig
 404 .Sh SEE ALSO
 405 .Xr getnetconfig 3 ,
 406 .Xr getnetpath 3 ,
 407 .Xr rpc_clnt_auth 3 ,
 408 .Xr rpc_clnt_calls 3 ,
 409 .Xr rpc_clnt_create 3 ,
 410 .Xr rpc_svc_calls 3 ,
 411 .Xr rpc_svc_create 3 ,
 412 .Xr rpc_svc_err 3 ,
 413 .Xr rpc_svc_reg 3 ,
 414 .Xr rpc_xdr 3 ,
 415 .Xr rpcbind 3 ,
 416 .Xr xdr 3 ,
 417 .Xr netconfig 5