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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
RPCGEN(1)		FreeBSD	General	Commands Manual		     RPCGEN(1)

NAME
     rpcgen -- an RPC protocol compiler

SYNOPSIS
     rpcgen infile
     rpcgen [-a] [-b] [-C] [-Dname[=value]] [-i	size] [-I -P [-K seconds]]
	    [-L] [-M] [-N] [-T]	[-Y pathname] infile
     rpcgen [-c	| -h | -l | -m | -t | -Sc | -Ss	| -Sm] [-o outfile] [infile]
     rpcgen [-s	nettype] [-o outfile] [infile]
     rpcgen [-n	netid] [-o outfile] [infile]

DESCRIPTION
     The rpcgen	utility	is a tool that generates C code	to implement an	RPC
     protocol.	The input to rpcgen is a language similar to C known as	RPC
     Language (Remote Procedure	Call Language).

     The rpcgen	utility	is normally used as in the first synopsis where	it
     takes an input file and generates three output files.  If the infile is
     named proto.x, then rpcgen	generates a header in proto.h, XDR routines in
     proto_xdr.c, server-side stubs in proto_svc.c, and	client-side stubs in
     proto_clnt.c.  With the -T	option,	it also	generates the RPC dispatch ta-
     ble in proto_tbl.i.

     The rpcgen	utility	can also generate sample client	and server files that
     can be customized to suit a particular application.  The -Sc, -Ss and -Sm
     options generate sample client, server and	makefile, respectively.	 The
     -a	option generates all files, including sample files.  If	the infile is
     proto.x, then the client side sample file is written to proto_client.c,
     the server	side sample file to proto_server.c and the sample makefile to
     makefile.proto.

     If	option -I is set, the server created can be started both by the	port
     monitors (for example, inetd(8)) or by itself.  When it is	started	by a
     port monitor, it creates servers only for the transport for which the
     file descriptor 0 was passed.  The	name of	the transport may be specified
     by	setting	up the environment variable NLSPROVIDER.  When the server gen-
     erated by rpcgen is executed, it creates server handles for all the
     transports	specified in NETPATH environment variable, or if it is unset,
     it	creates	server handles for all the visible transports from
     /etc/netconfig file.  Note: the transports	are chosen at run time and not
     at	compile	time.  When the	server is self-started,	it backgrounds itself
     by	default.  A special define symbol RPC_SVC_FG can be used to run	the
     server process in foreground.

     The second	synopsis provides special features which allow for the cre-
     ation of more sophisticated RPC servers.  These features include support
     for user provided #defines	and RPC	dispatch tables.  The entries in the
     RPC dispatch table	contain:
	   +o   pointers	to the service routine corresponding to	that proce-
	       dure,
	   +o   a pointer to the	input and output arguments,
	   +o   the size	of these routines.
     A server can use the dispatch table to check authorization	and then to
     execute the service routine; a client library may use it to deal with the
     details of	storage	management and XDR data	conversion.

     The other three synopses shown above are used when	one does not want to
     generate all the output files, but	only a particular one.	See the
     EXAMPLES section below for	examples of rpcgen usage.  When	rpcgen is exe-
     cuted with	the -s option, it creates servers for that particular class of
     transports.  When executed	with the -n option, it creates a server	for
     the transport specified by	netid.	If infile is not specified, rpcgen
     accepts the standard input.

     The C preprocessor, cc -E is run on the input file	before it is actually
     interpreted by rpcgen.  For each type of output file, rpcgen defines a
     special preprocessor symbol for use by the	rpcgen programmer:

     RPC_HDR
	     defined when compiling into headers

     RPC_XDR
	     defined when compiling into XDR routines

     RPC_SVC
	     defined when compiling into server-side stubs

     RPC_CLNT
	     defined when compiling into client-side stubs

     RPC_TBL
	     defined when compiling into RPC dispatch tables

     Any line beginning	with ``%'' is passed directly into the output file,
     uninterpreted by rpcgen.  To specify the path name	of the C preprocessor
     use -Y flag.

     For every data type referred to in	infile,	rpcgen assumes that there
     exists a routine with the string xdr_ prepended to	the name of the	data
     type.  If this routine does not exist in the RPC/XDR library, it must be
     provided.	Providing an undefined data type allows	customization of
     xdr(3) routines.

