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