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