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