1rpcgen(1)                        User Commands                       rpcgen(1)
2
3
4

NAME

6       rpcgen - an RPC protocol compiler
7

SYNOPSIS

9       rpcgen infile
10
11
12       rpcgen [-a] [-A] [-b] [-C] [-D name [= value]] [-i size]
13            [-I [-K seconds]] [-L] [-M] [-N] [- T] [-v]
14            [-Y pathname] infile
15
16
17       rpcgen [-c | -h | -l | -m | -t | -Sc | -Ss | -Sm]
18            [-o outfile] [infile]
19
20
21       rpcgen [-s nettype] [-o outfile] [infile]
22
23
24       rpcgen [-n netid] [-o outfile] [infile]
25
26

DESCRIPTION

28       The  rpcgen utility is a tool that generates C code to implement an RPC
29       protocol. The input to rpcgen is a language similar to C known  as  RPC
30       Language (Remote Procedure Call Language).
31
32
33       The  rpcgen  utility is normally used as in the first synopsis where it
34       takes an input file and generates three output files. If the infile  is
35       named  proto.x, then rpcgen generates a header in proto.h, XDR routines
36       in proto_xdr.c, server-side stubs in proto_svc.c, and client-side stubs
37       in proto_clnt.c. With the -T option, it also generates the RPC dispatch
38       table in proto_tbl.i.
39
40
41       rpcgen can also generate sample client and server  files  that  can  be
42       customized  to  suit  a  particular  application. The -Sc, -Ss, and -Sm
43       options generate sample client, server and makefile, respectively.  The
44       -a option generates all files, including sample files. If the infile is
45       proto.x, then the client side sample file is written to proto_client.c,
46       the  server  side sample file to proto_server.c and the sample makefile
47       to makefile.proto.
48
49
50       The server created can be started both by the port monitors (for  exam‐
51       ple,  inetd or listen) or by itself. When it is started by a port moni‐
52       tor, it creates servers only for  the  transport  for  which  the  file
53       descriptor 0 was passed. The name of the transport must be specified by
54       setting up the environment variable PM_TRANSPORT. When the server  gen‐
55       erated  by  rpcgen  is  executed, it creates server handles for all the
56       transports specified in the NETPATH environment variable, or if  it  is
57       unset,  it  creates  server handles for all the visible transports from
58       the /etc/netconfig file. Note: the transports are chosen  at  run  time
59       and  not  at  compile  time.  When the server is self-started, it back‐
60       grounds itself by default. A special define symbol  RPC_SVC_FG  can  be
61       used to run the server process in foreground.
62
63
64       The  second synopsis provides special features which allow for the cre‐
65       ation of more sophisticated RPC servers. These features include support
66       for  user-provided #defines and RPC dispatch tables. The entries in the
67       RPC dispatch table contain:
68
69           o      pointers to the service routine corresponding to that proce‐
70                  dure
71
72           o      a pointer to the input and output arguments
73
74           o      the size of these routines
75
76
77       A  server can use the dispatch table to check authorization and then to
78       execute the service routine. A client library can use the dispatch  ta‐
79       ble to deal with the details of storage management and XDR data conver‐
80       sion.
81
82
83       The other three synopses shown above are used when one does not want to
84       generate all the output files, but only a particular one. See the EXAM‐
85       PLES section below for examples of rpcgen usage. When  rpcgen  is  exe‐
86       cuted  with the -s option, it creates servers for that particular class
87       of transports. When executed with the -n option, it  creates  a  server
88       for  the transport specified by netid. If infile is not specified, rpc‐
89       gen accepts the standard input.
90
91
92       All the options mentioned in the second synopsis can be used  with  the
93       other  three  synopses,  but the changes are made only to the specified
94       output file.
95
96
97       The C preprocessor cc -E is run on the input file before it is actually
98       interpreted  by  rpcgen. For each type of output file, rpcgen defines a
99       special preprocessor symbol for use by the rpcgen programmer:
100
101       RPC_HDR     defined when compiling into headers
102
103
104       RPC_XDR     defined when compiling into XDR routines
105
106
107       RPC_SVC     defined when compiling into server-side stubs
108
109
110       RPC_CLNT    defined when compiling into client-side stubs
111
112
113       RPC_TBL     defined when compiling into RPC dispatch tables
114
115
116
117       Any line beginning with ``%'' is passed directly into the output  file,
118       uninterpreted  by rpcgen, except that the leading ``%" is stripped off.
119       To specify the path name of the C preprocessor, use the -Y flag.
120
121
122       For every data type referred to in infile, rpcgen  assumes  that  there
123       exists a routine with the string xdr_ prepended to the name of the data
124       type. If this routine does not exist in the RPC/XDR library, it must be
125       provided.  Providing an undefined data type allows customization of XDR
126       routines.
127
128   Server Error Reporting
129       By default, errors detected by  proto_svc.c  is  reported  to  standard
130       error and/or the system log.
131
132
133       This behavior can be overridden by compiling the file with a definition
134       of RPC_MSGOUT, for example, -DRPC_MSGOUT=mymsgfunc. The function speci‐
135       fied  is  called  to  report  errors.  It must conform to the following
136       printf-like signature:
137
138         extern void RPC_MSGOUT(const char *fmt, ...);
139
140
141

