1 .HTML "APE — The ANSI/POSIX Environment
6 APE \(em The ANSI/POSIX Environment
9 howard@plan9.bell-labs.com
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.
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
33 in order that the APE environment be a good aid for testing
34 ANSI/POSIX compliance of programs.
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
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.
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
52 controls which Plan 9 compiler and loader are used by
54 as well as the location of header and library files.
66 .CW /sys/include/ape ;
76 is used to create an executable using libraries in
83 command is intended for uses where the source code is
84 ANSI/POSIX, but the programs are built in the usual Plan 9
87 and producing object files with names ending in
90 Sometimes it is best to use the standard POSIX
94 (which produces object files with names ending in
96 and automatically calls the loader unless
99 Under these circumstances, execute the command:
103 This starts a POSIX shell, with an environment that
104 includes the POSIX commands
123 There are also a few placeholders for commands that cannot be
124 implemented in Plan 9:
132 command accepts the options mandated for
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:
139 for echoing the commands for each pass to stdout;
141 to turn on ANSI prototype warnings;
143 to leave assembly language in
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.
168 command only has effect if the
170 command has been started to interpose a pseudo-tty interface
173 and the running command.
174 None of the distributed commands do this automatically.
178 The C and POSIX standards require that certain symbols be
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.
185 .I "feature test macros" ,
186 which are preprocessor symbols beginning with an underscore
187 and then a capital letter; if the program
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
193 when it is defined, exactly the symbols required by POSIX are
194 visible in the appropriate headers.
198 ANSI defines some names that must be defined in
200 but POSIX defines others, such as
202 which are not allowed according to ANSI.
203 The solution is to make the additional symbols visible only when
207 To export a program, it helps to know whether it fits
208 in one of the following categories:
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.
215 Strictly conforming POSIX program. Similar, but for the POSIX standard as well.
217 Some superset of POSIX, with extensions. Each extension
218 is selected by a feature test macro, so it is clear which extensions
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
227 .CW "#ifdef _POSIX_SOURCE" .
235 as required by the C standard.
236 The C standard allows more names beginning with
238 but our header defines only those unless
240 is defined, in which case the symbols required by POSIX are also defined.
241 This means that a program that uses
243 cannot masquerade as a strictly conforming ANSI C program.
248 do not predefine any preprocessor symbols except those required by
256 Any others must be defined in the program itself or by using
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
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
282 header to declare the needed types and functions.
284 .CW _LIMITS_EXTENSION .
285 POSIX does not require that names such as
291 but many programs assume they are defined there.
293 .CW _LIMITS_EXTENSION
294 is defined, those names will all be defined when
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:
307 and similar Berkeley functions;
310 .CW gethostbyname() ,
312 and associated structures;
316 function and associated types and macros
317 for dealing with multiple input sources;
321 function (minimally implemented);
326 for pseudo-tty support via the
331 .CW <sys/resource.h> ;
333 for socket structures, constants, and functions;
335 for definitions of the
348 functions used for scatter/gather I/O.
351 also enables various extra definitions in
361 This extension allows inclusion of
363 which defines the networking functions described in the Plan 9 manual page
366 .CW _PLAN9_EXTENSION .
367 This extension allows inclusion of
375 These are pieces of Plan 9 source code ported into APE,
379 .CW _REGEXP_EXTENSION .
380 This extension allows inclusion of
382 which defines the regular expression matching functions described
383 in the Plan 9 manual page
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
392 The provided functions are:
399 (better random number generators);
403 (for dealing with the common needs for mucking with terminal
414 (for parsing a line into fields).
415 See the Research Unix System Programmer's Manual, Tenth Edition, for a description
418 .CW _C99_SNPRINTF_EXTENSION .
419 This extension permits the use of the return values of
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
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.
440 Some large systems, including X11, have been ported successfully
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.
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
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
461 Here are some solutions to problems that might remain:
463 Third (environment) argument to
476 .CW _LIMITS_EXTENSION .
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
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.
495 and the related functions do not look at the
497 environment variable. They just try the current directory and
499 if the pathname is not absolute.
506 is hard to do correctly.
507 The approximation used is only sometimes correct.
516 option has no effect.
517 The concept of a controlling tty is foreign to Plan 9.
520 forks the name space and note group,
521 which is only approximately the right behavior.
523 The functions dealing with stacking signals,
531 has no effect, as there is no such concept in Plan 9.