Annotation of src/usr.bin/rpcgen/rpcgen.1, Revision 1.9
1.9 ! deraadt 1: .\" $OpenBSD: rpcgen.1,v 1.8 2000/11/10 05:10:39 aaron Exp $
1.2 deraadt 2: .\" $NetBSD: rpcgen.1,v 1.5.2.1 1995/12/05 02:51:02 jtc Exp $
1.1 deraadt 3: .\" from: @(#)rpcgen.new.1 1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89
4: .\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved.
5: .Dd June 11, 1995
6: .Dt RPCGEN 1
1.5 aaron 7: .Os
1.1 deraadt 8: .Sh NAME
9: .Nm rpcgen
10: .Nd RPC protocol compiler
11: .Sh SYNOPSIS
12: .Nm rpcgen
1.9 ! deraadt 13: .Op Fl aALTNbC
! 14: .Op Fl D Op Ar name Ns Op =value
1.1 deraadt 15: .Op Fl K Ar secs
1.9 ! deraadt 16: .Op Fl i Ar lines
1.1 deraadt 17: .Ar infile
18: .Nm rpcgen
19: .Fl c Li |
20: .Fl h Li |
21: .Fl l Li |
22: .Fl m Li |
23: .Fl t Li |
24: .Fl S\&c Li |
25: .Fl S\&s Li |
26: .Op Fl o Ar outfile
27: .Op Ar infile
28: .Nm rpcgen
29: .Fl c Li |
30: .Ar nettype
31: .Op Fl o Ar outfile
32: .Op Ar infile
33: .Sh DESCRIPTION
1.6 aaron 34: .Nm
1.1 deraadt 35: is a tool that generates C code to implement an
36: .Tn RPC
37: protocol.
1.6 aaron 38: The input is a language similar to C known as
1.1 deraadt 39: .Tn RPC
40: Language (Remote Procedure Call Language).
1.6 aaron 41: .Nm
1.1 deraadt 42: is normally used as in the first synopsis where
43: it takes an input file and generates up to four output files.
44: If the
45: .Ar infile
46: is named
47: .Pa proto.x ,
48: then
1.6 aaron 49: .Nm
1.1 deraadt 50: will generate a header file in
51: .Pa proto.h ,
52: .Tn XDR
53: routines in
54: .Pa proto_xdr.c ,
55: server-side stubs in
56: .Pa proto_svc.c ,
57: and client-side stubs in
58: .Pa proto_clnt.c .
59: With the
60: .Fl T
61: option,
62: it will also generate the
63: .Tn RPC
64: dispatch table in
65: .Pa proto_tbl.i .
66: With the
67: .Fl S\&c
68: option,
69: it will also generate sample code which would illustrate how to use the
1.6 aaron 70: remote procedures on the client side.
71: This code would be created in
1.1 deraadt 72: .Pa proto_client.c .
73: With the
74: .Fl S\&s
75: option,
76: it will also generate a sample server code which would illustrate how to write
1.6 aaron 77: the remote procedures.
78: This code would be created in
1.1 deraadt 79: .Pa proto_server.c .
80: .Pp
81: The server created can be started both by the port monitors
82: (for example,
1.9 ! deraadt 83: .Xr inetd 8 Ns )
1.1 deraadt 84: or by itself.
85: When it is started by a port monitor,
86: it creates servers only for the transport for which
87: the file descriptor 0 was passed.
1.9 ! deraadt 88: The transports are chosen at run time and not at compile time.
1.1 deraadt 89: When the server is self-started,
90: it backgrounds itself by default.
91: A special define symbol
92: .Dv RPC_SVC_FG
1.4 aaron 93: can be used to run the server process in the foreground.
1.1 deraadt 94: .P
95: The second synopsis provides special features which allow
96: for the creation of more sophisticated
97: .Tn RPC
98: servers.
99: These features include support for user provided
100: .Li #defines
101: and
102: .Tn RPC
103: dispatch tables.
104: The entries in the
105: .Tn RPC
106: dispatch table contain:
107: .Pp
108: .Bl -inset -offset indent -compact
109: .It +
110: pointers to the service routine corresponding to that procedure,
111: .It +
112: a pointer to the input and output arguments,
113: .It +
114: the size of these routines
115: .El
116: .Pp
117: A server can use the dispatch table to check authorization
118: and then to execute the service routine;
119: a client library may use it to deal with the details of storage
120: management and
121: .Tn XDR
122: data conversion.
123: .Pp
124: The other three synopses shown above are used when
125: one does not want to generate all the output files,
126: but only a particular one.
127: Some examples of their usage is described in the
1.6 aaron 128: .Sx EXAMPLES
1.1 deraadt 129: section below.
130: When
1.6 aaron 131: .Nm
1.1 deraadt 132: is executed with the
133: .Fl s
134: option,
135: it creates servers for that particular class of transports.
136: When
137: executed with the
138: .Fl n
139: option,
140: it creates a server for the transport specified by
141: .Em netid .
142: If
143: .Ar infile
144: is not specified,
1.6 aaron 145: .Nm
1.1 deraadt 146: accepts the standard input.
147: .Pp
148: The C preprocessor,
149: .Xr cpp 1
150: is run on the input file before it is actually interpreted by
1.4 aaron 151: .Nm rpcgen .
1.1 deraadt 152: For each type of output file,
1.6 aaron 153: .Nm
1.1 deraadt 154: defines a special preprocessor symbol for use by the
1.6 aaron 155: .Nm
1.1 deraadt 156: programmer:
157: .Pp
1.4 aaron 158: .Bl -tag -width RPC_CLNT -compact
159: .It Dv RPC_HDR
160: Defined when compiling into header files.
161: .It Dv RPC_XDR
162: Defined when compiling into
1.1 deraadt 163: .Tn XDR
1.4 aaron 164: routines.
165: .It Dv RPC_SVC
166: Defined when compiling into server-side stubs.
167: .It Dv RPC_CLNT
168: Defined when compiling into client-side stubs.
169: .It Dv RPC_TBL
170: Defined when compiling into
1.1 deraadt 171: .Tn RPC
1.4 aaron 172: dispatch tables.
173: .El
1.1 deraadt 174: .Pp
175: Any line beginning with
176: .Sq %
177: is passed directly into the output file,
178: uninterpreted by
1.4 aaron 179: .Nm rpcgen .
1.1 deraadt 180: .Pp
181: For every data type referred to in
182: .Ar infile
1.6 aaron 183: .Nm
1.1 deraadt 184: assumes that there exists a
185: routine with the string
186: .Dq xdr_
187: prepended to the name of the data type.
188: If this routine does not exist in the
189: .Tn RPC/XDR
190: library, it must be provided.
191: Providing an undefined data type
192: allows customization of
193: .Tn XDR
194: routines.
1.6 aaron 195: .Pp
196: The options are as follows:
1.7 aaron 197: .Bl -tag -width Ds
1.1 deraadt 198: .It Fl a
199: Generate all the files including sample code for client and server side.
200: .It Fl b
201: This generates code for the
202: .Tn SunOS4.1
1.6 aaron 203: style of RPC.
204: This is the default.
1.1 deraadt 205: .It Fl c
206: Compile into
207: .Tn XDR
208: routines.
209: .It Fl C
1.6 aaron 210: Generate code in ANSI C.
211: This option also generates code that could be
1.1 deraadt 212: compiled with the C++ compiler.
213: .It Fl D Ar name Ns Op Ar =value
214: Define a symbol
215: .Dv name .
216: Equivalent to the
217: .Dv #define
218: directive in the source.
219: If no
220: .Dv value
221: is given,
222: .Dv value
223: is defined as 1.
224: This option may be specified more than once.
225: .It Fl h
226: Compile into C data-definitions (a header file).
227: The
228: .Fl T
229: option can be used in conjunction to produce a
230: header file which supports
231: .Tn RPC
232: dispatch tables.
233: .It Fl K Ar secs
234: By default, services created using
1.6 aaron 235: .Nm
1.1 deraadt 236: wait 120 seconds
237: after servicing a request before exiting.
238: That interval can be changed using the
239: .Fl K
240: flag.
241: To create a server that exits immediately upon servicing a request,
242: .Dq Fl K No 0
243: can be used.
244: To create a server that never exits, the appropriate argument is
245: .Dq Fl K No -1 .
246: .IP
247: When monitoring for a server,
248: some port monitors, like the
249: .Tn SVR4
250: utility
251: .Xr listen 1 ,
252: .Em always
253: spawn a new process in response to a service request.
254: If it is known that a server will be used with such a monitor, the
255: server should exit immediately on completion.
256: For such servers,
1.6 aaron 257: .Nm
1.1 deraadt 258: should be used with
259: .Dq Fl K No -1 .
260: .It Fl l
261: Compile into client-side stubs.
262: .It Fl m
263: Compile into server-side stubs,
264: but do not generate a
265: .Fn main
266: routine.
267: This option is useful for doing callback-routines
268: and for users who need to write their own
269: .Fn main
270: routine to do initialization.
271: .It Fl n Ar netid
272: Compile into server-side stubs for the transport
273: specified by
1.4 aaron 274: .Ar netid .
1.1 deraadt 275: There should be an entry for
276: .Ar netid
277: in the
278: netconfig database.
279: This option may be specified more than once,
280: so as to compile a server that serves multiple transports.
281: .It Fl N
1.4 aaron 282: Use the newstyle of
283: .Nm rpcgen .
284: This allows procedures to have multiple arguments.
1.6 aaron 285: It also uses the style of parameter passing that closely resembles C.
286: So, when
1.1 deraadt 287: passing an argument to a remote procedure you do not have to pass a pointer to
1.6 aaron 288: the argument but the argument itself.
289: This behaviour is different from the oldstyle
1.4 aaron 290: of
1.6 aaron 291: .Nm
292: generated code.
293: The newstyle is not the default case because of
1.1 deraadt 294: backward compatibility.
295: .It Fl o Ar outfile
296: Specify the name of the output file.
297: If none is specified,
298: standard output is used
299: .Po
300: .Fl c Fl h Fl l
301: .Fl m Fl n Fl s
302: modes only
1.4 aaron 303: .Pc .
1.1 deraadt 304: .It Fl s Ar nettype
305: Compile into server-side stubs for all the
306: transports belonging to the class
307: .Ar nettype .
308: The supported classes are
1.4 aaron 309: .Em netpath ,
310: .Em visible ,
311: .Em circuit_n ,
312: .Em circuit_v ,
313: .Em datagram_n ,
314: .Em datagram_v ,
315: .Em tcp ,
1.1 deraadt 316: and
317: .Em udp
318: [see
319: .Xr rpc 3
1.6 aaron 320: for the meanings associated with these classes.
321: Note:
1.1 deraadt 322: .Bx
323: currently supports only the
324: .Em tcp
325: and
326: .Em udp
327: classes].
328: This option may be specified more than once.
329: Note:
330: the transports are chosen at run time and not at compile time.
331: .It Fl S\&c
332: Generate sample code to show the use of remote procedure and how to bind
1.4 aaron 333: to the server before calling the client side stubs generated by
334: .Nm rpcgen .
1.1 deraadt 335: .It Fl S\&s
1.6 aaron 336: Generate skeleton code for the remote procedures on the server side.
337: You would need
1.1 deraadt 338: to fill in the actual code for the remote procedures.
339: .It Fl t
340: Compile into
341: .Tn RPC
342: dispatch table.
343: .It Fl T
344: Generate the code to support
345: .Tn RPC
346: dispatch tables.
347: .El
348: .Pp
349: The options
350: .Fl c ,
351: .Fl h ,
352: .Fl l ,
353: .Fl m ,
354: .Fl s ,
355: and
356: .Fl t
357: are used exclusively to generate a particular type of file,
358: while the options
359: .Fl D
360: and
361: .Fl T
362: are global and can be used with the other options.
1.6 aaron 363: .Sh EXAMPLES
1.1 deraadt 364: The command
365: .Pp
366: .Bd -literal -offset indent
367: $ rpcgen -T prot.x
368: .Ed
369: .Pp
370: generates the five files:
371: .Pa prot.h ,
372: .Pa prot_clnt.c ,
373: .Pa prot_svc.c ,
374: .Pa prot_xdr.c
375: and
376: .Pa prot_tbl.i .
377: .Pp
378: The following example sends the C data-definitions (header file)
1.4 aaron 379: to standard output:
1.1 deraadt 380: .Pp
381: .Bd -literal -offset indent
382: $ rpcgen -h prot.x
383: .Ed
384: .Pp
385: To send the test version of the
386: .Dv -DTEST ,
387: server side stubs for
388: all the transport belonging to the class
389: .Em datagram_n
390: to standard output, use:
391: .Pp
392: .Bd -literal -offset indent
393: $ rpcgen -s datagram_n -DTEST prot.x
394: .Ed
395: .Pp
396: To create the server side stubs for the transport indicated by
397: .Em netid
398: .Em tcp ,
399: use:
400: .Pp
401: .Bd -literal -offset indent
402: $ rpcgen -n tcp -o prot_svc.c prot.x
403: .Ed
1.8 aaron 404: .Sh NOTES
405: The
406: .Tn RPC
407: Language does not support nesting of structures.
408: As a workaround, structures can be declared at the top-level, and their
409: name used inside other structures in order to achieve the same effect.
410: .Pp
411: Name clashes can occur when using program definitions, since the apparent
412: scoping does not really apply.
413: Most of these can be avoided by giving unique names for programs,
414: versions, procedures, and types.
415: .Pp
416: The server code generated with
417: .Fl n
418: option refers to the transport indicated by
419: .Em netid
420: and hence is very site specific.
1.1 deraadt 421: .Sh SEE ALSO
422: .Xr cpp 1
![[BACK]](/icons/back.gif){kind=icon}
Return to rpcgen.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / rpcgen