Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
rpc(3NSL)	     Networking	Services Library Functions	     rpc(3NSL)

NAME
       rpc - library routines for remote procedure calls

SYNOPSIS
       cc [ flag ... ] file ...	-lnsl [	library	... ]
       #include	<rpc/rpc.h>
       #include	<netconfig.h>

DESCRIPTION
       These  routines	allow  C  language programs to make procedure calls on
       other machines across a network.	First, the client sends	a  request  to
       the server. On receipt of the request, the server calls a dispatch rou-
       tine to perform the requested service, and then sends back a reply.

       All RPC routines	require	the header <rpc/rpc.h>.	Routines that  take  a
       netconfig structure also	require	that <netconfig.h> be included.	Appli-
       cations using  RPC and  XDR routines should be linked with  the	libnsl
       library.

   Multithread Considerations
       In the case of multithreaded applications, the -mt option must be spec-
       ified on	the command line at compilation	time to	enable	a  thread-spe-
       cific   version	 of  rpc_createerr().  See  rpc_clnt_create(3NSL)  and
       threads(3THR).

       When used in multithreaded applications,	client-side routines  are  MT-
       Safe.  CLIENT  handles  can be shared between threads; however, in this
       implementation, requests	by different threads are serialized (that  is,
       the first request will receive its results before the second request is
       sent). See rpc_clnt_create(3NSL).

       When used in multithreaded applications,	server-side routines are  usu-
       ally Unsafe. In this implementation the service transport handle, SVCX-
       PRT contains a single data area for decoding arguments and encoding re-
       sults.	See  rpc_svc_create(3NSL). Therefore, this structure cannot be
       freely shared between threads that call functions that do  this.	  Rou-
       tines that are affected by this restriction are marked as unsafe	for MT
       applications. See rpc_svc_calls(3NSL).

   Nettyp
       Some of the high-level RPC interface routines take a nettype string  as
       one  of	the  parameters	 (for  example,	 clnt_create(),	 svc_create(),
       rpc_reg(), rpc_call()).	This string  defines  a	 class	of  transports
       which can be used for a particular application.

       nettype can be one of the following:

       netpath
	     Choose from the transports	which have been	indicated by their to-
	     ken names in the NETPATH environment variable. If NETPATH is  un-
	     set  or NULL, it defaults to visible. netpath is the default net-
	     type.

       visible
	     Choose the	transports which have the visible flag (v) set in  the
	     /etc/netconfig file.

       circuit_v
	     This  is  same as visible except that it chooses only the connec-
	     tion oriented transports  (semantics  tpi_cots  or	 tpi_cots_ord)
	     from the entries in the /etc/netconfig file.

       datagram_v
	     This  is  same as visible except that it chooses only the connec-
	     tionless datagram transports (semantics tpi_clts)	from  the  en-
	     tries in the /etc/netconfig file.

       circuit_n
	     This  is  same as netpath except that it chooses only the connec-
	     tion  oriented  datagram  transports   (semantics	 tpi_cots   or
	     tpi_cots_ord).

       datagram_n
	     This  is  same as netpath except that it chooses only the connec-
	     tionless datagram transports (semantics tpi_clts).

       udp   This refers to Internet UDP.

       tcp   This refers to Internet TCP.

       If  nettype is  NULL, it	defaults to netpath. The transports are	 tried
       in  left	to right order in the NETPATH variable or in top to down order
       in the /etc/netconfig file.

   Derived Types
       In a 64-bit environment,	the derived types are defined as follows:

       typedef		    uint32_t		  rpcprog_t;
       typedef		    uint32_t		  rpcvers_t;
       typedef		    uint32_t		  rpcproc_t;
       typedef		    uint32_t		  rpcprot_t;
       typedef		    uint32_t		  rpcport_t;
       typedef		    int32_t		  rpc_inline_t;

       In a 32-bit environment,	the derived types are defined as follows:

       typedef		    unsigned long	  rpcprog_t;
       typedef		    unsigned long	  rpcvers_t;
       typedef		    unsigned long	  rpcproc_t;
       typedef		    unsigned long	  rpcprot_t;
       typedef		    unsigned long	  rpcport_t;
       typedef		    long		  rpc_inline_t;

   Data	Structures
       Some of the data	structures used	by the RPC package are shown below.

   The AUTH Structure
       union  des_block	 {
	       struct  {
	       u_int32	high;
	       u_int32	low;
	       }  key;
       char  c[8];
       };
       typedef	union  des_block  des_block;
       extern  bool_t  xdr_des_block();
       /*
	*  Authentication  info.  Opaque  to  client.
       */
       struct  opaque_auth  {
	       enum_t oa_flavor;       /* flavor of auth */
	       caddr_t oa_base;	       /* address of more auth stuff */
	       uint_t oa_length;       /* not to exceed	MAX_AUTH_BYTES */
       };
       /*
	* Auth handle, interface to client side	 authenticators.
       */
	typedef	 struct	 {
	       struct opaque_auth ah_cred;
	       struct opaque_auth ah_verf;
	       union  des_block	ah_key;
	       struct  auth_ops	 {
		       void(*ah_nextverf)();
		       int(*ah_marshal)();     /* nextverf & serialize */
		       int(*ah_validate)();    /* validate verifier */
		       int(*ah_refresh)();     /* refresh credentials */
		       void(*ah_destroy)();    /* destroy this structure */
	       }  *ah_ops;
	       caddr_t	ah_private;
       }  AUTH;

   The CLIENT Structure
       /*
	*  Client  rpc	handle.
	*  Created  by	individual  implementations.
	* Client is responsible	for initializing auth.
	*/
	       typedef	struct	{
	       AUTH    *cl_auth;       /* authenticator	*/
	       struct clnt_ops {
		     enum clnt_stat (*cl_call)();      /* call remote procedure	*/
		     void (*cl_abort)();	       /* abort	a call */
		     void (*cl_geterr)();	    /* get specific error code */
		     bool_t (*cl_freeres)();	       /* frees	results	*/
		     void (*cl_destroy)();	     /*	destroy	this structure */
		     bool_t (*cl_control)();	       /* the ioctl() of rpc */
		     int (*cl_settimers)();	       /* set rpc level	timers */
		    } *cl_ops;
		    caddr_t    cl_private;		       /* private stuff	*/
		    char       *cl_netid;		 /* network identifier */
		    char       *cl_tp;			       /* device name */
       }  CLIENT;

   The SVCXPRT Structure
       enum  xprt_stat	{
       XPRT_DIED,
       XPRT_MOREREQS,
       XPRT_IDLE
       };
       /*
	*  Server  side	 transport  handle
	*/
       typedef	struct	{
	       int     xp_fd;		       /* file descriptor for the
	       ushort_t	xp_port;		/* obsolete */
	       struct xp_ops {
		  bool_t (*xp_recv)(); /* receive incoming requests */
		  enum xprt_stat (*xp_stat)(); /* get transport	status */
		  bool_t (*xp_getargs)();      /* get arguments	*/
		  bool_t (*xp_reply)();	       /* send reply */
		  bool_t (*xp_freeargs)();     /* free mem allocated
							   for args */
		  void (*xp_destroy)();	       /* destroy this struct */
	       } *xp_ops;
	       int xp_addrlen;		       /* length of remote addr.
					       Obsolete	*/
	       char *xp_tp;		       /* transport provider device
					       name */
	       char *xp_netid;		       /* network identifier */
	       struct netbuf xp_ltaddr;	       /* local	transport address */
	       struct netbuf xp_rtaddr;	       /* remote transport address */
	       char xp_raddr[16];	       /* remote address. Obsolete */
	       struct opaque_auth xp_verf;     /* raw response verifier	*/
	       caddr_t xp_p1;		       /* private: for use
					       by svc ops */
	       caddr_t xp_p2;		       /* private: for use
					       by svc ops */
	       caddr_t xp_p3;		       /* private: for use
					       by svc lib */
	       int xp_type		       /* transport type */
       }  SVCXPRT;

   The svc_reg Structure
       struct  svc_req	{
	  rpcprog_t rq_prog;	      /* service program number	*/
	  rpcvers_t rq_vers;	      /* service protocol version */
	  rpcproc_t rq_proc;	      /* the desired procedure */
	  struct opaque_auth rq_cred; /* raw creds from	the wire */
	  caddr_t rq_clntcred;	      /* read only cooked cred */
	  SVCXPRT *rq_xprt;	      /* associated transport */

       };

   The XDR Structure
       /*
	* XDR operations.
	* XDR_ENCODE causes the	type to	be encoded into	the stream.
	* XDR_DECODE causes the	type to	be extracted from the stream.
	* XDR_FREE can be used to release the space allocated by an XDR_DECODE
	* request.
	*/
       enum xdr_op {
	   XDR_ENCODE=0,
	   XDR_DECODE=1,
	   XDR_FREE=2
       };
       /*
	* This is the number of	bytes per unit of external data.
	*/
       #define BYTES_PER_XDR_UNIT	       (4)
       #define RNDUP(x)	 ((((x)	+ BYTES_PER_XDR_UNIT - 1) /
			  BYTES_PER_XDR_UNIT) \	* BYTES_PER_XDR_UNIT)
       /*
	* A xdrproc_t exists for each data type	which is to be encoded or
	* decoded.  The	second argument	to the xdrproc_t is a pointer to
	* an opaque pointer.  The opaque pointer generally points to a
	* structure of the data	type to	be decoded.  If	this points to 0,
	* then the type	routines should	allocate dynamic storage of the
	* appropriate size and return it.
	* bool_t  (*xdrproc_t)(XDR *, caddr_t *);
	*/
       typedef	bool_t (*xdrproc_t)();
       /*
	* The XDR handle.
	* Contains operation which is being applied to the stream,
	* an operations	vector for the particular implementation
	*/
       typedef struct {

       enum xdr_op x_op;    /* operation; fast additional param	*/
       struct  xdr_ops	{

       bool_t	    (*x_getlong)();	 /* get	long from underlying stream */
       bool_t	    (*x_putlong)();	 /* put	long to	underlying stream */
       bool_t	    (*x_getbytes)();	  /* get bytes from underlying stream */
       bool_t	    (*x_putbytes)();	 /* put	bytes to underlying stream */
       uint_t	    (*x_getpostn)();	 /* returns bytes off from beginning */
       bool_t	    (*x_setpostn)();	 /* reposition the stream */
       rpc_inline_t *(*x_inline)();	 /* buf	quick ptr to buffered data */
       void	    (*x_destroy)();	 /* free privates of this xdr_stream */
       bool_t	    (*x_control)();	 /* changed/retrieve client object info*/
       bool_t	    (*x_getint32)();	 /* get	int from underlying stream */
       bool_t	    (*x_putint32)();	 /* put	int to underlying stream */

       } *x_ops;

       caddr_t	    x_public;		  /* users' data */
       caddr_t	    x_priv		  /* pointer to	private	data */
       caddr_t	    x_base;		  /* private used for position info */
       int	    x_handy;		  /* extra private word	*/
       XDR;

   Index to Routines
       The following table lists  RPC routines and the manual reference	 pages
       on which	they are described:

       RPC Routine
	     Manual Reference Page

       auth_destroy
	      rpc_clnt_auth(3NSL)

       authdes_create
	     rpc_soc(3NSL)

       authdes_getucred
	     secure_rpc(3NSL)

       authdes_seccreate
	     secure_rpc(3NSL)

       authnone_create
	     rpc_clnt_auth(3NSL)

       authsys_create
	     rpc_clnt_auth(3NSL)

       authsys_create_default
	     rpc_clnt_auth(3NSL)

       authunix_create
	     rpc_soc(3NSL)

       authunix_create_default
	     rpc_soc(3NSL)

       callrpc
	     rpc_soc(3NSL)

       clnt_broadcast
	     rpc_soc(3NSL)

       clnt_call
	     rpc_clnt_calls(3NSL)

       clnt_control
	     rpc_clnt_create(3NSL)

       clnt_create
	     rpc_clnt_create(3NSL)

       clnt_destroy
	     rpc_clnt_create(3NSL)

       clnt_dg_create
	     rpc_clnt_create(3NSL)

       clnt_freeres
	     rpc_clnt_calls(3NSL)

       clnt_geterr
	     rpc_clnt_calls(3NSL)

       clnt_pcreateerror
	     rpc_clnt_create(3NSL)

       clnt_perrno
	     rpc_clnt_calls(3NSL)

       clnt_perror
	     rpc_clnt_calls(3NSL)

       clnt_raw_create
	     rpc_clnt_create(3NSL)

       clnt_spcreateerror
	     rpc_clnt_create(3NSL)

       clnt_sperrno
	     rpc_clnt_calls(3NSL)

       clnt_sperror
	     rpc_clnt_calls(3NSL)

       clnt_tli_create
	     rpc_clnt_create(3NSL)

       clnt_tp_create
	     rpc_clnt_create(3NSL)

       clnt_udpcreate
	     rpc_soc(3NSL)

       clnt_vc_create
	     rpc_clnt_create(3NSL)

       clntraw_create
	     rpc_soc(3NSL)

       clnttcp_create
	     rpc_soc(3NSL)

       clntudp_bufcreate
	     rpc_soc(3NSL)

       get_myaddress
	     rpc_soc(3NSL)

       getnetname
	     secure_rpc(3NSL)

       host2netname
	     secure_rpc(3NSL)

       key_decryptsession
	     secure_rpc(3NSL)

       key_encryptsession
	     secure_rpc(3NSL)

       key_gendes
	     secure_rpc(3NSL)

       key_setsecret
	     secure_rpc(3NSL)

       netname2host
	     secure_rpc(3NSL)

       netname2user
	     secure_rpc(3NSL)

       pmap_getmaps
	     rpc_soc(3NSL)

       pmap_getport
	     rpc_soc(3NSL)

       pmap_rmtcall
	     rpc_soc(3NSL)

       pmap_set
	     rpc_soc(3NSL)

       pmap_unset
	     rpc_soc(3NSL)

       rac_drop
	     rpc_rac(3RAC)

       rac_poll
	     rpc_rac(3RAC)

       rac_recv
	     rpc_rac(3RAC)

       rac_send
	     rpc_rac(3RAC)

       registerrpc
	     rpc_soc(3NSL)

       rpc_broadcast
	     rpc_clnt_calls(3NSL)

       rpc_broadcast_exp
	     rpc_clnt_calls(3NSL)

       rpc_call
	     rpc_clnt_calls(3NSL)

       rpc_reg
	     rpc_svc_calls(3NSL)

       svc_create
	     rpc_svc_create(3NSL)

       svc_destroy
	     rpc_svc_create(3NSL)

       svc_dg_create
	     rpc_svc_create(3NSL)

       svc_dg_enablecache
	     rpc_svc_calls(3NSL)

       svc_fd_create
	     rpc_svc_create(3NSL)

       svc_fds
	     rpc_soc(3NSL)

       svc_freeargs
	     rpc_svc_reg(3NSL)

       svc_getargs
	     rpc_svc_reg(3NSL)

       svc_getcaller
	     rpc_soc(3NSL)

       svc_getreq
	     rpc_soc(3NSL)

       svc_getreqset
	     rpc_svc_calls(3NSL)

       svc_getrpccaller
	     rpc_svc_calls(3NSL)

       svc_raw_create
	     rpc_svc_create(3NSL)

       svc_reg
	     rpc_svc_calls(3NSL)

       svc_register
	     rpc_soc(3NSL)

       svc_run
	     rpc_svc_reg(3NSL)

       svc_sendreply
	     rpc_svc_reg(3NSL)

       svc_tli_create
	     rpc_svc_create(3NSL)

       svc_tp_create
	     rpc_svc_create(3NSL)

       svc_unreg
	     rpc_svc_calls(3NSL)

       svc_unregister
	     rpc_soc(3NSL)

       svc_vc_create
	     rpc_svc_create(3NSL)

       svcerr_auth
	     rpc_svc_err(3NSL)

       svcerr_decode
	     rpc_svc_err(3NSL)

       svcerr_noproc
	     rpc_svc_err(3NSL)

       svcerr_noprog
	     rpc_svc_err(3NSL)

       svcerr_progvers
	     rpc_svc_err(3NSL)

       svcerr_systemerr
	     rpc_svc_err(3NSL)

       svcerr_weakauth
	     rpc_svc_err(3NSL)

       svcfd_create
	     rpc_soc(3NSL)

       svcraw_create
	     rpc_soc(3NSL)

       svctcp_create
	     rpc_soc(3NSL)

       svcudp_bufcreate
	     rpc_soc(3NSL)

       svcudp_create
	     rpc_soc(3NSL)

       user2netname
	     secure_rpc(3NSL)

       xdr_accepted_reply
	     rpc_xdr(3NSL)

       xdr_authsys_parms
	     rpc_xdr(3NSL)

       xdr_authunix_parms
	     rpc_soc(3NSL)

       xdr_callhdr
	     rpc_xdr(3NSL)

       xdr_callmsg
	     rpc_xdr(3NSL)

       xdr_opaque_auth
	     rpc_xdr(3NSL)

       xdr_rejected_reply
	     rpc_xdr(3NSL)

       xdr_replymsg
	     rpc_xdr(3NSL)

       xprt_register
	     rpc_svc_calls(3NSL)

       xprt_unregister
	     rpc_svc_calls(3NSL)

FILES
       /etc/netconfig

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO
       getnetconfig(3NSL),	  getnetpath(3NSL),	  rpc_clnt_auth(3NSL),
       rpc_clnt_calls(3NSL),	rpc_clnt_create(3NSL),	  rpc_svc_calls(3NSL),
       rpc_svc_create(3NSL),	   rpc_svc_err(3NSL),	    rpc_svc_reg(3NSL),
       rpc_xdr(3NSL),	 rpcbind(3NSL),	   secure_rpc(3NSL),	threads(3THR),
       xdr(3NSL), netconfig(4),	rpc(4),	attributes(5), environ(5)

SunOS 5.9			  5 Jun	2001			     rpc(3NSL)

NAME | SYNOPSIS | DESCRIPTION | FILES | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rpc&sektion=3nsl&manpath=SunOS+5.9>

home | help