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