Annotation of src/usr.bin/rpcgen/rpcgen.1, Revision 1.7
1.7 ! aaron 1: .\" $OpenBSD: rpcgen.1,v 1.6 2000/03/10 20:17:50 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
13: .Ar infile
14: .Nm rpcgen
15: .Op Fl D Op Ar name=value
16: .Op Fl A
17: .Op Fl M
18: .Op Fl T
19: .Op Fl K Ar secs
20: .Ar infile
21: .Nm rpcgen
22: .Fl c Li |
23: .Fl h Li |
24: .Fl l Li |
25: .Fl m Li |
26: .Fl t Li |
27: .Fl S\&c Li |
28: .Fl S\&s Li |
29: .Op Fl o Ar outfile
30: .Op Ar infile
31: .Nm rpcgen
32: .Fl c Li |
33: .Ar nettype
34: .Op Fl o Ar outfile
35: .Op Ar infile
36: .Nm rpcgen
37: .Fl s Li |
38: .Ar netid
39: .Op Fl o Ar outfile
40: .Op Ar infile
41: .Sh DESCRIPTION
1.6 aaron 42: .Nm
1.1 deraadt 43: is a tool that generates C code to implement an
44: .Tn RPC
45: protocol.
1.6 aaron 46: The input is a language similar to C known as
1.1 deraadt 47: .Tn RPC
48: Language (Remote Procedure Call Language).
1.6 aaron 49: .Nm
1.1 deraadt 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
1.6 aaron 57: .Nm
1.1 deraadt 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
1.6 aaron 78: remote procedures on the client side.
79: This code would be created in
1.1 deraadt 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
1.6 aaron 85: the remote procedures.
86: This code would be created in
1.1 deraadt 87: .Pa proto_server.c .
88: .Pp
89: The server created can be started both by the port monitors
90: (for example,
91: .Em inetd
92: or
93: .Em listen )
94: or by itself.
95: When it is started by a port monitor,
96: it creates servers only for the transport for which
97: the file descriptor 0 was passed.
98: The name of the transport must be specified
1.2 deraadt 99: by setting up the environment variable
1.1 deraadt 100: .Ev PM_TRANSPORT .
101: When the server generated by
1.6 aaron 102: .Nm
1.1 deraadt 103: is executed,
104: it creates server handles for all the transports
105: specified in
106: .Ev NETPATH
107: environment variable,
108: or if it is unset,
109: it creates server handles for all the visible transports from
110: .Pa /etc/netconfig
111: file.
112: Note:
113: the transports are chosen at run time and not at compile time.
114: When the server is self-started,
115: it backgrounds itself by default.
116: A special define symbol
117: .Dv RPC_SVC_FG
1.4 aaron 118: can be used to run the server process in the foreground.
1.1 deraadt 119: .P
120: The second synopsis provides special features which allow
121: for the creation of more sophisticated
122: .Tn RPC
123: servers.
124: These features include support for user provided
125: .Li #defines
126: and
127: .Tn RPC
128: dispatch tables.
129: The entries in the
130: .Tn RPC
131: dispatch table contain:
132: .Pp
133: .Bl -inset -offset indent -compact
134: .It +
135: pointers to the service routine corresponding to that procedure,
136: .It +
137: a pointer to the input and output arguments,
138: .It +
139: the size of these routines
140: .El
141: .Pp
142: A server can use the dispatch table to check authorization
143: and then to execute the service routine;
144: a client library may use it to deal with the details of storage
145: management and
146: .Tn XDR
147: data conversion.
148: .Pp
149: The other three synopses shown above are used when
150: one does not want to generate all the output files,
151: but only a particular one.
152: Some examples of their usage is described in the
1.6 aaron 153: .Sx EXAMPLES
1.1 deraadt 154: section below.
155: When
1.6 aaron 156: .Nm
1.1 deraadt 157: is executed with the
158: .Fl s
159: option,
160: it creates servers for that particular class of transports.
161: When
162: executed with the
163: .Fl n
164: option,
165: it creates a server for the transport specified by
166: .Em netid .
167: If
168: .Ar infile
169: is not specified,
1.6 aaron 170: .Nm
1.1 deraadt 171: accepts the standard input.
172: .Pp
173: The C preprocessor,
174: .Xr cpp 1
175: is run on the input file before it is actually interpreted by
1.4 aaron 176: .Nm rpcgen .
1.1 deraadt 177: For each type of output file,
1.6 aaron 178: .Nm
1.1 deraadt 179: defines a special preprocessor symbol for use by the
1.6 aaron 180: .Nm
1.1 deraadt 181: programmer:
182: .Pp
1.4 aaron 183: .Bl -tag -width RPC_CLNT -compact
184: .It Dv RPC_HDR
185: Defined when compiling into header files.
186: .It Dv RPC_XDR
187: Defined when compiling into
1.1 deraadt 188: .Tn XDR
1.4 aaron 189: routines.
190: .It Dv RPC_SVC
191: Defined when compiling into server-side stubs.
192: .It Dv RPC_CLNT
193: Defined when compiling into client-side stubs.
194: .It Dv RPC_TBL
195: Defined when compiling into
1.1 deraadt 196: .Tn RPC
1.4 aaron 197: dispatch tables.
198: .El
1.1 deraadt 199: .Pp
200: Any line beginning with
201: .Sq %
202: is passed directly into the output file,
203: uninterpreted by
1.4 aaron 204: .Nm rpcgen .
1.1 deraadt 205: .Pp
206: For every data type referred to in
207: .Ar infile
1.6 aaron 208: .Nm
1.1 deraadt 209: assumes that there exists a
210: routine with the string
211: .Dq xdr_
212: prepended to the name of the data type.
213: If this routine does not exist in the
214: .Tn RPC/XDR
215: library, it must be provided.
216: Providing an undefined data type
217: allows customization of
218: .Tn XDR
219: routines.
1.6 aaron 220: .Pp
221: The options are as follows:
1.7 ! aaron 222: .Bl -tag -width Ds
1.1 deraadt 223: .It Fl a
224: Generate all the files including sample code for client and server side.
225: .It Fl b
226: This generates code for the
227: .Tn SunOS4.1
1.6 aaron 228: style of RPC.
229: This is the default.
1.1 deraadt 230: .It Fl c
231: Compile into
232: .Tn XDR
233: routines.
234: .It Fl C
1.6 aaron 235: Generate code in ANSI C.
236: This option also generates code that could be
1.1 deraadt 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
1.6 aaron 260: .Nm
1.1 deraadt 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,
1.6 aaron 282: .Nm
1.1 deraadt 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
1.4 aaron 299: .Ar netid .
1.1 deraadt 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
1.4 aaron 307: Use the newstyle of
308: .Nm rpcgen .
309: This allows procedures to have multiple arguments.
1.6 aaron 310: It also uses the style of parameter passing that closely resembles C.
311: So, when
1.1 deraadt 312: passing an argument to a remote procedure you do not have to pass a pointer to
1.6 aaron 313: the argument but the argument itself.
314: This behaviour is different from the oldstyle
1.4 aaron 315: of
1.6 aaron 316: .Nm
317: generated code.
318: The newstyle is not the default case because of
1.1 deraadt 319: backward compatibility.
320: .It Fl o Ar outfile
321: Specify the name of the output file.
322: If none is specified,
323: standard output is used
324: .Po
325: .Fl c Fl h Fl l
326: .Fl m Fl n Fl s
327: modes only
1.4 aaron 328: .Pc .
1.1 deraadt 329: .It Fl s Ar nettype
330: Compile into server-side stubs for all the
331: transports belonging to the class
332: .Ar nettype .
333: The supported classes are
1.4 aaron 334: .Em netpath ,
335: .Em visible ,
336: .Em circuit_n ,
337: .Em circuit_v ,
338: .Em datagram_n ,
339: .Em datagram_v ,
340: .Em tcp ,
1.1 deraadt 341: and
342: .Em udp
343: [see
344: .Xr rpc 3
1.6 aaron 345: for the meanings associated with these classes.
346: Note:
1.1 deraadt 347: .Bx
348: currently supports only the
349: .Em tcp
350: and
351: .Em udp
352: classes].
353: This option may be specified more than once.
354: Note:
355: the transports are chosen at run time and not at compile time.
356: .It Fl S\&c
357: Generate sample code to show the use of remote procedure and how to bind
1.4 aaron 358: to the server before calling the client side stubs generated by
359: .Nm rpcgen .
1.1 deraadt 360: .It Fl S\&s
1.6 aaron 361: Generate skeleton code for the remote procedures on the server side.
362: You would need
1.1 deraadt 363: to fill in the actual code for the remote procedures.
364: .It Fl t
365: Compile into
366: .Tn RPC
367: dispatch table.
368: .It Fl T
369: Generate the code to support
370: .Tn RPC
371: dispatch tables.
372: .El
373: .Pp
374: The options
375: .Fl c ,
376: .Fl h ,
377: .Fl l ,
378: .Fl m ,
379: .Fl s ,
380: and
381: .Fl t
382: are used exclusively to generate a particular type of file,
383: while the options
384: .Fl D
385: and
386: .Fl T
387: are global and can be used with the other options.
388: .Sh NOTES
389: The
390: .Tn RPC
391: Language does not support nesting of structures.
392: As a work-around,
393: structures can be declared at the top-level,
394: and their name used inside other structures in
395: order to achieve the same effect.
396: .Pp
397: Name clashes can occur when using program definitions,
398: since the apparent scoping does not really apply.
399: Most of these can be avoided by giving
400: unique names for programs,
401: versions,
402: procedures and types.
403: .Pp
404: The server code generated with
405: .Fl n
406: option refers to the transport indicated by
407: .Em netid
408: and hence is very site specific.
1.6 aaron 409: .Sh EXAMPLES
1.1 deraadt 410: The command
411: .Pp
412: .Bd -literal -offset indent
413: $ rpcgen -T prot.x
414: .Ed
415: .Pp
416: generates the five files:
417: .Pa prot.h ,
418: .Pa prot_clnt.c ,
419: .Pa prot_svc.c ,
420: .Pa prot_xdr.c
421: and
422: .Pa prot_tbl.i .
423: .Pp
424: The following example sends the C data-definitions (header file)
1.4 aaron 425: to standard output:
1.1 deraadt 426: .Pp
427: .Bd -literal -offset indent
428: $ rpcgen -h prot.x
429: .Ed
430: .Pp
431: To send the test version of the
432: .Dv -DTEST ,
433: server side stubs for
434: all the transport belonging to the class
435: .Em datagram_n
436: to standard output, use:
437: .Pp
438: .Bd -literal -offset indent
439: $ rpcgen -s datagram_n -DTEST prot.x
440: .Ed
441: .Pp
442: To create the server side stubs for the transport indicated by
443: .Em netid
444: .Em tcp ,
445: use:
446: .Pp
447: .Bd -literal -offset indent
448: $ rpcgen -n tcp -o prot_svc.c prot.x
449: .Ed
450: .Sh SEE ALSO
451: .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