3.\" Copyright 1985-1993 Sun Microsystems, Inc.
4.Dd March 28, 1993
5.Dt RPCGEN 1
6.Os
7.Sh NAME
8.Nm rpcgen
9.Nd an RPC protocol compiler
10.Sh SYNOPSIS
11.Nm rpcgen
12.Ar infile
13.Nm rpcgen
14.Op Fl a
15.Op Fl b
16.Op Fl C
17.Oo
18.Fl D Ns Ar name Ns Op Ar =value
19.Oc
20.Op Fl i Ar size
21.Op Fl I Op Fl K Ar seconds
22.Op Fl L
23.Op Fl M
24.Op Fl N
25.Op Fl T
26.Op Fl Y Ar pathname
27.Ar infile
28.Nm rpcgen
29.Oo
30.Fl c |
31.Fl h |
32.Fl l |
33.Fl m |
34.Fl t |
35.Fl \&Sc |
36.Fl \&Ss |
37.Fl \&Sm
38.Oc
39.Op Fl o Ar outfile
40.Op Ar infile
41.Nm rpcgen
42.Op Fl s Ar nettype
43.Op Fl o Ar outfile
44.Op Ar infile
45.Nm rpcgen
46.Op Fl n Ar netid
47.Op Fl o Ar outfile
48.Op Ar infile
49.\" .SH AVAILABILITY
50.\" .LP
51.\" SUNWcsu
52.Sh DESCRIPTION
53.Nm Rpcgen
54is a tool that generates C code to implement an
55.Tn RPC
56protocol.
57The input to
58.Nm
59is a language similar to C known as
60.Tn RPC
61Language (Remote Procedure Call Language).
62.Pp
63.Nm Rpcgen
64is normally used as in the first synopsis where
65it takes an input file and generates three output files.
66If the
67.Ar infile
68is named
69.Pa proto.x ,
70then
71.Nm
72generates a header in
73.Pa proto.h ,
74XDR routines in
75.Pa proto_xdr.c ,
76server-side stubs in
77.Pa proto_svc.c ,
78and client-side stubs in
79.Pa proto_clnt.c .
80With the
81.Fl T
82option,
83it also generates the
84.Tn RPC
85dispatch table in
86.Pa proto_tbl.i .
87.Pp
88.Nm Rpcgen
89can also generate sample client and server files
90that can be customized to suit a particular application. The
91.Fl \&Sc ,
92.Fl \&Ss
93and
94.Fl \&Sm
95options generate sample client, server and makefile, respectively.
96The
97.Fl a
98option generates all files, including sample files. If the
99.Ar infile
100is
101.Pa proto.x ,
102then the client side sample file is written to
103.Pa proto_client.c ,
104the server side sample file to
105.Pa proto_server.c
106and the sample makefile to
107.Pa makefile.proto .
108.Pp
109The server created can be started both by the port monitors
110(for example,
111.Xr inetd 8 )
112or by itself.
113When it is started by a port monitor,
114it creates servers only for the transport for which
115the file descriptor
116.Em 0
117was passed.
118The name of the transport must be specified
119by setting up the environment variable
120.Ev PM_TRANSPORT .
121When the server generated by
122.Nm
123is executed,
124it creates server handles for all the transports
125specified in
126.Ev NETPATH
127environment variable,
128or if it is unset,
129it creates server handles for all the visible transports from
130.Pa /etc/netconfig
131file.
132Note:
133the transports are chosen at run time and not at compile time.
134When the server is self-started,
135it backgrounds itself by default.
136A special define symbol
137.Em RPC_SVC_FG
138can be used to run the server process in foreground.
139.Pp
140The second synopsis provides special features which allow
141for the creation of more sophisticated
142.Tn RPC
143servers.
144These features include support for user provided
145.Em #defines
146and
147.Tn RPC
148dispatch tables.
149The entries in the
150.Tn RPC
151dispatch table contain:
152.Bl -bullet -offset indent -compact
153.It
154pointers to the service routine corresponding to that procedure,
155.It
156a pointer to the input and output arguments,
157.It
158the size of these routines.
159.El
160A server can use the dispatch table to check authorization
161and then to execute the service routine;
162a client library may use it to deal with the details of storage
163management and XDR data conversion.
164.Pp
165The other three synopses shown above are used when
166one does not want to generate all the output files,
167but only a particular one.
168See the
169.Sx EXAMPLES
170section below for examples of
171.Nm
172usage.
173When
174.Nm
175is executed with the
176.Fl s
177option,
178it creates servers for that particular class of transports.
179When
180executed with the
181.Fl n
182option,
183it creates a server for the transport specified by
184.Ar netid .
185If
186.Ar infile
187is not specified,
188.Nm
189accepts the standard input.
190.Pp
191The C preprocessor,
192.Em cc -E
193is run on the input file before it is actually interpreted by
194.Nm Ns .
195For each type of output file,
196.Nm
197defines a special preprocessor symbol for use by the
198.Nm
199programmer:
200.Bl -tag -width indent
201.It RPC_HDR
202defined when compiling into headers
203.It RPC_XDR
204defined when compiling into XDR routines
205.It RPC_SVC
206defined when compiling into server-side stubs
207.It RPC_CLNT
208defined when compiling into client-side stubs
209.It RPC_TBL
210defined when compiling into RPC dispatch tables
211.El
212.Pp
213Any line beginning with
214.Dq %
215is passed directly into the output file,
216uninterpreted by
217.Nm Ns .
218To specify the path name of the C preprocessor use
219.Fl Y
220flag.
221.Pp
222For every data type referred to in
223.Ar infile ,
224.Nm
225assumes that there exists a
226routine with the string
227.Em xdr_
228prepended to the name of the data type.
229If this routine does not exist in the
230.Tn RPC/XDR
231library, it must be provided.
232Providing an undefined data type
233allows customization of
234.Xr XDR
235routines.
236.Sh OPTIONS
237The following options are available:
238.Bl -tag -width indent
239.It Fl a
240Generate all files, including sample files.
241.It Fl b
242Backward compatibility mode.
243Generate transport specific
244.Tn RPC
245code for older versions
246of the operating system.
247.Pp
248Note: in
| 3.\" Copyright 1985-1993 Sun Microsystems, Inc.
4.Dd March 28, 1993
5.Dt RPCGEN 1
6.Os
7.Sh NAME
8.Nm rpcgen
9.Nd an RPC protocol compiler
10.Sh SYNOPSIS
11.Nm rpcgen
12.Ar infile
13.Nm rpcgen
14.Op Fl a
15.Op Fl b
16.Op Fl C
17.Oo
18.Fl D Ns Ar name Ns Op Ar =value
19.Oc
20.Op Fl i Ar size
21.Op Fl I Op Fl K Ar seconds
22.Op Fl L
23.Op Fl M
24.Op Fl N
25.Op Fl T
26.Op Fl Y Ar pathname
27.Ar infile
28.Nm rpcgen
29.Oo
30.Fl c |
31.Fl h |
32.Fl l |
33.Fl m |
34.Fl t |
35.Fl \&Sc |
36.Fl \&Ss |
37.Fl \&Sm
38.Oc
39.Op Fl o Ar outfile
40.Op Ar infile
41.Nm rpcgen
42.Op Fl s Ar nettype
43.Op Fl o Ar outfile
44.Op Ar infile
45.Nm rpcgen
46.Op Fl n Ar netid
47.Op Fl o Ar outfile
48.Op Ar infile
49.\" .SH AVAILABILITY
50.\" .LP
51.\" SUNWcsu
52.Sh DESCRIPTION
53.Nm Rpcgen
54is a tool that generates C code to implement an
55.Tn RPC
56protocol.
57The input to
58.Nm
59is a language similar to C known as
60.Tn RPC
61Language (Remote Procedure Call Language).
62.Pp
63.Nm Rpcgen
64is normally used as in the first synopsis where
65it takes an input file and generates three output files.
66If the
67.Ar infile
68is named
69.Pa proto.x ,
70then
71.Nm
72generates a header in
73.Pa proto.h ,
74XDR routines in
75.Pa proto_xdr.c ,
76server-side stubs in
77.Pa proto_svc.c ,
78and client-side stubs in
79.Pa proto_clnt.c .
80With the
81.Fl T
82option,
83it also generates the
84.Tn RPC
85dispatch table in
86.Pa proto_tbl.i .
87.Pp
88.Nm Rpcgen
89can also generate sample client and server files
90that can be customized to suit a particular application. The
91.Fl \&Sc ,
92.Fl \&Ss
93and
94.Fl \&Sm
95options generate sample client, server and makefile, respectively.
96The
97.Fl a
98option generates all files, including sample files. If the
99.Ar infile
100is
101.Pa proto.x ,
102then the client side sample file is written to
103.Pa proto_client.c ,
104the server side sample file to
105.Pa proto_server.c
106and the sample makefile to
107.Pa makefile.proto .
108.Pp
109The server created can be started both by the port monitors
110(for example,
111.Xr inetd 8 )
112or by itself.
113When it is started by a port monitor,
114it creates servers only for the transport for which
115the file descriptor
116.Em 0
117was passed.
118The name of the transport must be specified
119by setting up the environment variable
120.Ev PM_TRANSPORT .
121When the server generated by
122.Nm
123is executed,
124it creates server handles for all the transports
125specified in
126.Ev NETPATH
127environment variable,
128or if it is unset,
129it creates server handles for all the visible transports from
130.Pa /etc/netconfig
131file.
132Note:
133the transports are chosen at run time and not at compile time.
134When the server is self-started,
135it backgrounds itself by default.
136A special define symbol
137.Em RPC_SVC_FG
138can be used to run the server process in foreground.
139.Pp
140The second synopsis provides special features which allow
141for the creation of more sophisticated
142.Tn RPC
143servers.
144These features include support for user provided
145.Em #defines
146and
147.Tn RPC
148dispatch tables.
149The entries in the
150.Tn RPC
151dispatch table contain:
152.Bl -bullet -offset indent -compact
153.It
154pointers to the service routine corresponding to that procedure,
155.It
156a pointer to the input and output arguments,
157.It
158the size of these routines.
159.El
160A server can use the dispatch table to check authorization
161and then to execute the service routine;
162a client library may use it to deal with the details of storage
163management and XDR data conversion.
164.Pp
165The other three synopses shown above are used when
166one does not want to generate all the output files,
167but only a particular one.
168See the
169.Sx EXAMPLES
170section below for examples of
171.Nm
172usage.
173When
174.Nm
175is executed with the
176.Fl s
177option,
178it creates servers for that particular class of transports.
179When
180executed with the
181.Fl n
182option,
183it creates a server for the transport specified by
184.Ar netid .
185If
186.Ar infile
187is not specified,
188.Nm
189accepts the standard input.
190.Pp
191The C preprocessor,
192.Em cc -E
193is run on the input file before it is actually interpreted by
194.Nm Ns .
195For each type of output file,
196.Nm
197defines a special preprocessor symbol for use by the
198.Nm
199programmer:
200.Bl -tag -width indent
201.It RPC_HDR
202defined when compiling into headers
203.It RPC_XDR
204defined when compiling into XDR routines
205.It RPC_SVC
206defined when compiling into server-side stubs
207.It RPC_CLNT
208defined when compiling into client-side stubs
209.It RPC_TBL
210defined when compiling into RPC dispatch tables
211.El
212.Pp
213Any line beginning with
214.Dq %
215is passed directly into the output file,
216uninterpreted by
217.Nm Ns .
218To specify the path name of the C preprocessor use
219.Fl Y
220flag.
221.Pp
222For every data type referred to in
223.Ar infile ,
224.Nm
225assumes that there exists a
226routine with the string
227.Em xdr_
228prepended to the name of the data type.
229If this routine does not exist in the
230.Tn RPC/XDR
231library, it must be provided.
232Providing an undefined data type
233allows customization of
234.Xr XDR
235routines.
236.Sh OPTIONS
237The following options are available:
238.Bl -tag -width indent
239.It Fl a
240Generate all files, including sample files.
241.It Fl b
242Backward compatibility mode.
243Generate transport specific
244.Tn RPC
245code for older versions
246of the operating system.
247.Pp
248Note: in
|
295platform, the default is actually 0 (which means
296that inline code generation is disabled by default). You must specify
297a non-zero value explicitly to override this default.
298.It Fl I
299Compile support for
300.Xr inetd 8
301in the server side stubs.
302Such servers can be self-started or can be started by
303.Nm inetd .
304When the server is self-started, it backgrounds itself by default.
305A special define symbol
306.Em RPC_SVC_FG
307can be used to run the
308server process in foreground, or the user may simply compile without
309the
310.Fl I
311option.
312.Pp
313If there are no pending client requests, the
314.Nm inetd
315servers exit after 120 seconds (default).
316The default can be changed with the
317.Fl K
318option.
319All the error messages for
320.Nm inetd
321servers
322are always logged with
323.Xr syslog 3 .
324.\" .IP
325.\" Note:
326.\" this option is supported for backward compatibility only.
327.\" By default,
328.\" .B rpcgen
329.\" generates servers that can be invoked through portmonitors.
330.Pp
331.It Fl K Ar seconds
332By default, services created using
333.Nm
334and invoked through
335port monitors wait 120 seconds
336after servicing a request before exiting.
337That interval can be changed using the
338.Fl K
339flag.
340To create a server that exits immediately upon servicing a request,
341use
342.Fl K Ar 0 .
343To create a server that never exits, the appropriate argument is
344.Fl k Ar -1 .
345.Pp
346When monitoring for a server,
347some portmonitors
348.Em always
349spawn a new process in response to a service request.
350If it is known that a server will be used with such a monitor, the
351server should exit immediately on completion.
352For such servers,
353.Nm
354should be used with
355.Fl K Ar 0 .
356.It Fl l
357Compile into client-side stubs.
358.It Fl L
359When the servers are started in foreground, use
360.Xr syslog 3
361to log the server errors instead of printing them on the standard
362error.
363.It Fl m
364Compile into server-side stubs,
365but do not generate a
366.Qq main
367routine.
368This option is useful for doing callback-routines
369and for users who need to write their own
370.Qq main
371routine to do initialization.
372.It Fl M
373Generate multithread-safe stubs for passing arguments and results between
374rpcgen generated code and user written code. This option is useful
375for users who want to use threads in their code. However, the
376.Xr rpc_svc_calls 3
377functions are not yet MT-safe, which means that rpcgen generated server-side
378code will not be MT-safe.
379.It Fl N
380This option allows procedures to have multiple arguments.
381It also uses the style of parameter passing that closely resembles C.
382So, when passing an argument to a remote procedure, you do not have to
383pass a pointer to the argument, but can pass the argument itself.
384This behavior is different from the old style of
385.Nm
386generated code.
387To maintain backward compatibility,
388this option is not the default.
389.It Fl n Ar netid
390Compile into server-side stubs for the transport
391specified by
392.Ar netid .
393There should be an entry for
394.Ar netid
395in the
396netconfig database.
397This option may be specified more than once,
398so as to compile a server that serves multiple transports.
399.It Fl o Ar outfile
400Specify the name of the output file.
401If none is specified,
402standard output is used
403(
404.Fl c ,
405.Fl h ,
406.Fl l ,
407.Fl m ,
408.Fl n ,
409.Fl s ,
410.Fl \&Sc ,
411.Fl \&Sm ,
412.Fl \&Ss ,
413and
414.Fl t
415modes only).
416.It Fl s Ar nettype
417Compile into server-side stubs for all the
418transports belonging to the class
419.Ar nettype .
420The supported classes are
421.Em netpath ,
422.Em visible ,
423.Em circuit_n ,
424.Em circuit_v ,
425.Em datagram_n ,
426.Em datagram_v ,
427.Em tcp ,
428and
429.Em udp
430(see
431.Xr rpc 3
432for the meanings associated with these classes).
433This option may be specified more than once.
434Note:
435the transports are chosen at run time and not at compile time.
436.It Fl \&Sc
437Generate sample client code that uses remote procedure calls.
438.It Fl \&Sm
439Generate a sample
440.Pa Makefile
441which can be used for compiling the application.
442.It Fl \&Ss
443Generate sample server code that uses remote procedure calls.
444.It Fl t
445Compile into
446.Tn RPC
447dispatch table.
448.It Fl T
449Generate the code to support
450.Tn RPC
451dispatch tables.
452.Pp
453The options
454.Fl c ,
455.Fl h ,
456.Fl l ,
457.Fl m ,
458.Fl s ,
459.Fl \&Sc ,
460.Fl \&Sm ,
461.Fl \&Ss ,
462and
463.Fl t
464are used exclusively to generate a particular type of file,
465while the options
466.Fl D
467and
468.Fl T
469are global and can be used with the other options.
470.It Fl Y Ar pathname
471Give the name of the directory where
472.Nm
473will start looking for the C-preprocessor.
474.El
475.Sh EXAMPLES
476The following example:
477.Dl example% rpcgen -T prot.x
478.Pp
479generates all the five files:
480.Pa prot.h ,
481.Pa prot_clnt.c ,
482.Pa prot_svc.c ,
483.Pa prot_xdr.c
484and
485.Pa prot_tbl.i .
486.Pp
487The following example sends the C data-definitions (header)
488to the standard output.
489.Dl example% rpcgen -h prot.x
490.Pp
491To send the test version of the
492.Fl D Ns Ar TEST ,
493server side stubs for
494all the transport belonging to the class
495.Ar datagram_n
496to standard output, use:
497.Dl example% rpcgen -s datagram_n -DTEST prot.x
498.Pp
499To create the server side stubs for the transport indicated
500by
501.Ar netid
502tcp,
503use:
504.Dl example% rpcgen -n tcp -o prot_svc.c prot.x
505.Sh SEE ALSO
506.Xr cc 1 ,
507.Xr rpc 3 ,
508.Xr syslog 3 ,
509.Xr inetd 8
510.\" .BR rpc_svc_calls (3)
511.Rs
512.%T The Nm rpcgen No chapter in the NETP manual
513.Re
| 295platform, the default is actually 0 (which means
296that inline code generation is disabled by default). You must specify
297a non-zero value explicitly to override this default.
298.It Fl I
299Compile support for
300.Xr inetd 8
301in the server side stubs.
302Such servers can be self-started or can be started by
303.Nm inetd .
304When the server is self-started, it backgrounds itself by default.
305A special define symbol
306.Em RPC_SVC_FG
307can be used to run the
308server process in foreground, or the user may simply compile without
309the
310.Fl I
311option.
312.Pp
313If there are no pending client requests, the
314.Nm inetd
315servers exit after 120 seconds (default).
316The default can be changed with the
317.Fl K
318option.
319All the error messages for
320.Nm inetd
321servers
322are always logged with
323.Xr syslog 3 .
324.\" .IP
325.\" Note:
326.\" this option is supported for backward compatibility only.
327.\" By default,
328.\" .B rpcgen
329.\" generates servers that can be invoked through portmonitors.
330.Pp
331.It Fl K Ar seconds
332By default, services created using
333.Nm
334and invoked through
335port monitors wait 120 seconds
336after servicing a request before exiting.
337That interval can be changed using the
338.Fl K
339flag.
340To create a server that exits immediately upon servicing a request,
341use
342.Fl K Ar 0 .
343To create a server that never exits, the appropriate argument is
344.Fl k Ar -1 .
345.Pp
346When monitoring for a server,
347some portmonitors
348.Em always
349spawn a new process in response to a service request.
350If it is known that a server will be used with such a monitor, the
351server should exit immediately on completion.
352For such servers,
353.Nm
354should be used with
355.Fl K Ar 0 .
356.It Fl l
357Compile into client-side stubs.
358.It Fl L
359When the servers are started in foreground, use
360.Xr syslog 3
361to log the server errors instead of printing them on the standard
362error.
363.It Fl m
364Compile into server-side stubs,
365but do not generate a
366.Qq main
367routine.
368This option is useful for doing callback-routines
369and for users who need to write their own
370.Qq main
371routine to do initialization.
372.It Fl M
373Generate multithread-safe stubs for passing arguments and results between
374rpcgen generated code and user written code. This option is useful
375for users who want to use threads in their code. However, the
376.Xr rpc_svc_calls 3
377functions are not yet MT-safe, which means that rpcgen generated server-side
378code will not be MT-safe.
379.It Fl N
380This option allows procedures to have multiple arguments.
381It also uses the style of parameter passing that closely resembles C.
382So, when passing an argument to a remote procedure, you do not have to
383pass a pointer to the argument, but can pass the argument itself.
384This behavior is different from the old style of
385.Nm
386generated code.
387To maintain backward compatibility,
388this option is not the default.
389.It Fl n Ar netid
390Compile into server-side stubs for the transport
391specified by
392.Ar netid .
393There should be an entry for
394.Ar netid
395in the
396netconfig database.
397This option may be specified more than once,
398so as to compile a server that serves multiple transports.
399.It Fl o Ar outfile
400Specify the name of the output file.
401If none is specified,
402standard output is used
403(
404.Fl c ,
405.Fl h ,
406.Fl l ,
407.Fl m ,
408.Fl n ,
409.Fl s ,
410.Fl \&Sc ,
411.Fl \&Sm ,
412.Fl \&Ss ,
413and
414.Fl t
415modes only).
416.It Fl s Ar nettype
417Compile into server-side stubs for all the
418transports belonging to the class
419.Ar nettype .
420The supported classes are
421.Em netpath ,
422.Em visible ,
423.Em circuit_n ,
424.Em circuit_v ,
425.Em datagram_n ,
426.Em datagram_v ,
427.Em tcp ,
428and
429.Em udp
430(see
431.Xr rpc 3
432for the meanings associated with these classes).
433This option may be specified more than once.
434Note:
435the transports are chosen at run time and not at compile time.
436.It Fl \&Sc
437Generate sample client code that uses remote procedure calls.
438.It Fl \&Sm
439Generate a sample
440.Pa Makefile
441which can be used for compiling the application.
442.It Fl \&Ss
443Generate sample server code that uses remote procedure calls.
444.It Fl t
445Compile into
446.Tn RPC
447dispatch table.
448.It Fl T
449Generate the code to support
450.Tn RPC
451dispatch tables.
452.Pp
453The options
454.Fl c ,
455.Fl h ,
456.Fl l ,
457.Fl m ,
458.Fl s ,
459.Fl \&Sc ,
460.Fl \&Sm ,
461.Fl \&Ss ,
462and
463.Fl t
464are used exclusively to generate a particular type of file,
465while the options
466.Fl D
467and
468.Fl T
469are global and can be used with the other options.
470.It Fl Y Ar pathname
471Give the name of the directory where
472.Nm
473will start looking for the C-preprocessor.
474.El
475.Sh EXAMPLES
476The following example:
477.Dl example% rpcgen -T prot.x
478.Pp
479generates all the five files:
480.Pa prot.h ,
481.Pa prot_clnt.c ,
482.Pa prot_svc.c ,
483.Pa prot_xdr.c
484and
485.Pa prot_tbl.i .
486.Pp
487The following example sends the C data-definitions (header)
488to the standard output.
489.Dl example% rpcgen -h prot.x
490.Pp
491To send the test version of the
492.Fl D Ns Ar TEST ,
493server side stubs for
494all the transport belonging to the class
495.Ar datagram_n
496to standard output, use:
497.Dl example% rpcgen -s datagram_n -DTEST prot.x
498.Pp
499To create the server side stubs for the transport indicated
500by
501.Ar netid
502tcp,
503use:
504.Dl example% rpcgen -n tcp -o prot_svc.c prot.x
505.Sh SEE ALSO
506.Xr cc 1 ,
507.Xr rpc 3 ,
508.Xr syslog 3 ,
509.Xr inetd 8
510.\" .BR rpc_svc_calls (3)
511.Rs
512.%T The Nm rpcgen No chapter in the NETP manual
513.Re
|