ape.ms 13 KB

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