OPTIONS

143       The following options are supported:
144
145       -a                Generates all files, including sample files.
146
147
148       -A                Enables the Automatic MT mode in the server main pro‐
149                         gram.  In  this  mode,  the RPC library automatically
150                         creates threads  to  service  client  requests.  This
151                         option generates multithread-safe stubs by implicitly
152                         turning on the -M option. Server multithreading modes
153                         and parameters can be set using the rpc_control(3NSL)
154                         call. rpcgen  generated  code  does  not  change  the
155                         default values for the Automatic MT mode.
156
157
158       -b                Backward compatibility mode. Generates transport-spe‐
159                         cific RPC code for older versions  of  the  operating
160                         system.
161
162
163       -c                Compiles into XDR routines.
164
165
166       -C                Generates  header  and  stub  files which can be used
167                         with ANSI C compilers. Headers  generated  with  this
168                         flag can also be used with C++ programs.
169
170
171       -Dname[=value]    Defines  a  symbol  name.  Equivalent  to the #define
172                         directive in the source. If no value is given,  value
173                         is  defined  as  1. This option can be specified more
174                         than once.
175
176
177       -h                Compiles into C data-definitions (a header).  The  -T
178                         option can be used in conjunction to produce a header
179                         which supports RPC dispatch tables.
180
181
182       -i size           Size at which to start generating inline  code.  This
183                         option  is  useful for optimization. The default size
184                         is 5.
185
186
187       -I                Compiles support for inetd(1M)  in  the  server  side
188                         stubs.  Such  servers  can  be self-started or can be
189                         started by inetd. When the server is self-started, it
190                         backgrounds  itself by default. A special define sym‐
191                         bol RPC_SVC_FG can be used to run the server  process
192                         in foreground, or the user can simply compile without
193                         the -I option.
194
195                         If there are no pending client  requests,  the  inetd
196                         servers exit after 120 seconds (default). The default
197                         can be changed with the -K option. All of  the  error
198                         messages  for  inetd  servers  are always logged with
199                         syslog(3C).
200
201                         Note: This option is supported for backward  compati‐
202                         bility  only. It should always be used in conjunction
203                         with the -b option which generates backward  compati‐
204                         bility  code.  By  default  (that  is, when -b is not
205                         specified), rpcgen  generates  servers  that  can  be
206                         invoked through portmonitors.
207
208
209       -K seconds        By default, services created using rpcgen and invoked
210                         through port monitors wait 120 seconds after  servic‐
211                         ing  a  request  before exiting. That interval can be
212                         changed using the -K flag. To create  a  server  that
213                         exits immediately upon servicing a request, use -K 0.
214                         To create a server that never exits, the  appropriate
215                         argument is -K −1.
216
217                         When monitoring for a server, some portmonitors, like
218                         listen(1M), always spawn a new process in response to
219                         a  service  request. If it is known that a server are
220                         used with such a  monitor,  the  server  should  exit
221                         immediately  on  completion. For such servers, rpcgen
222                         should be used with -K 0.
223
224
225       -l                Compiles into client-side stubs.
226
227
228       -L                When the servers are started in foreground, uses sys‐
229                         log(3C)  to log the server errors instead of printing
230                         them on the standard error.
231
232
233       -m                Compiles into server-side stubs, but do not  generate
234                         a  "main"  routine.  This  option is useful for doing
235                         callback-routines and for users  who  need  to  write
236                         their own "main" routine to do initialization.
237
238
239       -M                Generates  multithread-safe  stubs  for passing argu‐
240                         ments and results between rpcgen-generated  code  and
241                         user  written  code.  This option is useful for users
242                         who want to use threads in their code.
243
244
245       -N                This option allows procedures to have multiple  argu‐
246                         ments.  It  also  uses the style of parameter passing
247                         that closely resembles C. So, when passing  an  argu‐
248                         ment to a remote procedure, you do not have to pass a
249                         pointer to the argument, but can  pass  the  argument
250                         itself. This behavior is different from the old style
251                         of rpcgen-generated code. To maintain  backward  com‐
252                         patibility, this option is not the default.
253
254
255       -n netid          Compiles  into  server-side  stubs  for the transport
256                         specified by netid. There  should  be  an  entry  for
257                         netid  in  the netconfig database. This option can be
258                         specified more than once, so as to compile  a  server
259                         that serves multiple transports.
260
261
262       -o outfile        Specifies  the  name  of  the output file. If none is
263                         specified, standard output is used (-c, -h,  -l,  -m,
264                         -n, -s, -Sc, -Sm, -Ss, and -t modes only).
265
266
267       -s nettype        Compiles  into  server-side  stubs for all the trans‐
268                         ports belonging to the class nettype.  The  supported
269                         classes  are  netpath, visible, circuit_n, circuit_v,
270                         datagram_n, datagram_v, tcp, and udp  (see  rpc(3NSL)
271                         for the meanings associated with these classes). This
272                         option can be specified more  than  once.  Note:  The
273                         transports  are chosen at run time and not at compile
274                         time.
275
276
277       -Sc               Generates sample client code that uses remote  proce‐
278                         dure calls.
279
280
281       -Sm               Generates  a  sample  Makefile  which can be used for
282                         compiling the application.
283
284
285       -Ss               Generates sample server code that uses remote  proce‐
286                         dure calls.
287
288
289       -t                Compiles into RPC dispatch table.
290
291
292       -T                Generates the code to support RPC dispatch tables.
293
294                         The options -c, -h, -l, -m, -s, -Sc, -Sm, -Ss, and -t
295                         are used exclusively to generate a particular type of
296                         file,  while the options -D and -T are global and can
297                         be used with the other options.
298
299
300       -v                Displays the version number.
301
302
303       -Y pathname       Gives the name of the directory where  rpcgen  starts
304                         looking for the C preprocessor.
305
306

