1
0

ape.ms 12 KB

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