1 | .\" |
---|
2 | .\" Must use -- tbl -- for this one |
---|
3 | .\" |
---|
4 | .\" @(#)rpcgen.ms 2.2 88/08/04 4.0 RPCSRC |
---|
5 | .de BT |
---|
6 | .if \\n%=1 .tl ''- % -'' |
---|
7 | .. |
---|
8 | .ND |
---|
9 | .\" prevent excess underlining in nroff |
---|
10 | .if n .fp 2 R |
---|
11 | .OH '\fBrpcgen\fP Programming Guide''Page %' |
---|
12 | .EH 'Page %''\fBrpcgen\fP Programming Guide' |
---|
13 | .if \\n%=1 .bp |
---|
14 | .SH |
---|
15 | \&\fBrpcgen\fP Programming Guide |
---|
16 | .NH 0 |
---|
17 | \&The \fBrpcgen\fP Protocol Compiler |
---|
18 | .IX rpcgen "" \fIrpcgen\fP "" PAGE MAJOR |
---|
19 | .LP |
---|
20 | .IX RPC "" "" \fIrpcgen\fP |
---|
21 | The details of programming applications to use Remote Procedure Calls |
---|
22 | can be overwhelming. Perhaps most daunting is the writing of the XDR |
---|
23 | routines necessary to convert procedure arguments and results into |
---|
24 | their network format and vice-versa. |
---|
25 | .LP |
---|
26 | Fortunately, |
---|
27 | .I rpcgen(1) |
---|
28 | exists to help programmers write RPC applications simply and directly. |
---|
29 | .I rpcgen |
---|
30 | does most of the dirty work, allowing programmers to debug |
---|
31 | the main features of their application, instead of requiring them to |
---|
32 | spend most of their time debugging their network interface code. |
---|
33 | .LP |
---|
34 | .I rpcgen |
---|
35 | is a compiler. It accepts a remote program interface definition written |
---|
36 | in a language, called RPC Language, which is similar to C. It produces a C |
---|
37 | language output which includes stub versions of the client routines, a |
---|
38 | server skeleton, XDR filter routines for both parameters and results, and a |
---|
39 | header file that contains common definitions. The client stubs interface |
---|
40 | with the RPC library and effectively hide the network from their callers. |
---|
41 | The server stub similarly hides the network from the server procedures that |
---|
42 | are to be invoked by remote clients. |
---|
43 | .I rpcgen 's |
---|
44 | output files can be compiled and linked in the usual way. The developer |
---|
45 | writes server procedures\(emin any language that observes Sun calling |
---|
46 | conventions\(emand links them with the server skeleton produced by |
---|
47 | .I rpcgen |
---|
48 | to get an executable server program. To use a remote program, a programmer |
---|
49 | writes an ordinary main program that makes local procedure calls to the |
---|
50 | client stubs produced by |
---|
51 | .I rpcgen . |
---|
52 | Linking this program with |
---|
53 | .I rpcgen 's |
---|
54 | stubs creates an executable program. (At present the main program must be |
---|
55 | written in C). |
---|
56 | .I rpcgen |
---|
57 | options can be used to suppress stub generation and to specify the transport |
---|
58 | to be used by the server stub. |
---|
59 | .LP |
---|
60 | Like all compilers, |
---|
61 | .I rpcgen |
---|
62 | reduces development time |
---|
63 | that would otherwise be spent coding and debugging low-level routines. |
---|
64 | All compilers, including |
---|
65 | .I rpcgen , |
---|
66 | do this at a small cost in efficiency |
---|
67 | and flexibility. However, many compilers allow escape hatches for |
---|
68 | programmers to mix low-level code with high-level code. |
---|
69 | .I rpcgen |
---|
70 | is no exception. In speed-critical applications, hand-written routines |
---|
71 | can be linked with the |
---|
72 | .I rpcgen |
---|
73 | output without any difficulty. Also, one may proceed by using |
---|
74 | .I rpcgen |
---|
75 | output as a starting point, and then rewriting it as necessary. |
---|
76 | (If you need a discussion of RPC programming without |
---|
77 | .I rpcgen , |
---|
78 | see the |
---|
79 | .I "Remote Procedure Call Programming Guide)\. |
---|
80 | .NH 1 |
---|
81 | \&Converting Local Procedures into Remote Procedures |
---|
82 | .IX rpcgen "local procedures" \fIrpcgen\fP |
---|
83 | .IX rpcgen "remote procedures" \fIrpcgen\fP |
---|
84 | .LP |
---|
85 | Assume an application that runs on a single machine, one which we want |
---|
86 | to convert to run over the network. Here we will demonstrate such a |
---|
87 | conversion by way of a simple example\(ema program that prints a |
---|
88 | message to the console: |
---|
89 | .ie t .DS |
---|
90 | .el .DS L |
---|
91 | .ft I |
---|
92 | /* |
---|
93 | * printmsg.c: print a message on the console |
---|
94 | */ |
---|
95 | .ft CW |
---|
96 | #include <stdio.h> |
---|
97 | |
---|
98 | main(argc, argv) |
---|
99 | int argc; |
---|
100 | char *argv[]; |
---|
101 | { |
---|
102 | char *message; |
---|
103 | |
---|
104 | if (argc < 2) { |
---|
105 | fprintf(stderr, "usage: %s <message>\en", argv[0]); |
---|
106 | exit(1); |
---|
107 | } |
---|
108 | message = argv[1]; |
---|
109 | |
---|
110 | if (!printmessage(message)) { |
---|
111 | fprintf(stderr, "%s: couldn't print your message\en", |
---|
112 | argv[0]); |
---|
113 | exit(1); |
---|
114 | } |
---|
115 | printf("Message Delivered!\en"); |
---|
116 | exit(0); |
---|
117 | } |
---|
118 | .ft I |
---|
119 | /* |
---|
120 | * Print a message to the console. |
---|
121 | * Return a boolean indicating whether the message was actually printed. |
---|
122 | */ |
---|
123 | .ft CW |
---|
124 | printmessage(msg) |
---|
125 | char *msg; |
---|
126 | { |
---|
127 | FILE *f; |
---|
128 | |
---|
129 | f = fopen("/dev/console", "w"); |
---|
130 | if (f == NULL) { |
---|
131 | return (0); |
---|
132 | } |
---|
133 | fprintf(f, "%s\en", msg); |
---|
134 | fclose(f); |
---|
135 | return(1); |
---|
136 | } |
---|
137 | .DE |
---|
138 | .LP |
---|
139 | And then, of course: |
---|
140 | .ie t .DS |
---|
141 | .el .DS L |
---|
142 | .ft CW |
---|
143 | example% \fBcc printmsg.c -o printmsg\fP |
---|
144 | example% \fBprintmsg "Hello, there."\fP |
---|
145 | Message delivered! |
---|
146 | example% |
---|
147 | .DE |
---|
148 | .LP |
---|
149 | If |
---|
150 | .I printmessage() |
---|
151 | was turned into a remote procedure, |
---|
152 | then it could be called from anywhere in the network. |
---|
153 | Ideally, one would just like to stick a keyword like |
---|
154 | .I remote |
---|
155 | in front of a |
---|
156 | procedure to turn it into a remote procedure. Unfortunately, |
---|
157 | we have to live within the constraints of the C language, since |
---|
158 | it existed long before RPC did. But even without language |
---|
159 | support, it's not very difficult to make a procedure remote. |
---|
160 | .LP |
---|
161 | In general, it's necessary to figure out what the types are for |
---|
162 | all procedure inputs and outputs. In this case, we have a |
---|
163 | procedure |
---|
164 | .I printmessage() |
---|
165 | which takes a string as input, and returns an integer |
---|
166 | as output. Knowing this, we can write a protocol specification in RPC |
---|
167 | language that describes the remote version of |
---|
168 | .I printmessage (). |
---|
169 | Here it is: |
---|
170 | .ie t .DS |
---|
171 | .el .DS L |
---|
172 | .ft I |
---|
173 | /* |
---|
174 | * msg.x: Remote message printing protocol |
---|
175 | */ |
---|
176 | .ft CW |
---|
177 | |
---|
178 | program MESSAGEPROG { |
---|
179 | version MESSAGEVERS { |
---|
180 | int PRINTMESSAGE(string) = 1; |
---|
181 | } = 1; |
---|
182 | } = 99; |
---|
183 | .DE |
---|
184 | .LP |
---|
185 | Remote procedures are part of remote programs, so we actually declared |
---|
186 | an entire remote program here which contains the single procedure |
---|
187 | .I PRINTMESSAGE . |
---|
188 | This procedure was declared to be in version 1 of the |
---|
189 | remote program. No null procedure (procedure 0) is necessary because |
---|
190 | .I rpcgen |
---|
191 | generates it automatically. |
---|
192 | .LP |
---|
193 | Notice that everything is declared with all capital letters. This is |
---|
194 | not required, but is a good convention to follow. |
---|
195 | .LP |
---|
196 | Notice also that the argument type is \*Qstring\*U and not \*Qchar *\*U. This |
---|
197 | is because a \*Qchar *\*U in C is ambiguous. Programmers usually intend it |
---|
198 | to mean a null-terminated string of characters, but it could also |
---|
199 | represent a pointer to a single character or a pointer to an array of |
---|
200 | characters. In RPC language, a null-terminated string is |
---|
201 | unambiguously called a \*Qstring\*U. |
---|
202 | .LP |
---|
203 | There are just two more things to write. First, there is the remote |
---|
204 | procedure itself. Here's the definition of a remote procedure |
---|
205 | to implement the |
---|
206 | .I PRINTMESSAGE |
---|
207 | procedure we declared above: |
---|
208 | .ie t .DS |
---|
209 | .el .DS L |
---|
210 | .vs 11 |
---|
211 | .ft I |
---|
212 | /* |
---|
213 | * msg_proc.c: implementation of the remote procedure "printmessage" |
---|
214 | */ |
---|
215 | .ft CW |
---|
216 | |
---|
217 | #include <stdio.h> |
---|
218 | #include <rpc/rpc.h> /* \fIalways needed\fP */ |
---|
219 | #include "msg.h" /* \fIneed this too: msg.h will be generated by rpcgen\fP */ |
---|
220 | |
---|
221 | .ft I |
---|
222 | /* |
---|
223 | * Remote verson of "printmessage" |
---|
224 | */ |
---|
225 | .ft CW |
---|
226 | int * |
---|
227 | printmessage_1(msg) |
---|
228 | char **msg; |
---|
229 | { |
---|
230 | static int result; /* \fImust be static!\fP */ |
---|
231 | FILE *f; |
---|
232 | |
---|
233 | f = fopen("/dev/console", "w"); |
---|
234 | if (f == NULL) { |
---|
235 | result = 0; |
---|
236 | return (&result); |
---|
237 | } |
---|
238 | fprintf(f, "%s\en", *msg); |
---|
239 | fclose(f); |
---|
240 | result = 1; |
---|
241 | return (&result); |
---|
242 | } |
---|
243 | .vs |
---|
244 | .DE |
---|
245 | .LP |
---|
246 | Notice here that the declaration of the remote procedure |
---|
247 | .I printmessage_1() |
---|
248 | differs from that of the local procedure |
---|
249 | .I printmessage() |
---|
250 | in three ways: |
---|
251 | .IP 1. |
---|
252 | It takes a pointer to a string instead of a string itself. This |
---|
253 | is true of all remote procedures: they always take pointers to their |
---|
254 | arguments rather than the arguments themselves. |
---|
255 | .IP 2. |
---|
256 | It returns a pointer to an integer instead of an integer itself. This is |
---|
257 | also generally true of remote procedures: they always return a pointer |
---|
258 | to their results. |
---|
259 | .IP 3. |
---|
260 | It has an \*Q_1\*U appended to its name. In general, all remote |
---|
261 | procedures called by |
---|
262 | .I rpcgen |
---|
263 | are named by the following rule: the name in the program definition |
---|
264 | (here |
---|
265 | .I PRINTMESSAGE ) |
---|
266 | is converted to all |
---|
267 | lower-case letters, an underbar (\*Q_\*U) is appended to it, and |
---|
268 | finally the version number (here 1) is appended. |
---|
269 | .LP |
---|
270 | The last thing to do is declare the main client program that will call |
---|
271 | the remote procedure. Here it is: |
---|
272 | .ie t .DS |
---|
273 | .el .DS L |
---|
274 | .ft I |
---|
275 | /* |
---|
276 | * rprintmsg.c: remote version of "printmsg.c" |
---|
277 | */ |
---|
278 | .ft CW |
---|
279 | #include <stdio.h> |
---|
280 | #include <rpc/rpc.h> /* \fIalways needed\fP */ |
---|
281 | #include "msg.h" /* \fIneed this too: msg.h will be generated by rpcgen\fP */ |
---|
282 | |
---|
283 | main(argc, argv) |
---|
284 | int argc; |
---|
285 | char *argv[]; |
---|
286 | { |
---|
287 | CLIENT *cl; |
---|
288 | int *result; |
---|
289 | char *server; |
---|
290 | char *message; |
---|
291 | |
---|
292 | if (argc < 3) { |
---|
293 | fprintf(stderr, "usage: %s host message\en", argv[0]); |
---|
294 | exit(1); |
---|
295 | } |
---|
296 | |
---|
297 | .ft I |
---|
298 | /* |
---|
299 | * Save values of command line arguments |
---|
300 | */ |
---|
301 | .ft CW |
---|
302 | server = argv[1]; |
---|
303 | message = argv[2]; |
---|
304 | |
---|
305 | .ft I |
---|
306 | /* |
---|
307 | * Create client "handle" used for calling \fIMESSAGEPROG\fP on the |
---|
308 | * server designated on the command line. We tell the RPC package |
---|
309 | * to use the "tcp" protocol when contacting the server. |
---|
310 | */ |
---|
311 | .ft CW |
---|
312 | cl = clnt_create(server, MESSAGEPROG, MESSAGEVERS, "tcp"); |
---|
313 | if (cl == NULL) { |
---|
314 | .ft I |
---|
315 | /* |
---|
316 | * Couldn't establish connection with server. |
---|
317 | * Print error message and die. |
---|
318 | */ |
---|
319 | .ft CW |
---|
320 | clnt_pcreateerror(server); |
---|
321 | exit(1); |
---|
322 | } |
---|
323 | |
---|
324 | .ft I |
---|
325 | /* |
---|
326 | * Call the remote procedure "printmessage" on the server |
---|
327 | */ |
---|
328 | .ft CW |
---|
329 | result = printmessage_1(&message, cl); |
---|
330 | if (result == NULL) { |
---|
331 | .ft I |
---|
332 | /* |
---|
333 | * An error occurred while calling the server. |
---|
334 | * Print error message and die. |
---|
335 | */ |
---|
336 | .ft CW |
---|
337 | clnt_perror(cl, server); |
---|
338 | exit(1); |
---|
339 | } |
---|
340 | |
---|
341 | .ft I |
---|
342 | /* |
---|
343 | * Okay, we successfully called the remote procedure. |
---|
344 | */ |
---|
345 | .ft CW |
---|
346 | if (*result == 0) { |
---|
347 | .ft I |
---|
348 | /* |
---|
349 | * Server was unable to print our message. |
---|
350 | * Print error message and die. |
---|
351 | */ |
---|
352 | .ft CW |
---|
353 | fprintf(stderr, "%s: %s couldn't print your message\en", |
---|
354 | argv[0], server); |
---|
355 | exit(1); |
---|
356 | } |
---|
357 | |
---|
358 | .ft I |
---|
359 | /* |
---|
360 | * The message got printed on the server's console |
---|
361 | */ |
---|
362 | .ft CW |
---|
363 | printf("Message delivered to %s!\en", server); |
---|
364 | } |
---|
365 | .DE |
---|
366 | There are two things to note here: |
---|
367 | .IP 1. |
---|
368 | .IX "client handle, used by rpcgen" "" "client handle, used by \fIrpcgen\fP" |
---|
369 | First a client \*Qhandle\*U is created using the RPC library routine |
---|
370 | .I clnt_create (). |
---|
371 | This client handle will be passed to the stub routines |
---|
372 | which call the remote procedure. |
---|
373 | .IP 2. |
---|
374 | The remote procedure |
---|
375 | .I printmessage_1() |
---|
376 | is called exactly the same way as it is declared in |
---|
377 | .I msg_proc.c |
---|
378 | except for the inserted client handle as the first argument. |
---|
379 | .LP |
---|
380 | Here's how to put all of the pieces together: |
---|
381 | .ie t .DS |
---|
382 | .el .DS L |
---|
383 | .ft CW |
---|
384 | example% \fBrpcgen msg.x\fP |
---|
385 | example% \fBcc rprintmsg.c msg_clnt.c -o rprintmsg\fP |
---|
386 | example% \fBcc msg_proc.c msg_svc.c -o msg_server\fP |
---|
387 | .DE |
---|
388 | Two programs were compiled here: the client program |
---|
389 | .I rprintmsg |
---|
390 | and the server program |
---|
391 | .I msg_server . |
---|
392 | Before doing this though, |
---|
393 | .I rpcgen |
---|
394 | was used to fill in the missing pieces. |
---|
395 | .LP |
---|
396 | Here is what |
---|
397 | .I rpcgen |
---|
398 | did with the input file |
---|
399 | .I msg.x : |
---|
400 | .IP 1. |
---|
401 | It created a header file called |
---|
402 | .I msg.h |
---|
403 | that contained |
---|
404 | .I #define 's |
---|
405 | for |
---|
406 | .I MESSAGEPROG , |
---|
407 | .I MESSAGEVERS |
---|
408 | and |
---|
409 | .I PRINTMESSAGE |
---|
410 | for use in the other modules. |
---|
411 | .IP 2. |
---|
412 | It created client \*Qstub\*U routines in the |
---|
413 | .I msg_clnt.c |
---|
414 | file. In this case there is only one, the |
---|
415 | .I printmessage_1() |
---|
416 | that was referred to from the |
---|
417 | .I printmsg |
---|
418 | client program. The name of the output file for |
---|
419 | client stub routines is always formed in this way: if the name of the |
---|
420 | input file is |
---|
421 | .I FOO.x , |
---|
422 | the client stubs output file is called |
---|
423 | .I FOO_clnt.c . |
---|
424 | .IP 3. |
---|
425 | It created the server program which calls |
---|
426 | .I printmessage_1() |
---|
427 | in |
---|
428 | .I msg_proc.c . |
---|
429 | This server program is named |
---|
430 | .I msg_svc.c . |
---|
431 | The rule for naming the server output file is similar to the |
---|
432 | previous one: for an input file called |
---|
433 | .I FOO.x , |
---|
434 | the output server file is named |
---|
435 | .I FOO_svc.c . |
---|
436 | .LP |
---|
437 | Now we're ready to have some fun. First, copy the server to a |
---|
438 | remote machine and run it. For this example, the |
---|
439 | machine is called \*Qmoon\*U. Server processes are run in the |
---|
440 | background, because they never exit. |
---|
441 | .ie t .DS |
---|
442 | .el .DS L |
---|
443 | .ft CW |
---|
444 | moon% \fBmsg_server &\fP |
---|
445 | .DE |
---|
446 | Then on our local machine (\*Qsun\*U) we can print a message on \*Qmoon\*Us |
---|
447 | console. |
---|
448 | .ie t .DS |
---|
449 | .el .DS L |
---|
450 | .ft CW |
---|
451 | sun% \fBprintmsg moon "Hello, moon."\fP |
---|
452 | .DE |
---|
453 | The message will get printed to \*Qmoon\*Us console. You can print a |
---|
454 | message on anybody's console (including your own) with this program if |
---|
455 | you are able to copy the server to their machine and run it. |
---|
456 | .NH 1 |
---|
457 | \&Generating XDR Routines |
---|
458 | .IX RPC "generating XDR routines" |
---|
459 | .LP |
---|
460 | The previous example only demonstrated the automatic generation of |
---|
461 | client and server RPC code. |
---|
462 | .I rpcgen |
---|
463 | may also be used to generate XDR routines, that is, the routines |
---|
464 | necessary to convert local data |
---|
465 | structures into network format and vice-versa. This example presents |
---|
466 | a complete RPC service\(ema remote directory listing service, which uses |
---|
467 | .I rpcgen |
---|
468 | not only to generate stub routines, but also to generate the XDR |
---|
469 | routines. Here is the protocol description file: |
---|
470 | .ie t .DS |
---|
471 | .el .DS L |
---|
472 | .ft I |
---|
473 | /* |
---|
474 | * dir.x: Remote directory listing protocol |
---|
475 | */ |
---|
476 | .ft CW |
---|
477 | const MAXNAMELEN = 255; /* \fImaximum length of a directory entry\fP */ |
---|
478 | |
---|
479 | typedef string nametype<MAXNAMELEN>; /* \fIa directory entry\fP */ |
---|
480 | |
---|
481 | typedef struct namenode *namelist; /* \fIa link in the listing\fP */ |
---|
482 | |
---|
483 | .ft I |
---|
484 | /* |
---|
485 | * A node in the directory listing |
---|
486 | */ |
---|
487 | .ft CW |
---|
488 | struct namenode { |
---|
489 | nametype name; /* \fIname of directory entry\fP */ |
---|
490 | namelist next; /* \fInext entry\fP */ |
---|
491 | }; |
---|
492 | |
---|
493 | .ft I |
---|
494 | /* |
---|
495 | * The result of a READDIR operation. |
---|
496 | */ |
---|
497 | .ft CW |
---|
498 | union readdir_res switch (int errno) { |
---|
499 | case 0: |
---|
500 | namelist list; /* \fIno error: return directory listing\fP */ |
---|
501 | default: |
---|
502 | void; /* \fIerror occurred: nothing else to return\fP */ |
---|
503 | }; |
---|
504 | |
---|
505 | .ft I |
---|
506 | /* |
---|
507 | * The directory program definition |
---|
508 | */ |
---|
509 | .ft CW |
---|
510 | program DIRPROG { |
---|
511 | version DIRVERS { |
---|
512 | readdir_res |
---|
513 | READDIR(nametype) = 1; |
---|
514 | } = 1; |
---|
515 | } = 76; |
---|
516 | .DE |
---|
517 | .SH |
---|
518 | Note: |
---|
519 | .I |
---|
520 | Types (like |
---|
521 | .I readdir_res |
---|
522 | in the example above) can be defined using |
---|
523 | the \*Qstruct\*U, \*Qunion\*U and \*Qenum\*U keywords, but those keywords |
---|
524 | should not be used in subsequent declarations of variables of those types. |
---|
525 | For example, if you define a union \*Qfoo\*U, you should declare using |
---|
526 | only \*Qfoo\*U and not \*Qunion foo\*U. In fact, |
---|
527 | .I rpcgen |
---|
528 | compiles |
---|
529 | RPC unions into C structures and it is an error to declare them using the |
---|
530 | \*Qunion\*U keyword. |
---|
531 | .LP |
---|
532 | Running |
---|
533 | .I rpcgen |
---|
534 | on |
---|
535 | .I dir.x |
---|
536 | creates four output files. Three are the same as before: header file, |
---|
537 | client stub routines and server skeleton. The fourth are the XDR routines |
---|
538 | necessary for converting the data types we declared into XDR format and |
---|
539 | vice-versa. These are output in the file |
---|
540 | .I dir_xdr.c . |
---|
541 | .LP |
---|
542 | Here is the implementation of the |
---|
543 | .I READDIR |
---|
544 | procedure. |
---|
545 | .ie t .DS |
---|
546 | .el .DS L |
---|
547 | .vs 11 |
---|
548 | .ft I |
---|
549 | /* |
---|
550 | * dir_proc.c: remote readdir implementation |
---|
551 | */ |
---|
552 | .ft CW |
---|
553 | #include <rpc/rpc.h> |
---|
554 | #include <sys/dir.h> |
---|
555 | #include "dir.h" |
---|
556 | |
---|
557 | extern int errno; |
---|
558 | extern char *malloc(); |
---|
559 | extern char *strdup(); |
---|
560 | |
---|
561 | readdir_res * |
---|
562 | readdir_1(dirname) |
---|
563 | nametype *dirname; |
---|
564 | { |
---|
565 | DIR *dirp; |
---|
566 | struct direct *d; |
---|
567 | namelist nl; |
---|
568 | namelist *nlp; |
---|
569 | static readdir_res res; /* \fImust be static\fP! */ |
---|
570 | |
---|
571 | .ft I |
---|
572 | /* |
---|
573 | * Open directory |
---|
574 | */ |
---|
575 | .ft CW |
---|
576 | dirp = opendir(*dirname); |
---|
577 | if (dirp == NULL) { |
---|
578 | res.errno = errno; |
---|
579 | return (&res); |
---|
580 | } |
---|
581 | |
---|
582 | .ft I |
---|
583 | /* |
---|
584 | * Free previous result |
---|
585 | */ |
---|
586 | .ft CW |
---|
587 | xdr_free(xdr_readdir_res, &res); |
---|
588 | |
---|
589 | .ft I |
---|
590 | /* |
---|
591 | * Collect directory entries. |
---|
592 | * Memory allocated here will be freed by \fIxdr_free\fP |
---|
593 | * next time \fIreaddir_1\fP is called |
---|
594 | */ |
---|
595 | .ft CW |
---|
596 | nlp = &res.readdir_res_u.list; |
---|
597 | while (d = readdir(dirp)) { |
---|
598 | nl = *nlp = (namenode *) malloc(sizeof(namenode)); |
---|
599 | nl->name = strdup(d->d_name); |
---|
600 | nlp = &nl->next; |
---|
601 | } |
---|
602 | *nlp = NULL; |
---|
603 | |
---|
604 | .ft I |
---|
605 | /* |
---|
606 | * Return the result |
---|
607 | */ |
---|
608 | .ft CW |
---|
609 | res.errno = 0; |
---|
610 | closedir(dirp); |
---|
611 | return (&res); |
---|
612 | } |
---|
613 | .vs |
---|
614 | .DE |
---|
615 | Finally, there is the client side program to call the server: |
---|
616 | .ie t .DS |
---|
617 | .el .DS L |
---|
618 | .ft I |
---|
619 | /* |
---|
620 | * rls.c: Remote directory listing client |
---|
621 | */ |
---|
622 | .ft CW |
---|
623 | #include <stdio.h> |
---|
624 | #include <rpc/rpc.h> /* \fIalways need this\fP */ |
---|
625 | #include "dir.h" /* \fIwill be generated by rpcgen\fI */ |
---|
626 | |
---|
627 | extern int errno; |
---|
628 | |
---|
629 | main(argc, argv) |
---|
630 | int argc; |
---|
631 | char *argv[]; |
---|
632 | { |
---|
633 | CLIENT *cl; |
---|
634 | char *server; |
---|
635 | char *dir; |
---|
636 | readdir_res *result; |
---|
637 | namelist nl; |
---|
638 | |
---|
639 | |
---|
640 | if (argc != 3) { |
---|
641 | fprintf(stderr, "usage: %s host directory\en", |
---|
642 | argv[0]); |
---|
643 | exit(1); |
---|
644 | } |
---|
645 | |
---|
646 | .ft I |
---|
647 | /* |
---|
648 | * Remember what our command line arguments refer to |
---|
649 | */ |
---|
650 | .ft CW |
---|
651 | server = argv[1]; |
---|
652 | dir = argv[2]; |
---|
653 | |
---|
654 | .ft I |
---|
655 | /* |
---|
656 | * Create client "handle" used for calling \fIMESSAGEPROG\fP on the |
---|
657 | * server designated on the command line. We tell the RPC package |
---|
658 | * to use the "tcp" protocol when contacting the server. |
---|
659 | */ |
---|
660 | .ft CW |
---|
661 | cl = clnt_create(server, DIRPROG, DIRVERS, "tcp"); |
---|
662 | if (cl == NULL) { |
---|
663 | .ft I |
---|
664 | /* |
---|
665 | * Couldn't establish connection with server. |
---|
666 | * Print error message and die. |
---|
667 | */ |
---|
668 | .ft CW |
---|
669 | clnt_pcreateerror(server); |
---|
670 | exit(1); |
---|
671 | } |
---|
672 | |
---|
673 | .ft I |
---|
674 | /* |
---|
675 | * Call the remote procedure \fIreaddir\fP on the server |
---|
676 | */ |
---|
677 | .ft CW |
---|
678 | result = readdir_1(&dir, cl); |
---|
679 | if (result == NULL) { |
---|
680 | .ft I |
---|
681 | /* |
---|
682 | * An error occurred while calling the server. |
---|
683 | * Print error message and die. |
---|
684 | */ |
---|
685 | .ft CW |
---|
686 | clnt_perror(cl, server); |
---|
687 | exit(1); |
---|
688 | } |
---|
689 | |
---|
690 | .ft I |
---|
691 | /* |
---|
692 | * Okay, we successfully called the remote procedure. |
---|
693 | */ |
---|
694 | .ft CW |
---|
695 | if (result->errno != 0) { |
---|
696 | .ft I |
---|
697 | /* |
---|
698 | * A remote system error occurred. |
---|
699 | * Print error message and die. |
---|
700 | */ |
---|
701 | .ft CW |
---|
702 | errno = result->errno; |
---|
703 | perror(dir); |
---|
704 | exit(1); |
---|
705 | } |
---|
706 | |
---|
707 | .ft I |
---|
708 | /* |
---|
709 | * Successfully got a directory listing. |
---|
710 | * Print it out. |
---|
711 | */ |
---|
712 | .ft CW |
---|
713 | for (nl = result->readdir_res_u.list; nl != NULL; |
---|
714 | nl = nl->next) { |
---|
715 | printf("%s\en", nl->name); |
---|
716 | } |
---|
717 | exit(0); |
---|
718 | } |
---|
719 | .DE |
---|
720 | Compile everything, and run. |
---|
721 | .DS |
---|
722 | .ft CW |
---|
723 | sun% \fBrpcgen dir.x\fP |
---|
724 | sun% \fBcc rls.c dir_clnt.c dir_xdr.c -o rls\fP |
---|
725 | sun% \fBcc dir_svc.c dir_proc.c dir_xdr.c -o dir_svc\fP |
---|
726 | |
---|
727 | sun% \fBdir_svc &\fP |
---|
728 | |
---|
729 | moon% \fBrls sun /usr/pub\fP |
---|
730 | \&. |
---|
731 | \&.. |
---|
732 | ascii |
---|
733 | eqnchar |
---|
734 | greek |
---|
735 | kbd |
---|
736 | marg8 |
---|
737 | tabclr |
---|
738 | tabs |
---|
739 | tabs4 |
---|
740 | moon% |
---|
741 | .DE |
---|
742 | .LP |
---|
743 | .IX "debugging with rpcgen" "" "debugging with \fIrpcgen\fP" |
---|
744 | A final note about |
---|
745 | .I rpcgen : |
---|
746 | The client program and the server procedure can be tested together |
---|
747 | as a single program by simply linking them with each other rather |
---|
748 | than with the client and server stubs. The procedure calls will be |
---|
749 | executed as ordinary local procedure calls and the program can be |
---|
750 | debugged with a local debugger such as |
---|
751 | .I dbx . |
---|
752 | When the program is working, the client program can be linked to |
---|
753 | the client stub produced by |
---|
754 | .I rpcgen |
---|
755 | and the server procedures can be linked to the server stub produced |
---|
756 | by |
---|
757 | .I rpcgen . |
---|
758 | .SH |
---|
759 | .I NOTE : |
---|
760 | \fIIf you do this, you may want to comment out calls to RPC library |
---|
761 | routines, and have client-side routines call server routines |
---|
762 | directly.\fP |
---|
763 | .LP |
---|
764 | .NH 1 |
---|
765 | \&The C-Preprocessor |
---|
766 | .IX rpcgen "C-preprocessor" \fIrpcgen\fP |
---|
767 | .LP |
---|
768 | The C-preprocessor is run on all input files before they are |
---|
769 | compiled, so all the preprocessor directives are legal within a \*Q.x\*U |
---|
770 | file. Four symbols may be defined, depending upon which output file is |
---|
771 | getting generated. The symbols are: |
---|
772 | .TS |
---|
773 | box tab (&); |
---|
774 | lfI lfI |
---|
775 | lfL l . |
---|
776 | Symbol&Usage |
---|
777 | _ |
---|
778 | RPC_HDR&for header-file output |
---|
779 | RPC_XDR&for XDR routine output |
---|
780 | RPC_SVC&for server-skeleton output |
---|
781 | RPC_CLNT&for client stub output |
---|
782 | .TE |
---|
783 | .LP |
---|
784 | Also, |
---|
785 | .I rpcgen |
---|
786 | does a little preprocessing of its own. Any line that |
---|
787 | begins with a percent sign is passed directly into the output file, |
---|
788 | without any interpretation of the line. Here is a simple example that |
---|
789 | demonstrates the preprocessing features. |
---|
790 | .ie t .DS |
---|
791 | .el .DS L |
---|
792 | .ft I |
---|
793 | /* |
---|
794 | * time.x: Remote time protocol |
---|
795 | */ |
---|
796 | .ft CW |
---|
797 | program TIMEPROG { |
---|
798 | version TIMEVERS { |
---|
799 | unsigned int TIMEGET(void) = 1; |
---|
800 | } = 1; |
---|
801 | } = 44; |
---|
802 | |
---|
803 | #ifdef RPC_SVC |
---|
804 | %int * |
---|
805 | %timeget_1() |
---|
806 | %{ |
---|
807 | % static int thetime; |
---|
808 | % |
---|
809 | % thetime = time(0); |
---|
810 | % return (&thetime); |
---|
811 | %} |
---|
812 | #endif |
---|
813 | .DE |
---|
814 | The '%' feature is not generally recommended, as there is no guarantee |
---|
815 | that the compiler will stick the output where you intended. |
---|
816 | .NH 1 |
---|
817 | \&\fBrpcgen\fP Programming Notes |
---|
818 | .IX rpcgen "other operations" \fIrpcgen\fP |
---|
819 | .sp |
---|
820 | .NH 2 |
---|
821 | \&Timeout Changes |
---|
822 | .IX rpcgen "timeout changes" \fIrpcgen\fP |
---|
823 | .LP |
---|
824 | RPC sets a default timeout of 25 seconds for RPC calls when |
---|
825 | .I clnt_create() |
---|
826 | is used. This timeout may be changed using |
---|
827 | .I clnt_control() |
---|
828 | Here is a small code fragment to demonstrate use of |
---|
829 | .I clnt_control (): |
---|
830 | .ID |
---|
831 | struct timeval tv; |
---|
832 | CLIENT *cl; |
---|
833 | .sp .5 |
---|
834 | cl = clnt_create("somehost", SOMEPROG, SOMEVERS, "tcp"); |
---|
835 | if (cl == NULL) { |
---|
836 | exit(1); |
---|
837 | } |
---|
838 | tv.tv_sec = 60; /* \fIchange timeout to 1 minute\fP */ |
---|
839 | tv.tv_usec = 0; |
---|
840 | clnt_control(cl, CLSET_TIMEOUT, &tv); |
---|
841 | .DE |
---|
842 | .NH 2 |
---|
843 | \&Handling Broadcast on the Server Side |
---|
844 | .IX "broadcast RPC" |
---|
845 | .IX rpcgen "broadcast RPC" \fIrpcgen\fP |
---|
846 | .LP |
---|
847 | When a procedure is known to be called via broadcast RPC, |
---|
848 | it is usually wise for the server to not reply unless it can provide |
---|
849 | some useful information to the client. This prevents the network |
---|
850 | from getting flooded by useless replies. |
---|
851 | .LP |
---|
852 | To prevent the server from replying, a remote procedure can |
---|
853 | return NULL as its result, and the server code generated by |
---|
854 | .I rpcgen |
---|
855 | will detect this and not send out a reply. |
---|
856 | .LP |
---|
857 | Here is an example of a procedure that replies only if it |
---|
858 | thinks it is an NFS server: |
---|
859 | .ID |
---|
860 | void * |
---|
861 | reply_if_nfsserver() |
---|
862 | { |
---|
863 | char notnull; /* \fIjust here so we can use its address\fP */ |
---|
864 | .sp .5 |
---|
865 | if (access("/etc/exports", F_OK) < 0) { |
---|
866 | return (NULL); /* \fIprevent RPC from replying\fP */ |
---|
867 | } |
---|
868 | .ft I |
---|
869 | /* |
---|
870 | * return non-null pointer so RPC will send out a reply |
---|
871 | */ |
---|
872 | .ft L |
---|
873 | return ((void *)¬null); |
---|
874 | } |
---|
875 | .DE |
---|
876 | Note that if procedure returns type \*Qvoid *\*U, they must return a non-NULL |
---|
877 | pointer if they want RPC to reply for them. |
---|
878 | .NH 2 |
---|
879 | \&Other Information Passed to Server Procedures |
---|
880 | .LP |
---|
881 | Server procedures will often want to know more about an RPC call |
---|
882 | than just its arguments. For example, getting authentication information |
---|
883 | is important to procedures that want to implement some level of security. |
---|
884 | This extra information is actually supplied to the server procedure as a |
---|
885 | second argument. Here is an example to demonstrate its use. What we've |
---|
886 | done here is rewrite the previous |
---|
887 | .I printmessage_1() |
---|
888 | procedure to only allow root users to print a message to the console. |
---|
889 | .ID |
---|
890 | int * |
---|
891 | printmessage_1(msg, rq) |
---|
892 | char **msg; |
---|
893 | struct svc_req *rq; |
---|
894 | { |
---|
895 | static in result; /* \fIMust be static\fP */ |
---|
896 | FILE *f; |
---|
897 | struct suthunix_parms *aup; |
---|
898 | .sp .5 |
---|
899 | aup = (struct authunix_parms *)rq->rq_clntcred; |
---|
900 | if (aup->aup_uid != 0) { |
---|
901 | result = 0; |
---|
902 | return (&result); |
---|
903 | } |
---|
904 | .sp |
---|
905 | .ft I |
---|
906 | /* |
---|
907 | * Same code as before. |
---|
908 | */ |
---|
909 | .ft L |
---|
910 | } |
---|
911 | .DE |
---|
912 | .NH 1 |
---|
913 | \&RPC Language |
---|
914 | .IX RPCL |
---|
915 | .IX rpcgen "RPC Language" \fIrpcgen\fP |
---|
916 | .LP |
---|
917 | RPC language is an extension of XDR language. The sole extension is |
---|
918 | the addition of the |
---|
919 | .I program |
---|
920 | type. For a complete description of the XDR language syntax, see the |
---|
921 | .I "External Data Representation Standard: Protocol Specification" |
---|
922 | chapter. For a description of the RPC extensions to the XDR language, |
---|
923 | see the |
---|
924 | .I "Remote Procedure Calls: Protocol Specification" |
---|
925 | chapter. |
---|
926 | .LP |
---|
927 | However, XDR language is so close to C that if you know C, you know most |
---|
928 | of it already. We describe here the syntax of the RPC language, |
---|
929 | showing a few examples along the way. We also show how the various |
---|
930 | RPC and XDR type definitions get compiled into C type definitions in |
---|
931 | the output header file. |
---|
932 | .KS |
---|
933 | .NH 2 |
---|
934 | Definitions |
---|
935 | \& |
---|
936 | .IX rpcgen definitions \fIrpcgen\fP |
---|
937 | .LP |
---|
938 | An RPC language file consists of a series of definitions. |
---|
939 | .DS L |
---|
940 | .ft CW |
---|
941 | definition-list: |
---|
942 | definition ";" |
---|
943 | definition ";" definition-list |
---|
944 | .DE |
---|
945 | .KE |
---|
946 | It recognizes five types of definitions. |
---|
947 | .DS L |
---|
948 | .ft CW |
---|
949 | definition: |
---|
950 | enum-definition |
---|
951 | struct-definition |
---|
952 | union-definition |
---|
953 | typedef-definition |
---|
954 | const-definition |
---|
955 | program-definition |
---|
956 | .DE |
---|
957 | .NH 2 |
---|
958 | Structures |
---|
959 | \& |
---|
960 | .IX rpcgen structures \fIrpcgen\fP |
---|
961 | .LP |
---|
962 | An XDR struct is declared almost exactly like its C counterpart. It |
---|
963 | looks like the following: |
---|
964 | .DS L |
---|
965 | .ft CW |
---|
966 | struct-definition: |
---|
967 | "struct" struct-ident "{" |
---|
968 | declaration-list |
---|
969 | "}" |
---|
970 | |
---|
971 | declaration-list: |
---|
972 | declaration ";" |
---|
973 | declaration ";" declaration-list |
---|
974 | .DE |
---|
975 | As an example, here is an XDR structure to a two-dimensional |
---|
976 | coordinate, and the C structure that it gets compiled into in the |
---|
977 | output header file. |
---|
978 | .DS |
---|
979 | .ft CW |
---|
980 | struct coord { struct coord { |
---|
981 | int x; --> int x; |
---|
982 | int y; int y; |
---|
983 | }; }; |
---|
984 | typedef struct coord coord; |
---|
985 | .DE |
---|
986 | The output is identical to the input, except for the added |
---|
987 | .I typedef |
---|
988 | at the end of the output. This allows one to use \*Qcoord\*U instead of |
---|
989 | \*Qstruct coord\*U when declaring items. |
---|
990 | .NH 2 |
---|
991 | Unions |
---|
992 | \& |
---|
993 | .IX rpcgen unions \fIrpcgen\fP |
---|
994 | .LP |
---|
995 | XDR unions are discriminated unions, and look quite different from C |
---|
996 | unions. They are more analogous to Pascal variant records than they |
---|
997 | are to C unions. |
---|
998 | .DS L |
---|
999 | .ft CW |
---|
1000 | union-definition: |
---|
1001 | "union" union-ident "switch" "(" declaration ")" "{" |
---|
1002 | case-list |
---|
1003 | "}" |
---|
1004 | |
---|
1005 | case-list: |
---|
1006 | "case" value ":" declaration ";" |
---|
1007 | "default" ":" declaration ";" |
---|
1008 | "case" value ":" declaration ";" case-list |
---|
1009 | .DE |
---|
1010 | Here is an example of a type that might be returned as the result of a |
---|
1011 | \*Qread data\*U operation. If there is no error, return a block of data. |
---|
1012 | Otherwise, don't return anything. |
---|
1013 | .DS L |
---|
1014 | .ft CW |
---|
1015 | union read_result switch (int errno) { |
---|
1016 | case 0: |
---|
1017 | opaque data[1024]; |
---|
1018 | default: |
---|
1019 | void; |
---|
1020 | }; |
---|
1021 | .DE |
---|
1022 | It gets compiled into the following: |
---|
1023 | .DS L |
---|
1024 | .ft CW |
---|
1025 | struct read_result { |
---|
1026 | int errno; |
---|
1027 | union { |
---|
1028 | char data[1024]; |
---|
1029 | } read_result_u; |
---|
1030 | }; |
---|
1031 | typedef struct read_result read_result; |
---|
1032 | .DE |
---|
1033 | Notice that the union component of the output struct has the name as |
---|
1034 | the type name, except for the trailing \*Q_u\*U. |
---|
1035 | .NH 2 |
---|
1036 | Enumerations |
---|
1037 | \& |
---|
1038 | .IX rpcgen enumerations \fIrpcgen\fP |
---|
1039 | .LP |
---|
1040 | XDR enumerations have the same syntax as C enumerations. |
---|
1041 | .DS L |
---|
1042 | .ft CW |
---|
1043 | enum-definition: |
---|
1044 | "enum" enum-ident "{" |
---|
1045 | enum-value-list |
---|
1046 | "}" |
---|
1047 | |
---|
1048 | enum-value-list: |
---|
1049 | enum-value |
---|
1050 | enum-value "," enum-value-list |
---|
1051 | |
---|
1052 | enum-value: |
---|
1053 | enum-value-ident |
---|
1054 | enum-value-ident "=" value |
---|
1055 | .DE |
---|
1056 | Here is a short example of an XDR enum, and the C enum that it gets |
---|
1057 | compiled into. |
---|
1058 | .DS L |
---|
1059 | .ft CW |
---|
1060 | enum colortype { enum colortype { |
---|
1061 | RED = 0, RED = 0, |
---|
1062 | GREEN = 1, --> GREEN = 1, |
---|
1063 | BLUE = 2 BLUE = 2, |
---|
1064 | }; }; |
---|
1065 | typedef enum colortype colortype; |
---|
1066 | .DE |
---|
1067 | .NH 2 |
---|
1068 | Typedef |
---|
1069 | \& |
---|
1070 | .IX rpcgen typedef \fIrpcgen\fP |
---|
1071 | .LP |
---|
1072 | XDR typedefs have the same syntax as C typedefs. |
---|
1073 | .DS L |
---|
1074 | .ft CW |
---|
1075 | typedef-definition: |
---|
1076 | "typedef" declaration |
---|
1077 | .DE |
---|
1078 | Here is an example that defines a |
---|
1079 | .I fname_type |
---|
1080 | used for declaring |
---|
1081 | file name strings that have a maximum length of 255 characters. |
---|
1082 | .DS L |
---|
1083 | .ft CW |
---|
1084 | typedef string fname_type<255>; --> typedef char *fname_type; |
---|
1085 | .DE |
---|
1086 | .NH 2 |
---|
1087 | Constants |
---|
1088 | \& |
---|
1089 | .IX rpcgen constants \fIrpcgen\fP |
---|
1090 | .LP |
---|
1091 | XDR constants symbolic constants that may be used wherever a |
---|
1092 | integer constant is used, for example, in array size specifications. |
---|
1093 | .DS L |
---|
1094 | .ft CW |
---|
1095 | const-definition: |
---|
1096 | "const" const-ident "=" integer |
---|
1097 | .DE |
---|
1098 | For example, the following defines a constant |
---|
1099 | .I DOZEN |
---|
1100 | equal to 12. |
---|
1101 | .DS L |
---|
1102 | .ft CW |
---|
1103 | const DOZEN = 12; --> #define DOZEN 12 |
---|
1104 | .DE |
---|
1105 | .NH 2 |
---|
1106 | Programs |
---|
1107 | \& |
---|
1108 | .IX rpcgen programs \fIrpcgen\fP |
---|
1109 | .LP |
---|
1110 | RPC programs are declared using the following syntax: |
---|
1111 | .DS L |
---|
1112 | .ft CW |
---|
1113 | program-definition: |
---|
1114 | "program" program-ident "{" |
---|
1115 | version-list |
---|
1116 | "}" "=" value |
---|
1117 | |
---|
1118 | version-list: |
---|
1119 | version ";" |
---|
1120 | version ";" version-list |
---|
1121 | |
---|
1122 | version: |
---|
1123 | "version" version-ident "{" |
---|
1124 | procedure-list |
---|
1125 | "}" "=" value |
---|
1126 | |
---|
1127 | procedure-list: |
---|
1128 | procedure ";" |
---|
1129 | procedure ";" procedure-list |
---|
1130 | |
---|
1131 | procedure: |
---|
1132 | type-ident procedure-ident "(" type-ident ")" "=" value |
---|
1133 | .DE |
---|
1134 | For example, here is the time protocol, revisited: |
---|
1135 | .ie t .DS |
---|
1136 | .el .DS L |
---|
1137 | .ft I |
---|
1138 | /* |
---|
1139 | * time.x: Get or set the time. Time is represented as number of seconds |
---|
1140 | * since 0:00, January 1, 1970. |
---|
1141 | */ |
---|
1142 | .ft CW |
---|
1143 | program TIMEPROG { |
---|
1144 | version TIMEVERS { |
---|
1145 | unsigned int TIMEGET(void) = 1; |
---|
1146 | void TIMESET(unsigned) = 2; |
---|
1147 | } = 1; |
---|
1148 | } = 44; |
---|
1149 | .DE |
---|
1150 | This file compiles into #defines in the output header file: |
---|
1151 | .ie t .DS |
---|
1152 | .el .DS L |
---|
1153 | .ft CW |
---|
1154 | #define TIMEPROG 44 |
---|
1155 | #define TIMEVERS 1 |
---|
1156 | #define TIMEGET 1 |
---|
1157 | #define TIMESET 2 |
---|
1158 | .DE |
---|
1159 | .NH 2 |
---|
1160 | Declarations |
---|
1161 | \& |
---|
1162 | .IX rpcgen declarations \fIrpcgen\fP |
---|
1163 | .LP |
---|
1164 | In XDR, there are only four kinds of declarations. |
---|
1165 | .DS L |
---|
1166 | .ft CW |
---|
1167 | declaration: |
---|
1168 | simple-declaration |
---|
1169 | fixed-array-declaration |
---|
1170 | variable-array-declaration |
---|
1171 | pointer-declaration |
---|
1172 | .DE |
---|
1173 | \fB1) Simple declarations\fP are just like simple C declarations. |
---|
1174 | .DS L |
---|
1175 | .ft CW |
---|
1176 | simple-declaration: |
---|
1177 | type-ident variable-ident |
---|
1178 | .DE |
---|
1179 | Example: |
---|
1180 | .DS L |
---|
1181 | .ft CW |
---|
1182 | colortype color; --> colortype color; |
---|
1183 | .DE |
---|
1184 | \fB2) Fixed-length Array Declarations\fP are just like C array declarations: |
---|
1185 | .DS L |
---|
1186 | .ft CW |
---|
1187 | fixed-array-declaration: |
---|
1188 | type-ident variable-ident "[" value "]" |
---|
1189 | .DE |
---|
1190 | Example: |
---|
1191 | .DS L |
---|
1192 | .ft CW |
---|
1193 | colortype palette[8]; --> colortype palette[8]; |
---|
1194 | .DE |
---|
1195 | \fB3) Variable-Length Array Declarations\fP have no explicit syntax |
---|
1196 | in C, so XDR invents its own using angle-brackets. |
---|
1197 | .DS L |
---|
1198 | .ft CW |
---|
1199 | variable-array-declaration: |
---|
1200 | type-ident variable-ident "<" value ">" |
---|
1201 | type-ident variable-ident "<" ">" |
---|
1202 | .DE |
---|
1203 | The maximum size is specified between the angle brackets. The size may |
---|
1204 | be omitted, indicating that the array may be of any size. |
---|
1205 | .DS L |
---|
1206 | .ft CW |
---|
1207 | int heights<12>; /* \fIat most 12 items\fP */ |
---|
1208 | int widths<>; /* \fIany number of items\fP */ |
---|
1209 | .DE |
---|
1210 | Since variable-length arrays have no explicit syntax in C, these |
---|
1211 | declarations are actually compiled into \*Qstruct\*Us. For example, the |
---|
1212 | \*Qheights\*U declaration gets compiled into the following struct: |
---|
1213 | .DS L |
---|
1214 | .ft CW |
---|
1215 | struct { |
---|
1216 | u_int heights_len; /* \fI# of items in array\fP */ |
---|
1217 | int *heights_val; /* \fIpointer to array\fP */ |
---|
1218 | } heights; |
---|
1219 | .DE |
---|
1220 | Note that the number of items in the array is stored in the \*Q_len\*U |
---|
1221 | component and the pointer to the array is stored in the \*Q_val\*U |
---|
1222 | component. The first part of each of these component's names is the |
---|
1223 | same as the name of the declared XDR variable. |
---|
1224 | .LP |
---|
1225 | \fB4) Pointer Declarations\fP are made in |
---|
1226 | XDR exactly as they are in C. You can't |
---|
1227 | really send pointers over the network, but you can use XDR pointers |
---|
1228 | for sending recursive data types such as lists and trees. The type is |
---|
1229 | actually called \*Qoptional-data\*U, not \*Qpointer\*U, in XDR language. |
---|
1230 | .DS L |
---|
1231 | .ft CW |
---|
1232 | pointer-declaration: |
---|
1233 | type-ident "*" variable-ident |
---|
1234 | .DE |
---|
1235 | Example: |
---|
1236 | .DS L |
---|
1237 | .ft CW |
---|
1238 | listitem *next; --> listitem *next; |
---|
1239 | .DE |
---|
1240 | .NH 2 |
---|
1241 | \&Special Cases |
---|
1242 | .IX rpcgen "special cases" \fIrpcgen\fP |
---|
1243 | .LP |
---|
1244 | There are a few exceptions to the rules described above. |
---|
1245 | .LP |
---|
1246 | .B Booleans: |
---|
1247 | C has no built-in boolean type. However, the RPC library does a |
---|
1248 | boolean type called |
---|
1249 | .I bool_t |
---|
1250 | that is either |
---|
1251 | .I TRUE |
---|
1252 | or |
---|
1253 | .I FALSE . |
---|
1254 | Things declared as type |
---|
1255 | .I bool |
---|
1256 | in XDR language are compiled into |
---|
1257 | .I bool_t |
---|
1258 | in the output header file. |
---|
1259 | .LP |
---|
1260 | Example: |
---|
1261 | .DS L |
---|
1262 | .ft CW |
---|
1263 | bool married; --> bool_t married; |
---|
1264 | .DE |
---|
1265 | .B Strings: |
---|
1266 | C has no built-in string type, but instead uses the null-terminated |
---|
1267 | \*Qchar *\*U convention. In XDR language, strings are declared using the |
---|
1268 | \*Qstring\*U keyword, and compiled into \*Qchar *\*Us in the output header |
---|
1269 | file. The maximum size contained in the angle brackets specifies the |
---|
1270 | maximum number of characters allowed in the strings (not counting the |
---|
1271 | .I NULL |
---|
1272 | character). The maximum size may be left off, indicating a string |
---|
1273 | of arbitrary length. |
---|
1274 | .LP |
---|
1275 | Examples: |
---|
1276 | .DS L |
---|
1277 | .ft CW |
---|
1278 | string name<32>; --> char *name; |
---|
1279 | string longname<>; --> char *longname; |
---|
1280 | .DE |
---|
1281 | .B "Opaque Data:" |
---|
1282 | Opaque data is used in RPC and XDR to describe untyped data, that is, |
---|
1283 | just sequences of arbitrary bytes. It may be declared either as a |
---|
1284 | fixed or variable length array. |
---|
1285 | .DS L |
---|
1286 | Examples: |
---|
1287 | .ft CW |
---|
1288 | opaque diskblock[512]; --> char diskblock[512]; |
---|
1289 | |
---|
1290 | opaque filedata<1024>; --> struct { |
---|
1291 | u_int filedata_len; |
---|
1292 | char *filedata_val; |
---|
1293 | } filedata; |
---|
1294 | .DE |
---|
1295 | .B Voids: |
---|
1296 | In a void declaration, the variable is not named. The declaration is |
---|
1297 | just \*Qvoid\*U and nothing else. Void declarations can only occur in two |
---|
1298 | places: union definitions and program definitions (as the argument or |
---|
1299 | result of a remote procedure). |
---|