/share/doc/psd/22.rpcgen/rpcgen.ms

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 1301 lines · 1254 code · 47 blank · 0 comment · 0 complexity · 360825e13eb725255918d08a1be30e7e MD5 · raw file

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