OPTIONS
     The following options are available:

     -a	     Generate all files, including sample files.

     -b	     Backward compatibility mode.  Generate transport specific RPC
	     code for older versions of	the operating system.

     -c	     Compile into XDR routines.

     -C	     Generate ANSI C code.  This is always done, the flag is only pro-
	     vided for backwards compatibility.

     -Dname

     -Dname=value
	     Define a symbol name.  Equivalent to the #define directive	in the
	     source.  If no value is given, value is defined as	1.  This
	     option may	be specified more than once.

     -h	     Compile into C data-definitions (a	header).  -T option can	be
	     used in conjunction to produce a header which supports RPC	dis-
	     patch tables.

     -i	size
	     Size at which to start generating inline code.  This option is
	     useful for	optimization.  The default size	is 5.

	     Note: in order to provide backwards compatibility with the	older
	     rpcgen on the FreeBSD platform, the default is actually 0 (which
	     means that	inline code generation is disabled by default).	 You
	     must specify a non-zero value explicitly to override this
	     default.

     -I	     Compile support for inetd(8) in the server	side stubs.  Such
	     servers can be self-started or can	be started by inetd(8).	 When
	     the server	is self-started, it backgrounds	itself by default.  A
	     special define symbol RPC_SVC_FG can be used to run the server
	     process in	foreground, or the user	may simply compile without the
	     -I	option.

	     If	there are no pending client requests, the inetd(8) servers
	     exit after	120 seconds (default).	The default can	be changed
	     with the -K option.  All the error	messages for inetd(8) servers
	     are always	logged with syslog(3).

	     Note: Contrary to some systems, in	FreeBSD	this option is needed
	     to	generate servers that can be invoked through portmonitors and
	     inetd(8).

     -K	seconds
	     By	default, services created using	rpcgen and invoked through
	     port monitors wait	120 seconds after servicing a request before
	     exiting.  That interval can be changed using the -K flag.	To
	     create a server that exits	immediately upon servicing a request,
	     use -K 0.	To create a server that	never exits, the appropriate
	     argument is -K -1.

	     When monitoring for a server, some	portmonitors always spawn a
	     new process in response to	a service request.  If it is known
	     that a server will	be used	with such a monitor, the server	should
	     exit immediately on completion.  For such servers,	rpcgen should
	     be	used with -K 0.

     -l	     Compile into client-side stubs.

     -L	     When the servers are started in foreground, use syslog(3) to log
	     the server	errors instead of printing them	on the standard	error.

     -m	     Compile into server-side stubs, but do not	generate a "main" rou-
	     tine.  This option	is useful for doing callback-routines and for
	     users who need to write their own "main" routine to do initial-
	     ization.

     -M	     Generate multithread-safe stubs for passing arguments and results
	     between rpcgen generated code and user written code.  This	option
	     is	useful for users who want to use threads in their code.	 How-
	     ever, the rpc_svc_calls(3)	functions are not yet MT-safe, which
	     means that	rpcgen generated server-side code will not be MT-safe.

     -N	     Allow procedures to have multiple arguments.  It also uses	the
	     style of parameter	passing	that closely resembles C.  So, when
	     passing an	argument to a remote procedure,	you do not have	to
	     pass a pointer to the argument, but can pass the argument itself.
	     This behavior is different	from the old style of rpcgen generated
	     code.  To maintain	backward compatibility,	this option is not the
	     default.

     -n	netid
	     Compile into server-side stubs for	the transport specified	by
	     netid.  There should be an	entry for netid	in the netconfig data-
	     base.  This option	may be specified more than once, so as to com-
	     pile a server that	serves multiple	transports.

     -o	outfile
	     Specify the name of the output file.  If none is specified, stan-
	     dard output is used (-c, -h, -l, -m, -n, -s, -Sc, -Sm, -Ss, and
	     -t	modes only).

     -P	     Compile support for port monitors in the server side stubs.

	     Note: Contrary to some systems, in	FreeBSD	this option is needed
	     to	generate servers that can be monitored.

	     If	the -I option has been specified, -P is	turned off automati-
	     cally.

     -s	nettype
	     Compile into server-side stubs for	all the	transports belonging
	     to	the class nettype.  The	supported classes are netpath,
	     visible, circuit_n, circuit_v, datagram_n,	datagram_v, tcp, and
	     udp (see rpc(3) for the meanings associated with these classes).
	     This option may be	specified more than once.  Note: the trans-
	     ports are chosen at run time and not at compile time.

     -Sc     Generate sample client code that uses remote procedure calls.

     -Sm     Generate a	sample Makefile	which can be used for compiling	the
	     application.

     -Ss     Generate sample server code that uses remote procedure calls.

     -t	     Compile into RPC dispatch table.

     -T	     Generate the code to support RPC dispatch tables.

	     The options -c, -h, -l, -m, -s, -Sc, -Sm, -Ss, and	-t are used
	     exclusively to generate a particular type of file,	while the
	     options -D	and -T are global and can be used with the other
	     options.

     -Y	pathname
	     Give the name of the directory where rpcgen will start looking
	     for the C-preprocessor.

ENVIRONMENT
     If	the RPCGEN_CPP environment variable is set, its	value is used as the
     command line of the C preprocessor	to be run on the input file.

EXAMPLES
     The following example:
	   example% rpcgen -T prot.x

     generates all the five files: prot.h, prot_clnt.c,	prot_svc.c, prot_xdr.c
     and prot_tbl.i.

     The following example sends the C data-definitions	(header) to the	stan-
     dard output.
	   example% rpcgen -h prot.x

     To	send the test version of the -DTEST, server side stubs for all the
     transport belonging to the	class datagram_n to standard output, use:
	   example% rpcgen -s datagram_n -DTEST	prot.x

     To	create the server side stubs for the transport indicated by netid tcp,
     use:
	   example% rpcgen -n tcp -o prot_svc.c	prot.x

SEE ALSO
     cc(1), rpc(3), rpc_svc_calls(3), syslog(3), xdr(3), inetd(8)

     The rpcgen	chapter	in the NETP manual.

FreeBSD	10.1		       September 2, 2005		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rpcgen&sektion=1&manpath=FreeBSD+10.0-RELEASE>

home | help