1 '\" te
2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH RPCGEN 1 "Dec 16, 2013"
8 .SH NAME
9 rpcgen \- an RPC protocol compiler
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBrpcgen\fR \fIinfile\fR
14 .fi
15
16 .LP
17 .nf
18 \fBrpcgen\fR [\fB-a\fR] [\fB-A\fR] [\fB-b\fR] [\fB-C\fR] [\fB-D\fR \fIname\fR [= \fIvalue\fR]] [\fB-i\fR \fIsize\fR]
19 [\fB-I\fR [\fB-K\fR \fIseconds\fR]] [\fB-L\fR] [\fB-M\fR] [\fB-N\fR] [\fB- T\fR] [\fB-v\fR]
20 [\fB-Y\fR \fIpathname\fR] \fIinfile\fR
21 .fi
22
23 .LP
24 .nf
25 \fBrpcgen\fR [\fB-c\fR | \fB-h\fR | \fB-l\fR | \fB-m\fR | \fB-t\fR | \fB-Sc\fR | \fB-Ss\fR | \fB-Sm\fR]
26 [\fB-o\fR \fIoutfile\fR] [\fIinfile\fR]
27 .fi
28
29 .LP
30 .nf
31 \fBrpcgen\fR [\fB-s\fR \fInettype\fR] [\fB-o\fR \fIoutfile\fR] [\fIinfile\fR]
32 .fi
33
34 .LP
35 .nf
36 \fBrpcgen\fR [\fB-n\fR \fInetid\fR] [\fB-o\fR \fIoutfile\fR] [\fIinfile\fR]
37 .fi
38
39 .SH DESCRIPTION
40 .sp
41 .LP
42 The \fBrpcgen\fR utility is a tool that generates C code to implement an
43 \fBRPC\fR protocol. The input to \fBrpcgen\fR is a language similar to C known
44 as \fBRPC\fR Language (Remote Procedure Call Language).
45 .sp
46 .LP
47 The \fBrpcgen\fR utility is normally used as in the first synopsis where it
48 takes an input file and generates four output files. If the \fIinfile\fR is
49 named \fBproto.x\fR, then \fBrpcgen\fR generates a header in \fBproto.h\fR,
50 \fBXDR\fR routines in \fBproto_xdr.c\fR, server-side stubs in
51 \fBproto_svc.c\fR, and client-side stubs in \fBproto_clnt.c\fR. With the
52 \fB-T\fR option, it also generates the \fBRPC\fR dispatch table in
53 \fBproto_tbl.i\fR.
54 .sp
55 .LP
56 \fBrpcgen\fR can also generate sample client and server files that can be
57 customized to suit a particular application. The \fB-Sc\fR, \fB-Ss\fR, and
58 \fB-Sm\fR options generate sample client, server and makefile, respectively.
59 The \fB-a\fR option generates all files, including sample files. If the infile
60 is \fBproto.x\fR, then the client side sample file is written to
61 \fBproto_client.c\fR, the server side sample file to \fBproto_server.c\fR and
62 the sample makefile to \fBmakefile.proto\fR.
63 .sp
64 .LP
65 The server created can be started both by the port monitors (for example,
66 \fBinetd\fR or \fBlisten\fR) or by itself. When it is started by a port
67 monitor, it creates servers only for the transport for which the file
68 descriptor \fB0\fR was passed. The name of the transport must be specified by
69 setting up the environment variable \fBPM_TRANSPORT\fR. When the server
70 generated by \fBrpcgen\fR is executed, it creates server handles for all the
71 transports specified in the \fBNETPATH\fR environment variable, or if it is
72 unset, it creates server handles for all the visible transports from the
73 \fB/etc/netconfig\fR file. Note: the transports are chosen at run time and not
74 at compile time. When the server is self-started, it backgrounds itself by
75 default. A special define symbol \fBRPC_SVC_FG\fR can be used to run the server
76 process in foreground.
77 .sp
78 .LP
79 The second synopsis provides special features which allow for the creation of
80 more sophisticated \fBRPC\fR servers. These features include support for
81 user-provided \fB#defines\fR and \fBRPC\fR dispatch tables. The entries in the
82 \fBRPC\fR dispatch table contain:
83 .RS +4
84 .TP
85 .ie t \(bu
86 .el o
87 pointers to the service routine corresponding to that procedure
88 .RE
89 .RS +4
90 .TP
91 .ie t \(bu
92 .el o
93 a pointer to the input and output arguments
94 .RE
95 .RS +4
96 .TP
97 .ie t \(bu
98 .el o
99 the size of these routines
100 .RE
101 .sp
102 .LP
103 A server can use the dispatch table to check authorization and then to execute
104 the service routine. A client library can use the dispatch table to deal with
105 the details of storage management and \fBXDR\fR data conversion.
106 .sp
107 .LP
108 The other three synopses shown above are used when one does not want to
109 generate all the output files, but only a particular one. See the EXAMPLES
110 section below for examples of \fBrpcgen\fR usage. When \fBrpcgen\fR is executed
111 with the \fB-s\fR option, it creates servers for that particular class of
112 transports. When executed with the \fB-n\fR option, it creates a server for the
113 transport specified by \fInetid\fR. If \fIinfile\fR is not specified,
114 \fBrpcgen\fR accepts the standard input.
115 .sp
116 .LP
117 All the options mentioned in the second synopsis can be used with the other
118 three synopses, but the changes are made only to the specified output file.
119 .sp
120 .LP
121 The C preprocessor \fBcc\fR \fB-E\fR is run on the input file before it is
122 actually interpreted by \fBrpcgen\fR. For each type of output file,
123 \fBrpcgen\fR defines a special preprocessor symbol for use by the \fBrpcgen\fR
124 programmer:
125 .sp
126 .ne 2
127 .na
128 \fB\fBRPC_HDR\fR\fR
129 .ad
130 .RS 12n
131 defined when compiling into headers
132 .RE
133
134 .sp
135 .ne 2
136 .na
137 \fB\fBRPC_XDR\fR\fR
138 .ad
139 .RS 12n
140 defined when compiling into \fBXDR\fR routines
141 .RE
142
143 .sp
144 .ne 2
145 .na
146 \fB\fBRPC_SVC\fR\fR
147 .ad
148 .RS 12n
149 defined when compiling into server-side stubs
150 .RE
151
152 .sp
153 .ne 2
154 .na
155 \fB\fBRPC_CLNT\fR\fR
156 .ad
157 .RS 12n
158 defined when compiling into client-side stubs
159 .RE
160
161 .sp
162 .ne 2
163 .na
164 \fB\fBRPC_TBL\fR\fR
165 .ad
166 .RS 12n
167 defined when compiling into \fBRPC\fR dispatch tables
168 .RE
169
170 .sp
171 .LP
172 Any line beginning with ``\fB%\fR'' is passed directly into the output file,
173 uninterpreted by \fBrpcgen\fR, except that the leading ``\fB%\fR" is stripped
174 off. To specify the path name of the C preprocessor, use the \fB-Y\fR flag.
175 .sp
176 .LP
177 For every data type referred to in \fIinfile\fR, \fBrpcgen\fR assumes that
178 there exists a routine with the string \fBxdr_\fR prepended to the name of the
179 data type. If this routine does not exist in the \fBRPC\fR/\fBXDR\fR library,
180 it must be provided. Providing an undefined data type allows customization of
181 \fBXDR\fR routines.
182 .SS "Server Error Reporting"
183 .sp
184 .LP
185 By default, errors detected by \fBproto_svc.c\fR is reported to standard error
186 and/or the system log.
187 .sp
188 .LP
189 This behavior can be overridden by compiling the file with a definition of
190 \fBRPC_MSGOUT\fR, for example, \fB-DRPC_MSGOUT=mymsgfunc\fR. The function
191 specified is called to report errors. It must conform to the following
192 \fBprintf\fR-like signature:
193 .sp
194 .in +2
195 .nf
196 extern void RPC_MSGOUT(const char *fmt, ...);
197 .fi
198 .in -2
199 .sp
200
201 .SH OPTIONS
202 .sp
203 .LP
204 The following options are supported:
205 .sp
206 .ne 2
207 .na
208 \fB\fB-a\fR\fR
209 .ad
210 .RS 18n
211 Generates all files, including sample files.
212 .RE
213
214 .sp
215 .ne 2
216 .na
217 \fB\fB-A\fR\fR
218 .ad
219 .RS 18n
220 Enables the Automatic \fBMT\fR mode in the server main program. In this mode,
221 the \fBRPC\fR library automatically creates threads to service client requests.
222 This option generates multithread-safe stubs by implicitly turning on the
223 \fB-M\fR option. Server multithreading modes and parameters can be set using
224 the \fBrpc_control\fR(3NSL) call. \fBrpcgen\fR generated code does not change
225 the default values for the Automatic \fBMT\fR mode.
226 .RE
227
228 .sp
229 .ne 2
230 .na
231 \fB\fB-b\fR\fR
232 .ad
233 .RS 18n
234 Backward compatibility mode. Generates transport-specific \fBRPC\fR code for
235 older versions of the operating system.
236 .RE
237
238 .sp
239 .ne 2
240 .na
241 \fB\fB-c\fR\fR
242 .ad
243 .RS 18n
244 Compiles into \fBXDR\fR routines.
245 .RE
246
247 .sp
248 .ne 2
249 .na
250 \fB\fB-C\fR\fR
251 .ad
252 .RS 18n
253 Generates header and stub files which can be used with ANSI C compilers.
254 Headers generated with this flag can also be used with C++ programs.
255 .RE
256
257 .sp
258 .ne 2
259 .na
260 \fB\fB-D\fR\fIname\fR\fB[=\fR\fIvalue\fR\fB]\fR\fR
261 .ad
262 .RS 18n
263 Defines a symbol \fIname\fR. Equivalent to the \fB#define\fR directive in the
264 source. If no \fIvalue\fR is given, \fIvalue\fR is defined as \fB1\fR. This
265 option can be specified more than once.
266 .RE
267
268 .sp
269 .ne 2
270 .na
271 \fB\fB-h\fR\fR
272 .ad
273 .RS 18n
274 Compiles into \fBC\fR data-definitions (a header). The \fB-T\fR option can be
275 used in conjunction to produce a header which supports \fBRPC\fR dispatch
276 tables.
277 .RE
278
279 .sp
280 .ne 2
281 .na
282 \fB\fB-i\fR \fIsize\fR\fR
283 .ad
284 .RS 18n
285 Size at which to start generating inline code. This option is useful for
286 optimization. The default \fIsize\fR is 5.
287 .RE
288
289 .sp
290 .ne 2
291 .na
292 \fB\fB-I\fR\fR
293 .ad
294 .RS 18n
295 Compiles support for \fBinetd\fR(1M) in the server side stubs. Such servers can
296 be self-started or can be started by \fBinetd\fR. When the server is
297 self-started, it backgrounds itself by default. A special define symbol
298 \fBRPC_SVC_FG\fR can be used to run the server process in foreground, or the
299 user can simply compile without the \fB-I\fR option.
300 .sp
301 If there are no pending client requests, the \fBinetd\fR servers exit after 120
302 seconds (default). The default can be changed with the \fB-K\fR option. All of
303 the error messages for \fBinetd\fR servers are always logged with
304 \fBsyslog\fR(3C).
305 .sp
306 \fBNote:\fR This option is supported for backward compatibility only. It should
307 always be used in conjunction with the \fB-b\fR option which generates backward
308 compatibility code. By default (that is, when \fB-b\fR is not specified),
309 \fBrpcgen\fR generates servers that can be invoked through portmonitors.
310 .RE
311
312 .sp
313 .ne 2
314 .na
315 \fB\fB-K\fR \fIseconds\fR\fR
316 .ad
317 .RS 18n
318 By default, services created using \fBrpcgen\fR and invoked through port
319 monitors wait 120 seconds after servicing a request before exiting. That
320 interval can be changed using the \fB-K\fR flag. To create a server that exits
321 immediately upon servicing a request, use \fB-K\fR \fB0\fR. To create a server
322 that never exits, the appropriate argument is \fB-K\fR \fB\(mi1\fR\&.
323 .sp
324 When monitoring for a server, some portmonitors, like \fBlisten\fR(1M),
325 \fBalways\fR spawn a new process in response to a service request. If it is
326 known that a server are used with such a monitor, the server should exit
327 immediately on completion. For such servers, \fBrpcgen\fR should be used with
328 \fB-K\fR \fB0\fR.
329 .RE
330
331 .sp
332 .ne 2
333 .na
334 \fB\fB-l\fR\fR
335 .ad
336 .RS 18n
337 Compiles into client-side stubs.
338 .RE
339
340 .sp
341 .ne 2
342 .na
343 \fB\fB-L\fR\fR
344 .ad
345 .RS 18n
346 When the servers are started in foreground, uses \fBsyslog\fR(3C) to log the
347 server errors instead of printing them on the standard error.
348 .RE
349
350 .sp
351 .ne 2
352 .na
353 \fB\fB-m\fR\fR
354 .ad
355 .RS 18n
356 Compiles into server-side stubs, but do not generate a "main" routine. This
357 option is useful for doing callback-routines and for users who need to write
358 their own "main" routine to do initialization.
359 .RE
360
361 .sp
362 .ne 2
363 .na
364 \fB\fB-M\fR\fR
365 .ad
366 .RS 18n
367 Generates multithread-safe stubs for passing arguments and results between
368 \fBrpcgen\fR-generated code and user written code. This option is useful for
369 users who want to use threads in their code.
370 .RE
371
372 .sp
373 .ne 2
374 .na
375 \fB\fB-N\fR\fR
376 .ad
377 .RS 18n
378 This option allows procedures to have multiple arguments. It also uses the
379 style of parameter passing that closely resembles C. So, when passing an
380 argument to a remote procedure, you do not have to pass a pointer to the
381 argument, but can pass the argument itself. This behavior is different from the
382 old style of \fBrpcgen\fR-generated code. To maintain backward compatibility,
383 this option is not the default.
384 .RE
385
386 .sp
387 .ne 2
388 .na
389 \fB\fB-n\fR \fInetid\fR\fR
390 .ad
391 .RS 18n
392 Compiles into server-side stubs for the transport specified by \fInetid\fR.
393 There should be an entry for \fInetid\fR in the \fBnetconfig\fR database. This
394 option can be specified more than once, so as to compile a server that serves
395 multiple transports.
396 .RE
397
398 .sp
399 .ne 2
400 .na
401 \fB\fB-o\fR \fIoutfile\fR\fR
402 .ad
403 .RS 18n
404 Specifies the name of the output file. If none is specified, standard output is
405 used (\fB-c\fR, \fB-h\fR, \fB-l\fR, \fB-m\fR, \fB-n\fR, \fB-s\fR, \fB-Sc\fR,
406 \fB-Sm\fR, \fB-Ss\fR, and \fB-t\fR modes only).
407 .RE
408
409 .sp
410 .ne 2
411 .na
412 \fB\fB-s\fR \fInettype\fR\fR
413 .ad
414 .RS 18n
415 Compiles into server-side stubs for all the transports belonging to the class
416 \fInettype\fR. The supported classes are \fBnetpath\fR, \fBvisible\fR,
417 \fBcircuit_n\fR, \fBcircuit_v\fR, \fBdatagram_n\fR, \fBdatagram_v\fR,
418 \fBtcp\fR, and \fBudp\fR (see \fBrpc\fR(3NSL) for the meanings associated with
419 these classes). This option can be specified more than once. \fBNote:\fR The
420 transports are chosen at run time and not at compile time.
421 .RE
422
423 .sp
424 .ne 2
425 .na
426 \fB\fB-Sc\fR\fR
427 .ad
428 .RS 18n
429 Generates sample client code that uses remote procedure calls.
430 .RE
431
432 .sp
433 .ne 2
434 .na
435 \fB\fB-Sm\fR\fR
436 .ad
437 .RS 18n
438 Generates a sample Makefile which can be used for compiling the application.
439 .RE
440
441 .sp
442 .ne 2
443 .na
444 \fB\fB-Ss\fR\fR
445 .ad
446 .RS 18n
447 Generates sample server code that uses remote procedure calls.
448 .RE
449
450 .sp
451 .ne 2
452 .na
453 \fB\fB-t\fR\fR
454 .ad
455 .RS 18n
456 Compiles into \fBRPC\fR dispatch table.
457 .RE
458
459 .sp
460 .ne 2
461 .na
462 \fB\fB-T\fR\fR
463 .ad
464 .RS 18n
465 Generates the code to support \fBRPC\fR dispatch tables.
466 .sp
467 The options \fB-c\fR, \fB-h\fR, \fB-l\fR, \fB-m\fR, \fB-s\fR, \fB-Sc\fR,
468 \fB-Sm\fR, \fB-Ss\fR, and \fB-t\fR are used exclusively to generate a
469 particular type of file, while the options \fB-D\fR and \fB-T\fR are global and
470 can be used with the other options.
471 .RE
472
473 .sp
474 .ne 2
475 .na
476 \fB\fB-v\fR\fR
477 .ad
478 .RS 18n
479 Displays the version number.
480 .RE
481
482 .sp
483 .ne 2
484 .na
485 \fB\fB-Y\fR \fIpathname\fR\fR
486 .ad
487 .RS 18n
488 Gives the name of the directory where \fBrpcgen\fR starts looking for the C
489 preprocessor.
490 .RE
491
492 .SH OPERANDS
493 .sp
494 .LP
495 The following operand is supported:
496 .sp
497 .ne 2
498 .na
499 \fB\fIinfile\fR\fR
500 .ad
501 .RS 10n
502 input file
503 .RE
504
505 .SH EXAMPLES
506 .LP
507 \fBExample 1 \fRGenerating the output files and dispatch table
508 .sp
509 .LP
510 The following entry
511
512 .sp
513 .in +2
514 .nf
515 example% \fBrpcgen -T prot.x\fR
516 .fi
517 .in -2
518 .sp
519
520 .sp
521 .LP
522 generates all the five files: \fBprot.h\fR, \fBprot_clnt.c\fR,
523 \fBprot_svc.c\fR, \fBprot_xdr.c\fR, and \fBprot_tbl.i\fR.
524
525 .LP
526 \fBExample 2 \fRSending headers to standard output
527 .sp
528 .LP
529 The following example sends the C data-definitions (header) to the standard
530 output:
531
532 .sp
533 .in +2
534 .nf
535 example% \fBrpcgen -h prot.x\fR
536 .fi
537 .in -2
538 .sp
539
540 .LP
541 \fBExample 3 \fRSending a test version
542 .sp
543 .LP
544 To send the test version of the \fB-DTEST\fR, server side stubs for all the
545 transport belonging to the class \fBdatagram_n\fR to standard output, use:
546
547 .sp
548 .in +2
549 .nf
550 example% \fBrpcgen -s datagram_n -DTEST prot.x\fR
551 .fi
552 .in -2
553 .sp
554
555 .LP
556 \fBExample 4 \fRCreating server side stubs
557 .sp
558 .LP
559 To create the server side stubs for the transport indicated by \fInetid\fR
560 \fBtcp\fR, use:
561
562 .sp
563 .in +2
564 .nf
565 example% \fBrpcgen -n tcp -o prot_svc.c prot.x\fR
566 .fi
567 .in -2
568 .sp
569
570 .SH EXIT STATUS
571 .sp
572 .ne 2
573 .na
574 \fB\fB0\fR\fR
575 .ad
576 .RS 6n
577 Successful operation.
578 .RE
579
580 .sp
581 .ne 2
582 .na
583 \fB\fB>0\fR\fR
584 .ad
585 .RS 6n
586 An error occurred.
587 .RE
588
589 .SH SEE ALSO
590 .sp
591 .LP
592 \fBinetd\fR(1M), \fBlisten\fR(1M), \fBrpc\fR(3NSL), \fBrpc_control\fR(3NSL),
593 \fBrpc_svc_calls\fR(3NSL), \fBsyslog\fR(3C), \fBnetconfig\fR(4),
594 \fBattributes\fR(5)
595 .sp
596 .LP
597 The \fBrpcgen\fR chapter in the \fIONC+ Developer\&'s Guide\fR manual.
|
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .Dd "Aug 2, 2014"
8 .Dt RPCGEN 1
9 .Os
10 .Sh NAME
11 .Nm rpcgen
12 .Nd an RPC protocol compiler
13 .Sh SYNOPSIS
14 .Nm
15 .Ar infile
16 .
17 .Nm
18 .Op Fl a
19 .Op Fl A
20 .Op Fl b
21 .Op Fl C
22 .Op Fl D Ar name Ns Op = Ns Ar value
23 .Op Fl i Ar size
24 .Op Fl I Op Fl K Ar seconds
25 .Op Fl L
26 .Op Fl M
27 .Op Fl N
28 .Op Fl T
29 .Op Fl v
30 .Op Fl Y Ar pathname
31 .Ar infile
32 .
33 .Nm
34 .Op Fl c | Fl h | Fl l | Fl m | Fl t | Fl "Sc" | Fl "Ss" | Fl "Sm"
35 .Op Fl o Ar outfile
36 .Op Ar infile
37 .
38 .Nm
39 .Op Fl s Ar nettype
40 .Op Fl o Ar outfile
41 .Op Ar infile
42 .
43 .Nm
44 .Op Fl n Ar netid
45 .Op Fl o Ar outfile
46 .Op infile
47 .
48 .Sh DESCRIPTION
49 The
50 .Nm
51 utility is a tool that generates C code to implement an
52 RPC protocol. The input to
53 .Nm
54 is a language similar to C known
55 as
56 .Em RPC Language
57 (Remote Procedure Call Language).
58 .Lp
59 The
60 .Nm
61 utility is normally used as in the first synopsis where it
62 takes an input file and generates four output files. If the
63 .Ar infile
64 is
65 named
66 .Pa proto.x ,
67 then
68 .Nm
69 generates a header in
70 .Pa proto.h ,
71 XDR routines in
72 .Pa proto_xdr.c ,
73 server-side stubs in
74 .Pa proto_svc.c ,
75 and client-side stubs in
76 .Pa proto_clnt.c .
77 With the
78 .Fl T
79 option, it also generates the RPC dispatch table in
80 .Pa proto_tbl.i .
81 .Lp
82 .Nm
83 can also generate sample client and server files that can be
84 customized to suit a particular application. The
85 .Fl "Sc" ,
86 .Fl "Ss" ,
87 and
88 .Fl "Sm"
89 options generate sample client, server and makefile, respectively.
90 The
91 .Fl a
92 option generates all files, including sample files. If the infile
93 is
94 .Pa proto.x ,
95 then the client side sample file is written to
96 .Pa proto_client.c ,
97 the server side sample file to
98 .Pa proto_server.c
99 and the sample makefile to
100 .Pa makefile.proto .
101 .Lp
102 The server created can be started both by the port monitors (for example,
103 .Xr inetd 1M
104 or
105 .Xr listen 1M )
106 or by itself. When it is started by a port
107 monitor, it creates servers only for the transport for which the file
108 descriptor 0 was passed. The name of the transport must be specified by
109 setting up the environment variable
110 .Ev PM_TRANSPORT .
111 When the server
112 generated by
113 .Nm
114 is executed, it creates server handles for all the
115 transports specified in the
116 .Ev NETPATH
117 environment variable, or if it is
118 unset, it creates server handles for all the visible transports from the
119 .Pa /etc/netconfig
120 file. Note: the transports are chosen at run time and not
121 at compile time. When the server is self-started, it backgrounds itself by
122 default. A special define symbol
123 .Dv RPC_SVC_FG
124 can be used to run the server process in foreground.
125 .Lp
126 The second synopsis provides special features which allow for the creation of
127 more sophisticated RPC servers. These features include support for
128 user-provided
129 .Li #defines
130 and RPC dispatch tables. The entries in the
131 RPC dispatch table contain:
132 .Bl -bullet -offset indent
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 .Lp
141 A server can use the dispatch table to check authorization and then to execute
142 the service routine. A client library can use the dispatch table to deal with
143 the details of storage management and XDR data conversion.
144 .Lp
145 The other three synopses shown above are used when one does not want to
146 generate all the output files, but only a particular one. See the
147 .Sx EXAMPLES
148 section below for examples of
149 .Nm
150 usage. When
151 .Nm
152 is executed with the
153 .Fl s
154 option, it creates servers for that particular class of
155 transports. When executed with the
156 .Fl n
157 option, it creates a server for the
158 transport specified by
159 .Ar netid .
160 If
161 .Ar infile
162 is not specified,
163 .Nm
164 accepts the standard input.
165 .Lp
166 All the options mentioned in the second synopsis can be used with the other
167 three synopses, but the changes are made only to the specified output file.
168 .Lp
169 The C preprocessor
170 .Ic cc Fl E
171 is run on the input file before it is
172 actually interpreted by
173 .Nm .
174 For each type of output file,
175 .Nm
176 defines a special preprocessor symbol for use by the
177 .Nm
178 programmer:
179 .Bl -tag -width Dv -offset indent
180 .It Dv RPC_HDR
181 defined when compiling into headers
182 .It Dv RPC_XDR
183 defined when compiling into XDR routines
184 .It Dv RPC_SVC
185 defined when compiling into server-side stubs
186 .It Dv RPC_CLNT
187 defined when compiling into client-side stubs
188 .It Dv RPC_TBL
189 defined when compiling into RPC dispatch tables
190 .El
191 .Lp
192 Any line beginning with
193 .Dq %
194 is passed directly into the output file,
195 uninterpreted by
196 .Nm ,
197 except that the leading
198 .Dq %
199 is stripped
200 off. To specify the path name of the C preprocessor, use the
201 .Fl Y
202 flag.
203 .Lp
204 For every data type referred to in
205 .Ar infile ,
206 .Nm
207 assumes that
208 there exists a routine with the string
209 .Sy xdr_
210 prepended to the name of the
211 data type. If this routine does not exist in the RPC/XDR library,
212 it must be provided. Providing an undefined data type allows customization of
213 XDR routines.
214 .Ss "Server Error Reporting"
215 By default, errors detected by
216 .Pa proto_svc.c
217 is reported to standard error and/or the system log.
218 .Lp
219 This behavior can be overridden by compiling the file with a definition of
220 .Dv RPC_MSGOUT ,
221 for example,
222 .Fl D Dv RPC_MSGOUT Ns = Ns Ar mymsgfunc .
223 The function
224 specified is called to report errors. It must conform to the following
225 .Xr printf 3C
226 style signature:
227 .Lp
228 .Dl extern void RPC_MSGOUT(const char *fmt, ...);
229 .Sh OPTIONS
230 The following options are supported:
231 .Bl -tag -width Fl
232 .
233 .It Fl a
234 Generates all files, including sample files.
235 .
236 .It Fl A
237 Enables the Automatic
238 MT mode in the server main program. In this mode,
239 the RPC library automatically creates threads to service client requests.
240 This option generates multithread-safe stubs by implicitly turning on the
241 .Fl M
242 option. Server multithreading modes and parameters can be set using
243 the
244 .Xr rpc_control 3NSL
245 call.
246 .Nm
247 generated code does not change
248 the default values for the Automatic MT mode.
249 .
250 .It Fl b
251 Backward compatibility mode. Generates transport-specific RPC code for
252 older versions of the operating system.
253 .
254 .It Fl c
255 Compiles into XDR routines.
256 .
257 .It Fl C
258 Generates header and stub files which can be used with ANSI C compilers.
259 Headers generated with this flag can also be used with C++ programs. This
260 behavior is now default, and therefore this option
261 is redundant. It remains here for compatibility.
262 .It Fl D Ar name Ns Op = Ns Ar value
263 Defines a symbol \fIname\fR. Equivalent to the \fB#define\fR directive in the
264 source. If no \fIvalue\fR is given, \fIvalue\fR is defined as \fB1\fR. This
265 option can be specified more than once.
266 .
267 .It Fl h
268 Compiles into C data-definitions (a header). The
269 .Fl T
270 option can be
271 used in conjunction to produce a header which supports RPC dispatch
272 tables.
273 .
274 .It Fl i Ar size
275 Size at which to start generating inline code. This option is useful for
276 optimization. The default
277 .Ar size
278 is 5.
279 .
280 .It Fl I
281 Compiles support for
282 .Xr inetd 1M
283 in the server side stubs. Such servers can
284 be self-started or can be started by
285 .Xr inetd 3C .
286 When the server is
287 self-started, it backgrounds itself by default. A special define symbol
288 .Dv RPC_SVC_FG
289 can be used to run the server process in foreground, or the
290 user can simply compile without the
291 .Fl I
292 option.
293 .Lp
294 If there are no pending client requests, the
295 .Xr inetd 1M
296 servers exit after 120
297 seconds (default). The default can be changed with the
298 .Fl -K
299 option. All of
300 the error messages for
301 .Xr inetd 1M
302 servers are always logged with
303 .Xr syslog 3C .
304 .Lp
305 .Em Note:
306 This option is supported for backward compatibility only. It should
307 always be used in conjunction with the
308 .Fl b
309 option which generates backward
310 compatibility code. By default (that is, when
311 .Fl b
312 is not specified),
313 .Nm
314 generates servers that can be invoked through portmonitors.
315 .
316 .It Fl K Ar seconds
317 By default, services created using
318 .Nm
319 and invoked through port
320 monitors wait 120 seconds after servicing a request before exiting. That
321 interval can be changed using the
322 .Fl K
323 flag. To create a server that exits
324 immediately upon servicing a request, use
325 .Fl K Li 0 .
326 To create a server
327 that never exits, the appropriate argument is
328 .Fl K Li \(mi1 .
329 .Lp
330 When monitoring for a server, some portmonitors, like
331 .Xr listen 1M ,
332 .Em always
333 spawn a new process in response to a service request. If it is
334 known that a server are used with such a monitor, the server should exit
335 immediately on completion. For such servers,
336 .Nm
337 should be used with
338 .Fl K Li 0 .
339 .
340 .It Fl l
341 Compiles into client-side stubs.
342 .
343 .It Fl L
344 When the servers are started in foreground, uses
345 .Xr syslog 3C
346 to log the server errors instead of printing them on the standard error.
347 .
348 .It Fl m
349 Compiles into server-side stubs, but do not generate a "main" routine. This
350 option is useful for doing callback-routines and for users who need to write
351 their own "main" routine to do initialization.
352 .
353 .It Fl M
354 Generates multithread-safe stubs for passing arguments and results between
355 code generated by
356 .Nm rpcgen
357 and user written code. This option is useful for
358 users who want to use threads in their code.
359 .
360 .It Fl N
361 This option allows procedures to have multiple arguments. It also uses the
362 style of parameter passing that closely resembles C. So, when passing an
363 argument to a remote procedure, you do not have to pass a pointer to the
364 argument, but can pass the argument itself. This behavior is different from the
365 old style of code generated by
366 .Nm .
367 To maintain backward compatibility, this option is not the default.
368 .
369 .It Fl n Ar netid
370 Compiles into server-side stubs for the transport specified by
371 .Ar netid .
372 There should be an entry for
373 .Ar netid
374 in the
375 .Xr netconfig 4
376 database. This
377 option can be specified more than once, so as to compile a server that serves
378 multiple transports.
379 .
380 .It Fl o Ar outfile
381 Specifies the name of the output file. If none is specified, standard output is
382 used
383 .Po
384 .Fl c , h , l , m , n , s , "Sc" , "Sm" , "Ss" ,
385 and
386 .Fl t
387 modes only
388 .Pc .
389 .
390 .It Fl s Ar netttype
391 Compiles into server-side stubs for all the transports belonging to the class
392 .Ar nettype .
393 The supported classes are
394 .Sy netpath ,
395 .Sy visible ,
396 .Sy circuit_n ,
397 .Sy circuit_v ,
398 .Sy datagram_n ,
399 .Sy datagram_v ,
400 .Sy tcp ,
401 and
402 .Sy udp
403 (see
404 .Xr rpc 3NSL
405 for the meanings associated with
406 these classes). This option can be specified more than once.
407 .Em Note:
408 The transports are chosen at run time and not at compile time.
409 .
410 .It Fl "Sc"
411 Generates sample client code that uses remote procedure calls.
412 .
413 .It Fl "Sm"
414 Generates a sample Makefile which can be used for compiling the application.
415 .
416 .It Fl "Ss"
417 Generates sample server code that uses remote procedure calls.
418 .
419 .It Fl t
420 Compiles into RPC dispatch table.
421 .
422 .It Fl T
423 Generates the code to support RPC dispatch tables.
424 .Lp
425 The options
426 .Fl c , h , l , m , s R, "Sc" , "Sm" , "Ss" ,
427 and
428 .Fl t
429 are used exclusively to generate a
430 particular type of file, while the options
431 .Fl D
432 and
433 .Fl T
434 are global and can be used with the other options.
435 .
436 .It Fl v
437 Displays the version number.
438 .
439 .It Fl Y Ar pathname
440 Gives the name of the directory where
441 .Nm
442 starts looking for the C preprocessor.
443 .El
444 .Sh OPERANDS
445 The following operand is supported:
446 .Bl -tag -width Ar
447 .
448 .It Ar infile
449 input file
450 .El
451 .Sh EXIT STATUS
452 .Ex -std
453 .Sh EXAMPLES
454 .Ss Example 1 Generating the output files and dispatch table
455 The following entry
456 .Lp
457 .Dl example% rpcgen -T prot.x
458 .Lp
459 generates all the five files:
460 .Pa prot.h , prot_clnt.c R, prot_svc.c , prot_xdr.c ,
461 and
462 .Pa prot_tbl.i .
463 .
464 .Ss Example 2 Sending headers to standard output
465 The following example sends the C data-definitions (header) to the standard
466 output:
467 .Lp
468 .Dl example% rpcgen -h prot.x
469 .
470 .Ss Example 3 Sending a test version
471 To send the test version of the
472 .Fl DTEST ,
473 server side stubs for all the
474 transport belonging to the class
475 .Sy datagram_n
476 to standard output, use:
477 .Lp
478 .Dl example% rpcgen -s datagram_n -DTEST prot.x
479 .
480 .Ss Example 4 Creating server side stubs
481 To create the server side stubs for the transport indicated by
482 .Ar netid
483 .Sy tcp ,
484 use:
485 .Lp
486 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
487 .Sh SEE ALSO
488 .Xr inetd 1M ,
489 .Xr listen 1M ,
490 .Xr rpc 3NSL ,
491 .Xr rpc_control 3NSL ,
492 .Xr rpc_svc_calls 3NSL ,
493 .Xr syslog 3C ,
494 .Xr netconfig 4 ,
495 .Xr attributes 5
496 .Rs
497 .%B ONC+ Developer\&'s Guide
498 .Re
|