OPERANDS

308       The following operand is supported:
309
310       infile    input file
311
312

EXAMPLES

314       Example 1 Generating the output files and dispatch table
315
316
317       The following entry
318
319
320         example% rpcgen -T prot.x
321
322
323
324
325       generates   all   the  five  files:  prot.h,  prot_clnt.c,  prot_svc.c,
326       prot_xdr.c, and prot_tbl.i.
327
328
329       Example 2 Sending headers to standard output
330
331
332       The following example sends the  C  data-definitions  (header)  to  the
333       standard output:
334
335
336         example% rpcgen -h prot.x
337
338
339
340       Example 3 Sending a test version
341
342
343       To  send  the test version of the -DTEST, server side stubs for all the
344       transport belonging to the class datagram_n to standard output, use:
345
346
347         example% rpcgen -s datagram_n -DTEST prot.x
348
349
350
351       Example 4 Creating server side stubs
352
353
354       To create the server side stubs for the transport  indicated  by  netid
355       tcp, use:
356
357
358         example% rpcgen -n tcp -o prot_svc.c prot.x
359
360
361

EXIT STATUS

363       0     Successful operation.
364
365
366       >0    An error occurred.
367
368

ATTRIBUTES

370       See attributes(5) for descriptions of the following attributes:
371
372
373
374
375       ┌─────────────────────────────┬─────────────────────────────┐
376       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
377       ├─────────────────────────────┼─────────────────────────────┤
378       │Availability                 │SUNWbtool                    │
379       └─────────────────────────────┴─────────────────────────────┘
380

SEE ALSO

382       inetd(1M),        listen(1M),       rpc(3NSL),       rpc_control(3NSL),
383       rpc_svc_calls(3NSL), syslog(3C), netconfig(4), attributes(5)
384
385
386       The rpcgen chapter in the ONC+ Developer's Guide manual.
387
388
389
390SunOS 5.11                        24 Aug 2009                        rpcgen(1)
Impressum