ape.html 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533
  1. <html>
  2. <title>
  3. data
  4. </title>
  5. <body BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#330088" ALINK="#FF0044">
  6. <H1>APE &#173; The ANSI/POSIX Environment
  7. </H1>
  8. <DL><DD><I>Howard Trickey<br>
  9. howard@plan9.bell-labs.com<br>
  10. </I></DL>
  11. <H4>Introduction
  12. </H4>
  13. <P>
  14. When a large or frequently-updated program must be ported
  15. to or from Plan 9, the ANSI/POSIX environment known as APE can be useful.
  16. APE combines the set of headers and object code libraries specified by
  17. the ANSI C standard (ANSI X3.159-1989) with the POSIX operating system
  18. interface standard (IEEE 1003.1-1990, ISO 9945-1), the part of POSIX
  19. defining the basic operating system functions.
  20. Using APE will cause slower compilation and marginally slower execution speeds,
  21. so if the importing or exporting happens only infrequently, due consideration
  22. should be given to using the usual Plan 9 compilation environment instead.
  23. Another factor to consider is that the Plan 9 header organization is
  24. much simpler to remember and use.
  25. </P>
  26. <P>
  27. There are some aspects of required POSIX behavior that are impossible or
  28. very hard to simulate in Plan 9. They are described below.
  29. Experience has shown, however, that the simulation is adequate for the
  30. vast majority of programs. A much more common problem is that
  31. many programs use functions or headers not defined by POSIX.
  32. APE has some extensions to POSIX to help in this regard.
  33. Extensions must be explicitly enabled with an appropriate
  34. <TT>#define</TT>,
  35. in order that the APE environment be a good aid for testing
  36. ANSI/POSIX compliance of programs.
  37. </P>
  38. <H4>Pcc
  39. </H4>
  40. <P>
  41. The
  42. <TT>pcc</TT>
  43. command acts as a front end to the Plan 9 C compilers and loaders.
  44. It runs an ANSI C preprocessor over source files, using the APE
  45. headers to satisfy
  46. <TT>#include <<I>file</I>></TT>
  47. directives; then it runs a Plan 9 C compiler; finally, it may load
  48. with APE libraries to produce an executable program.
  49. The document
  50. <I>How to Use the Plan 9 C Compiler</I>
  51. explains how environment variables are used by convention to
  52. handle compilation for differing architectures.
  53. The environment variable
  54. <TT>$objtype</TT>
  55. controls which Plan 9 compiler and loader are used by
  56. <TT>pcc</TT>,
  57. as well as the location of header and library files.
  58. For example, if
  59. <TT>$objtype</TT>
  60. is
  61. <TT>mips</TT>,
  62. then
  63. <TT>pcc</TT>
  64. has
  65. <TT>cpp</TT>
  66. look for headers in
  67. <TT>/mips/include/ape</TT>
  68. followed by
  69. <TT>/sys/include/ape</TT>;
  70. then
  71. <TT>pcc</TT>
  72. uses
  73. <TT>vc</TT>
  74. to create
  75. <TT>.v</TT>
  76. object files;
  77. finally,
  78. <TT>vl</TT>
  79. is used to create an executable using libraries in
  80. <TT>/mips/lib/ape</TT>.
  81. </P>
  82. <H4>Psh and Cc
  83. </H4>
  84. <P>
  85. The
  86. <TT>pcc</TT>
  87. command is intended for uses where the source code is
  88. ANSI/POSIX, but the programs are built in the usual Plan 9
  89. manner &#173; with
  90. <TT>mk</TT>
  91. and producing object files with names ending in
  92. <TT>.v</TT>,
  93. etc.
  94. Sometimes it is best to use the standard POSIX
  95. <TT>make</TT>
  96. and
  97. <TT>cc</TT>
  98. (which produces object files with names ending in
  99. <TT>.o</TT>,
  100. and automatically calls the loader unless
  101. <TT>-c</TT>
  102. is specified).
  103. Under these circumstances, execute the command:
  104. <DL><DT><DD><TT><PRE>
  105. <TT>ape/psh</TT>
  106. </PRE></TT></DL>
  107. This starts a POSIX shell, with an environment that
  108. includes the POSIX commands
  109. <TT>ar89</TT>,
  110. <TT>c89</TT>,
  111. <TT>cc</TT>,
  112. <TT>basename</TT>,
  113. <TT>dirname</TT>,
  114. <TT>expr</TT>,
  115. <TT>false</TT>,
  116. <TT>grep</TT>,
  117. <TT>kill</TT>,
  118. <TT>make</TT>,
  119. <TT>rmdir</TT>,
  120. <TT>sed</TT>,
  121. <TT>sh</TT>,
  122. <TT>stty</TT>,
  123. <TT>true</TT>,
  124. <TT>uname</TT>,
  125. and
  126. <TT>yacc</TT>.
  127. There are also a few placeholders for commands that cannot be
  128. implemented in Plan 9:
  129. <TT>chown</TT>,
  130. <TT>ln</TT>,
  131. and
  132. <TT>umask</TT>.
  133. </P>
  134. <P>
  135. The
  136. <TT>cc</TT>
  137. command accepts the options mandated for
  138. the POSIX command
  139. <TT>c89</TT>,
  140. as specified in the C-Language Development Utilities Option
  141. annex of the POSIX Shell and Utilities standard.
  142. It also accepts the following nonstandard options:
  143. <TT>-v</TT>
  144. for echoing the commands for each pass to stdout;
  145. <TT>-A</TT>
  146. to turn on ANSI prototype warnings;
  147. <TT>-S</TT>
  148. to leave assembly language in
  149. <I>file</I>.s;
  150. <TT>-Wp,<I>args</I></TT>
  151. to pass
  152. <I>args</I>
  153. to the
  154. <TT>cpp</TT>;
  155. <TT>-W0,<I>args</I></TT>
  156. to pass
  157. <I>args</I>
  158. to 2c, etc.;
  159. and
  160. <TT>-Wl,<I>args</I></TT>
  161. to pass
  162. <I>args</I>
  163. to 2l, etc.
  164. </P>
  165. <P>
  166. The
  167. <TT>sh</TT>
  168. command is pdksh, a mostly POSIX-compliant public domain Korn Shell.
  169. The Plan 9 implementation does not include
  170. the emacs and vi editing modes.
  171. </P>
  172. <P>
  173. The
  174. <TT>stty</TT>
  175. command only has effect if the
  176. <TT>ape/ptyfs</TT>
  177. command has been started to interpose a pseudo-tty interface
  178. between
  179. <TT>/dev/cons</TT>
  180. and the running command.
  181. None of the distributed commands do this automatically.
  182. </P>
  183. <H4>Symbols
  184. </H4>
  185. <P>
  186. The C and POSIX standards require that certain symbols be
  187. defined in headers.
  188. They also require that certain other classes of symbols not
  189. be defined in the headers, and specify certain other
  190. symbols that may be defined in headers at the discretion
  191. of the implementation.
  192. POSIX defines
  193. <I>feature test macros</I>,
  194. which are preprocessor symbols beginning with an underscore
  195. and then a capital letter; if the program
  196. <TT>#defines</TT>
  197. a feature test macro before the inclusion of any headers,
  198. then it is requesting that certain symbols be visible in the headers.
  199. The most important feature test macro is
  200. <TT>_POSIX_SOURCE</TT>:
  201. when it is defined, exactly the symbols required by POSIX are
  202. visible in the appropriate headers.
  203. Consider
  204. <TT><signal.h></TT>
  205. for example:
  206. ANSI defines some names that must be defined in
  207. <TT><signal.h></TT>,
  208. but POSIX defines others, such as
  209. <TT>sigset_t</TT>,
  210. which are not allowed according to ANSI.
  211. The solution is to make the additional symbols visible only when
  212. <TT>_POSIX_SOURCE</TT>
  213. is defined.
  214. </P>
  215. <P>
  216. To export a program, it helps to know whether it fits
  217. in one of the following categories:
  218. </P>
  219. <DL COMPACT>
  220. <DT>1.<DD>
  221. Strictly conforming ANSI C program. It only uses features of the language,
  222. libraries, and headers explicitly required by the C standard. It does not
  223. depend on unspecified, undefined, or implementation-dependent behavior,
  224. and does not exceed any minimum implementation limit.
  225. <DT>2.<DD>
  226. Strictly conforming POSIX program. Similar, but for the POSIX standard as well.
  227. <DT>3.<DD>
  228. Some superset of POSIX, with extensions. Each extension
  229. is selected by a feature test macro, so it is clear which extensions
  230. are being used.
  231. </dl>
  232. <P>
  233. With APE, if headers are always included to declare any library functions
  234. used, then the set of feature test macros defined by a program will
  235. show which of the above categories the program is in.
  236. To accomplish this, no symbol is defined in a header if it is not required
  237. by the C or POSIX standard, and those required by the POSIX standard
  238. are protected by
  239. <TT>#ifdef _POSIX_SOURCE</TT>.
  240. For example,
  241. <TT><errno.h></TT>
  242. defines
  243. <TT>EDOM</TT>,
  244. <TT>ERANGE</TT>,
  245. and
  246. <TT>errno</TT>,
  247. as required by the C standard.
  248. The C standard allows more names beginning with
  249. <TT>E</TT>,
  250. but our header defines only those unless
  251. <TT>_POSIX_SOURCE</TT>
  252. is defined, in which case the symbols required by POSIX are also defined.
  253. This means that a program that uses
  254. <TT>ENAMETOOLONG</TT>
  255. cannot masquerade as a strictly conforming ANSI C program.
  256. </P>
  257. <P>
  258. <TT>Pcc</TT>
  259. and
  260. <TT>cc</TT>
  261. do not predefine any preprocessor symbols except those required by
  262. the ANSI C standard:
  263. <TT>__STDC__</TT>,
  264. <TT>__LINE__</TT>,
  265. <TT>__FILE__</TT>,
  266. <TT>__DATE__</TT>,
  267. and
  268. <TT>__TIME__</TT>.
  269. Any others must be defined in the program itself or by using
  270. <TT>-D</TT>
  271. on the command line.
  272. </P>
  273. <H4>Extensions
  274. </H4>
  275. <P>
  276. The discipline enforced by putting only required
  277. names in the headers is useful for exporting programs,
  278. but it gets in the way when importing programs.
  279. The compromise is to allow additional symbols in headers,
  280. additional headers, and additional library functions,
  281. but only under control of extension feature test macros.
  282. The following extensions are provided; unless otherwise
  283. specified, the additional library functions are in the
  284. default APE library.
  285. </P>
  286. <DL COMPACT>
  287. <DT> -<DD>
  288. <TT>_LIBG_EXTENSION</TT>.
  289. This allows the use of the Plan 9 graphics library.
  290. The functions are as described in the Plan 9 manual (see
  291. <A href="/magic/man2html/2/graphics"><I>graphics</I>(2))
  292. </A>except that
  293. <TT>div</TT>
  294. had to be renamed
  295. <TT>ptdiv</TT>.
  296. Include the
  297. <TT><libg.h></TT>
  298. header to declare the needed types and functions.
  299. <DT> -<DD>
  300. <TT>_LIMITS_EXTENSION</TT>.
  301. POSIX does not require that names such as
  302. <TT>PATH_MAX</TT>
  303. and
  304. <TT>OPEN_MAX</TT>
  305. be defined in
  306. <TT><limits.h></TT>,
  307. but many programs assume they are defined there.
  308. If
  309. <TT>_LIMITS_EXTENSION</TT>
  310. is defined, those names will all be defined when
  311. <TT><limits.h></TT>
  312. is included.
  313. <DT> -<DD>
  314. <TT>_BSD_EXTENSION</TT>.
  315. This extension includes not only Berkeley Unix routines,
  316. but also a grab bag of other miscellaneous routines often
  317. found in Unix implementations.
  318. The extension allows the inclusion of any of:
  319. <TT><bsd.h></TT>
  320. for
  321. <TT>bcopy()</TT>,
  322. <TT>bcmp()</TT>,
  323. and similar Berkeley functions;
  324. <TT><netdb.h></TT>
  325. for
  326. <TT>gethostbyname()</TT>,
  327. etc.,
  328. and associated structures;
  329. <TT><select.h></TT>
  330. for the Berkeley
  331. <TT>select</TT>
  332. function and associated types and macros
  333. for dealing with multiple input sources;
  334. <TT><sys/ioctl.h></TT>
  335. for the
  336. <TT>ioctl</TT>
  337. function (minimally implemented);
  338. <TT><sys/param.h></TT>
  339. for
  340. <TT>NOFILES_MAX</TT>;
  341. <TT><sys/pty.h></TT>
  342. for pseudo-tty support via the
  343. <TT>ptsname(int)</TT>
  344. and
  345. <TT>ptmname(int)</TT>
  346. functions;
  347. <TT><sys/resource.h></TT>;
  348. <TT><sys/socket.h></TT>
  349. for socket structures, constants, and functions;
  350. <TT><sys/time.h></TT>
  351. for definitions of the
  352. <TT>timeval</TT>
  353. and
  354. <TT>timezone</TT>
  355. structures;
  356. and
  357. <TT><sys/uio.h></TT>
  358. for the
  359. <TT>iovec</TT>
  360. structure and the
  361. <TT>writev</TT>
  362. and
  363. <TT>readv</TT>
  364. functions used for scatter/gather I/O.
  365. Defining
  366. <TT>_BSD_EXTENSION</TT>
  367. also enables various extra definitions in
  368. <TT><ctype.h></TT>,
  369. <TT><signal.h></TT>,
  370. <TT><stdio.h></TT>,
  371. <TT><unistd.h></TT>,
  372. <TT><sys/stat.h></TT>,
  373. and
  374. <TT><sys/times.h></TT>.
  375. <DT> -<DD>
  376. <TT>_NET_EXTENSION</TT>.
  377. This extension allows inclusion of
  378. <TT><libnet.h></TT>,
  379. which defines the networking functions described in the Plan 9 manual page
  380. <A href="/magic/man2html/2/dial"><I>dial</I>(2).
  381. </A><DT> -<DD>
  382. <TT>_REGEXP_EXTENSION</TT>.
  383. This extension allows inclusion of
  384. <TT><regexp.h></TT>,
  385. which defines the regular expression matching functions described
  386. in the Plan 9 manual page
  387. <A href="/magic/man2html/2/regexp"><I>regexp</I>(2).
  388. </A><DT> -<DD>
  389. <TT>_RESEARCH_SOURCE</TT>.
  390. This extension enables a small library of functions from the Tenth Edition Unix
  391. Research System (V10).
  392. These functions and the types needed to use them are all defined in the
  393. <TT><libv.h></TT>
  394. header.
  395. The provided functions are:
  396. <TT>srand</TT>,
  397. <TT>rand</TT>,
  398. <TT>nrand</TT>,
  399. <TT>lrand</TT>,
  400. and
  401. <TT>frand</TT>
  402. (better random number generators);
  403. <TT>getpass</TT>,
  404. <TT>tty_echoon</TT>,
  405. <TT>tty_echooff</TT>
  406. (for dealing with the common needs for mucking with terminal
  407. characteristics);
  408. <TT>min</TT>
  409. and
  410. <TT>max</TT>;
  411. <TT>nap</TT>;
  412. and
  413. <TT>setfields</TT>,
  414. <TT>getfields</TT>,
  415. and
  416. <TT>getmfields</TT>
  417. (for parsing a line into fields).
  418. See the Research Unix System Programmer's Manual, Tenth Edition, for a description
  419. of these functions.
  420. </dl>
  421. <H4>Common Problems
  422. </H4>
  423. <P>
  424. Some large systems, including X11, have been ported successfully
  425. to Plan 9 using APE
  426. (the X11 port is not included in the distribution, however,
  427. because supporting it properly is too big a job).
  428. The problems encountered fall into three categories:
  429. (1) non-ANSI C/POSIX features used; (2) inadequate simulation of POSIX functions;
  430. and (3) compiler/loader bugs.
  431. By far the majority of problems are in the first category.
  432. </P>
  433. <P>
  434. POSIX is just starting to be a target for programmers.
  435. Most existing code is written to work with one or both of a BSD or a System V Unix.
  436. System V is fairly close to POSIX, but there are some differences.
  437. Also, many System V systems have imported some BSD features that are
  438. not part of POSIX.
  439. A good strategy for porting external programs is to first try using
  440. <TT>CFLAGS=-D_POSIX_SOURCE</TT>;
  441. if that doesn't work, try adding
  442. <TT>_D_BSD_EXTENSION</TT>
  443. and perhaps include
  444. <TT><bsd.h></TT>
  445. in source files.
  446. Here are some solutions to problems that might remain:
  447. </P>
  448. <DL COMPACT>
  449. <DT> -<DD>
  450. Third (environment) argument to
  451. <TT>main</TT>.
  452. Use the
  453. <TT>environ</TT>
  454. global instead.
  455. <DT> -<DD>
  456. <TT>OPEN_MAX</TT>,
  457. <TT>PATH_MAX</TT>,
  458. etc., assumed in
  459. <TT><limits.h></TT>.
  460. Rewrite to call
  461. <TT>sysconf</TT>
  462. or define
  463. <TT>_LIMITS_EXTENSION</TT>.
  464. <DT> -<DD>
  465. <TT><varargs.h></TT>.
  466. Rewrite to use
  467. <TT><stdarg.h></TT>.
  468. </dl>
  469. <P>
  470. The second class of problems has to do with inadequacies in the Plan 9
  471. simulation of POSIX functions.
  472. These shortcomings have rarely gotten in the way
  473. (except, perhaps, for the
  474. <TT>link</TT>
  475. problem).
  476. </P>
  477. <DL COMPACT>
  478. <DT> -<DD>
  479. Functions for setting the userid, groupid, effective userid and effective groupid
  480. do not do anything useful. The concept is impossible to simulate in Plan 9.
  481. <TT>Chown</TT>
  482. also does nothing.
  483. <DT> -<DD>
  484. <TT>execlp</TT>
  485. and the related functions do not look at the
  486. <TT>PATH</TT>
  487. environment variable. They just try the current directory and
  488. <TT>/bin</TT>
  489. if the pathname is not absolute.
  490. <DT> -<DD>
  491. Advisory locking via
  492. <TT>fcntl</TT>
  493. is not implemented.
  494. <DT> -<DD>
  495. <TT>isatty</TT>
  496. is hard to do correctly.
  497. The approximation used is only sometimes correct.
  498. <DT> -<DD>
  499. <TT>link</TT>
  500. always fails.
  501. <DT> -<DD>
  502. With
  503. <TT>open</TT>,
  504. the
  505. <TT>O_NOCTTY</TT>
  506. option has no effect.
  507. The concept of a controlling tty is foreign to Plan 9.
  508. <DT> -<DD>
  509. <TT>setsid</TT>
  510. forks the name space and note group,
  511. which is only approximately the right behavior.
  512. <DT> -<DD>
  513. The functions dealing with stacking signals,
  514. <TT>sigpending</TT>,
  515. <TT>sigprocmask</TT>
  516. and
  517. <TT>sigsuspend</TT>,
  518. do not work.
  519. <DT> -<DD>
  520. <TT>umask</TT>
  521. has no effect, as there is no such concept in Plan 9.
  522. <DT> -<DD>
  523. code that does
  524. <TT>getenv("HOME")</TT>
  525. should be changed to
  526. <TT>getenv("home")</TT>
  527. on Plan 9.
  528. </dl>
  529. <br>&#32;<br>
  530. <A href=http://www.lucent.com/copyright.html>
  531. Copyright</A> &#169; 2000 Lucent Technologies Inc. All rights reserved.
  532. </body></html>