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