.HTML "APE — The ANSI/POSIX Environment.de XX.IP \ \ \ \-...TLAPE \(em The ANSI/POSIX Environment.AUHoward Trickeyhoward@plan9.bell-labs.com.SHIntroduction.PPWhen a large or frequently-updated program must be portedto or from Plan 9, the ANSI/POSIX environment known as APE can be useful.APE combines the set of headers and object code libraries specified bythe ANSI C standard (ANSI X3.159-1989) with the POSIX operating systeminterface standard (IEEE 1003.1-1990, ISO 9945-1), the part of POSIXdefining the basic operating system functions.Using APE will cause slower compilation and marginally slower execution speeds,so if the importing or exporting happens only infrequently, due considerationshould be given to using the usual Plan 9 compilation environment instead.Another factor to consider is that the Plan 9 header organization ismuch simpler to remember and use..PPThere are some aspects of required POSIX behavior that are impossible orvery hard to simulate in Plan 9. They are described below.Experience has shown, however, that the simulation is adequate for thevast majority of programs. A much more common problem is thatmany programs use functions or headers not defined by POSIX.APE has some extensions to POSIX to help in this regard.Extensions must be explicitly enabled with an appropriate.CW #define ,in order that the APE environment be a good aid for testingANSI/POSIX compliance of programs..SHPcc.PPThe.CW pcccommand acts as a front end to the Plan 9 C compilers and loaders.It runs an ANSI C preprocessor over source files, using the APEheaders to satisfy.CW "#include <\fIfile\fP>"directives; then it runs a Plan 9 C compiler; finally, it may loadwith APE libraries to produce an executable program.The document.I "How to Use the Plan 9 C Compiler"explains how environment variables are used by convention tohandle compilation for differing architectures.The environment variable.CW $objtypecontrols which Plan 9 compiler and loader are used by.CW pcc ,as well as the location of header and library files.For example, if.CW $objtypeis.CW mips ,then.CW pcchas.CW cpplook for headers in.CW /mips/include/apefollowed by.CW /sys/include/ape ;then.CW pccuses.CW vcto create.CW .vobject files;finally,.CW vlis used to create an executable using libraries in.CW /mips/lib/ape ..SHPsh and Cc.PPThe.CW pcccommand is intended for uses where the source code isANSI/POSIX, but the programs are built in the usual Plan 9manner \(em with.CW mkand producing object files with names ending in.CW .v ,etc.Sometimes it is best to use the standard POSIX.CW makeand.CW cc(which produces object files with names ending in.CW .o ,and automatically calls the loader unless.CW -cis specified).Under these circumstances, execute the command:.DS.CW "ape/psh".DEThis starts a POSIX shell, with an environment thatincludes the POSIX commands.CW ar89 ,.CW c89 ,.CW cc ,.CW basename ,.CW dirname ,.CW expr ,.CW false ,.CW grep ,.CW kill ,.CW make ,.CW rmdir ,.CW sed ,.CW sh ,.CW stty ,.CW true ,.CW uname ,and.CW yacc .There are also a few placeholders for commands that cannot beimplemented in Plan 9:.CW chown ,.CW ln ,and.CW umask ..PPThe.CW cccommand accepts the options mandated forthe POSIX command.CW c89 ,as specified in the C-Language Development Utilities Optionannex of the POSIX Shell and Utilities standard.It also accepts the following nonstandard options:.CW -vfor echoing the commands for each pass to stdout;.CW -Ato turn on ANSI prototype warnings;.CW -Sto leave assembly language in.I file .s;.CW -Wp,\fIargs\fPto pass.I argsto the.CW cpp ;.CW -W0,\fIargs\fPto pass.I argsto 2c, etc.;and.CW -Wl,\fIargs\fPto pass.I argsto 2l, etc..PPThe.CW shcommand is pdksh, a mostly POSIX-compliant public domain Korn Shell.The Plan 9 implementation does not includethe emacs and vi editing modes..PPThe.CW sttycommand only has effect if the.CW ape/ptyfscommand has been started to interpose a pseudo-tty interfacebetween.CW /dev/consand the running command.None of the distributed commands do this automatically..SHSymbols.PPThe C and POSIX standards require that certain symbols bedefined in headers.They also require that certain other classes of symbols notbe defined in the headers, and specify certain othersymbols that may be defined in headers at the discretionof the implementation.POSIX defines.I "feature test macros" ,which are preprocessor symbols beginning with an underscoreand then a capital letter; if the program.CW #definesa feature test macro before the inclusion of any headers,then it is requesting that certain symbols be visible in the headers.The most important feature test macro is.CW _POSIX_SOURCE :when it is defined, exactly the symbols required by POSIX arevisible in the appropriate headers.Consider.CW <signal.h>for example:ANSI defines some names that must be defined in.CW <signal.h> ,but POSIX defines others, such as.CW sigset_t ,which are not allowed according to ANSI.The solution is to make the additional symbols visible only when.CW _POSIX_SOURCEis defined..PPTo export a program, it helps to know whether it fitsin one of the following categories:.IP 1.Strictly conforming ANSI C program. It only uses features of the language,libraries, and headers explicitly required by the C standard. It does notdepend on unspecified, undefined, or implementation-dependent behavior,and does not exceed any minimum implementation limit..IP 2.Strictly conforming POSIX program. Similar, but for the POSIX standard as well..IP 3.Some superset of POSIX, with extensions. Each extensionis selected by a feature test macro, so it is clear which extensionsare being used..PPWith APE, if headers are always included to declare any library functionsused, then the set of feature test macros defined by a program willshow which of the above categories the program is in.To accomplish this, no symbol is defined in a header if it is not requiredby the C or POSIX standard, and those required by the POSIX standardare protected by.CW "#ifdef _POSIX_SOURCE" .For example,.CW <errno.h>defines.CW EDOM ,.CW ERANGE ,and.CW errno ,as required by the C standard.The C standard allows more names beginning with.CW E ,but our header defines only those unless.CW _POSIX_SOURCEis defined, in which case the symbols required by POSIX are also defined.This means that a program that uses.CW ENAMETOOLONGcannot masquerade as a strictly conforming ANSI C program..PP.CW Pccand.CW ccdo not predefine any preprocessor symbols except those required bythe ANSI C standard:.CW __STDC__ ,.CW __LINE__ ,.CW __FILE__ ,.CW __DATE__ ,and.CW __TIME__ .Any others must be defined in the program itself or by using.CW -Don the command line..SHExtensions.PPThe discipline enforced by putting only requirednames in the headers is useful for exporting programs,but it gets in the way when importing programs.The compromise is to allow additional symbols in headers,additional headers, and additional library functions,but only under control of extension feature test macros.The following extensions are provided; unless otherwisespecified, the additional library functions are in thedefault APE library..XX.CW _LIBG_EXTENSION .This allows the use of the Plan 9 graphics library.The functions are as described in the Plan 9 manual (see.I graphics (2))except that.CW divhad to be renamed.CW ptdiv .Include the.CW <libg.h>header to declare the needed types and functions..XX.CW _LIMITS_EXTENSION .POSIX does not require that names such as.CW PATH_MAXand.CW OPEN_MAXbe defined in.CW <limits.h> ,but many programs assume they are defined there.If.CW _LIMITS_EXTENSIONis defined, those names will all be defined when.CW <limits.h>is included..XX.CW _BSD_EXTENSION .This extension includes not only Berkeley Unix routines,but also a grab bag of other miscellaneous routines oftenfound in Unix implementations.The extension allows the inclusion of any of:.CW <bsd.h>for.CW bcopy() ,.CW bcmp() ,and similar Berkeley functions;.CW <netdb.h>for.CW gethostbyname() ,etc.,and associated structures;.CW <select.h>for the Berkeley.CW selectfunction and associated types and macrosfor dealing with multiple input sources;.CW <sys/ioctl.h>for the.CW ioctlfunction (minimally implemented);.CW <sys/param.h>for.CW NOFILES_MAX ;.CW <sys/pty.h>for pseudo-tty support via the.CW ptsname(int)and.CW ptmname(int)functions;.CW <sys/resource.h> ;.CW <sys/socket.h>for socket structures, constants, and functions;.CW <sys/time.h>for definitions of the.CW timevaland.CW timezonestructures;and.CW <sys/uio.h>for the.CW iovecstructure and the.CW writevand.CW readvfunctions used for scatter/gather I/O.Defining.CW _BSD_EXTENSIONalso enables various extra definitions in.CW <ctype.h> ,.CW <signal.h> ,.CW <stdio.h> ,.CW <unistd.h> ,.CW <sys/stat.h> ,and.CW <sys/times.h> ..XX.CW _NET_EXTENSION .This extension allows inclusion of.CW <libnet.h> ,which defines the networking functions described in the Plan 9 manual page.I dial (2)..XX.CW _PLAN9_EXTENSION .This extension allows inclusion of.CW <u.h> ,.CW <lock.h> ,.CW <qlock.h> ,.CW <utf.h> ,.CW <fmt.h> ,and.CW <draw.h> .These are pieces of Plan 9 source code ported into APE,mostly from .CW <libc.h> ..XX.CW _REGEXP_EXTENSION .This extension allows inclusion of.CW <regexp.h> ,which defines the regular expression matching functions describedin the Plan 9 manual page.I regexp (2)..XX.CW _RESEARCH_SOURCE .This extension enables a small library of functions from the Tenth Edition UnixResearch System (V10).These functions and the types needed to use them are all defined in the.CW <libv.h>header.The provided functions are:.CW srand ,.CW rand ,.CW nrand ,.CW lrand ,and.CW frand(better random number generators);.CW getpass ,.CW tty_echoon ,.CW tty_echooff(for dealing with the common needs for mucking with terminalcharacteristics);.CW minand.CW max ;.CW nap ;and.CW setfields ,.CW getfields ,and.CW getmfields(for parsing a line into fields).See the Research Unix System Programmer's Manual, Tenth Edition, for a descriptionof these functions..XX.CW _C99_SNPRINTF_EXTENSION .This extension permits the use of the return values of.I snprintfand.I vsnprintf .Before C99, the 1999 C standard,these functions usually returned the number of bytes,excluding terminating NUL,actually stored in the target string.(GNU, as usual, had to be different and returned -1 if the targetstring was too small.)C99 requires them to instead return the number of bytes,excluding terminating NUL,that would have been written into the target string if it were infinitely largeor a negative value if an `encoding error' occurs,so old programs compiled under C99 rules will be prone to overrunningtheir buffers.This extension is a way for the programmer to declare that he or she understandsthe situation and has adjusted the code being compiled to compensate..SHCommon Problems.PPSome large systems, including X11, have been ported successfullyto Plan 9 using APE(the X11 port is not included in the distribution, however,because supporting it properly is too big a job).The problems encountered fall into three categories:(1) non-ANSI C/POSIX features used; (2) inadequate simulation of POSIX functions;and (3) compiler/loader bugs.By far the majority of problems are in the first category..PPPOSIX is just starting to be a target for programmers.Most existing code is written to work with one or both of a BSD or a System V Unix.System V is fairly close to POSIX, but there are some differences.Also, many System V systems have imported some BSD features that arenot part of POSIX.A good strategy for porting external programs is to first try using.CW CFLAGS=-D_POSIX_SOURCE ;if that doesn't work, try adding.CW _D_BSD_EXTENSIONand perhaps include.CW <bsd.h>in source files.Here are some solutions to problems that might remain:.XXThird (environment) argument to.CW main .Use the.CW environglobal instead..XX.CW OPEN_MAX ,.CW PATH_MAX ,etc., assumed in.CW <limits.h> .Rewrite to call.CW sysconfor define.CW _LIMITS_EXTENSION ..XX.CW <varargs.h> .Rewrite to use.CW <stdarg.h> ..PPThe second class of problems has to do with inadequacies in the Plan 9simulation of POSIX functions.These shortcomings have rarely gotten in the way(except, perhaps, for the.CW linkproblem)..XXFunctions for setting the userid, groupid, effective userid and effective groupiddo not do anything useful. The concept is impossible to simulate in Plan 9..CW Chownalso does nothing..XX.CW execlpand the related functions do not look at the.CW PATHenvironment variable. They just try the current directory and.CW /binif the pathname is not absolute..XXLines 1–500 of 537. Load more
.HTML "APE — The ANSI/POSIX Environment .de XX .IP \ \ \ \- .. .TL APE \(em The ANSI/POSIX Environment .AU Howard Trickey howard@plan9.bell-labs.com .SH Introduction .PP When a large or frequently-updated program must be ported to or from Plan 9, the ANSI/POSIX environment known as APE can be useful. APE combines the set of headers and object code libraries specified by the ANSI C standard (ANSI X3.159-1989) with the POSIX operating system interface standard (IEEE 1003.1-1990, ISO 9945-1), the part of POSIX defining the basic operating system functions. Using APE will cause slower compilation and marginally slower execution speeds, so if the importing or exporting happens only infrequently, due consideration should be given to using the usual Plan 9 compilation environment instead. Another factor to consider is that the Plan 9 header organization is much simpler to remember and use. .PP There are some aspects of required POSIX behavior that are impossible or very hard to simulate in Plan 9. They are described below. Experience has shown, however, that the simulation is adequate for the vast majority of programs. A much more common problem is that many programs use functions or headers not defined by POSIX. APE has some extensions to POSIX to help in this regard. Extensions must be explicitly enabled with an appropriate .CW #define , in order that the APE environment be a good aid for testing ANSI/POSIX compliance of programs. .SH Pcc .PP The .CW pcc command acts as a front end to the Plan 9 C compilers and loaders. It runs an ANSI C preprocessor over source files, using the APE headers to satisfy .CW "#include <\fIfile\fP>" directives; then it runs a Plan 9 C compiler; finally, it may load with APE libraries to produce an executable program. The document .I "How to Use the Plan 9 C Compiler" explains how environment variables are used by convention to handle compilation for differing architectures. The environment variable .CW $objtype controls which Plan 9 compiler and loader are used by .CW pcc , as well as the location of header and library files. For example, if .CW $objtype is .CW mips , then .CW pcc has .CW cpp look for headers in .CW /mips/include/ape followed by .CW /sys/include/ape ; then .CW pcc uses .CW vc to create .CW .v object files; finally, .CW vl is used to create an executable using libraries in .CW /mips/lib/ape . .SH Psh and Cc .PP The .CW pcc command is intended for uses where the source code is ANSI/POSIX, but the programs are built in the usual Plan 9 manner \(em with .CW mk and producing object files with names ending in .CW .v , etc. Sometimes it is best to use the standard POSIX .CW make and .CW cc (which produces object files with names ending in .CW .o , and automatically calls the loader unless .CW -c is specified). Under these circumstances, execute the command: .DS .CW "ape/psh" .DE This starts a POSIX shell, with an environment that includes the POSIX commands .CW ar89 , .CW c89 , .CW cc , .CW basename , .CW dirname , .CW expr , .CW false , .CW grep , .CW kill , .CW make , .CW rmdir , .CW sed , .CW sh , .CW stty , .CW true , .CW uname , and .CW yacc . There are also a few placeholders for commands that cannot be implemented in Plan 9: .CW chown , .CW ln , and .CW umask . .PP The .CW cc command accepts the options mandated for the POSIX command .CW c89 , as specified in the C-Language Development Utilities Option annex of the POSIX Shell and Utilities standard. It also accepts the following nonstandard options: .CW -v for echoing the commands for each pass to stdout; .CW -A to turn on ANSI prototype warnings; .CW -S to leave assembly language in .I file .s; .CW -Wp,\fIargs\fP to pass .I args to the .CW cpp ; .CW -W0,\fIargs\fP to pass .I args to 2c, etc.; and .CW -Wl,\fIargs\fP to pass .I args to 2l, etc. .PP The .CW sh command is pdksh, a mostly POSIX-compliant public domain Korn Shell. The Plan 9 implementation does not include the emacs and vi editing modes. .PP The .CW stty command only has effect if the .CW ape/ptyfs command has been started to interpose a pseudo-tty interface between .CW /dev/cons and the running command. None of the distributed commands do this automatically. .SH Symbols .PP The C and POSIX standards require that certain symbols be defined in headers. They also require that certain other classes of symbols not be defined in the headers, and specify certain other symbols that may be defined in headers at the discretion of the implementation. POSIX defines .I "feature test macros" , which are preprocessor symbols beginning with an underscore and then a capital letter; if the program .CW #defines a feature test macro before the inclusion of any headers, then it is requesting that certain symbols be visible in the headers. The most important feature test macro is .CW _POSIX_SOURCE : when it is defined, exactly the symbols required by POSIX are visible in the appropriate headers. Consider .CW <signal.h> for example: ANSI defines some names that must be defined in .CW <signal.h> , but POSIX defines others, such as .CW sigset_t , which are not allowed according to ANSI. The solution is to make the additional symbols visible only when .CW _POSIX_SOURCE is defined. .PP To export a program, it helps to know whether it fits in one of the following categories: .IP 1. Strictly conforming ANSI C program. It only uses features of the language, libraries, and headers explicitly required by the C standard. It does not depend on unspecified, undefined, or implementation-dependent behavior, and does not exceed any minimum implementation limit. .IP 2. Strictly conforming POSIX program. Similar, but for the POSIX standard as well. .IP 3. Some superset of POSIX, with extensions. Each extension is selected by a feature test macro, so it is clear which extensions are being used. .PP With APE, if headers are always included to declare any library functions used, then the set of feature test macros defined by a program will show which of the above categories the program is in. To accomplish this, no symbol is defined in a header if it is not required by the C or POSIX standard, and those required by the POSIX standard are protected by .CW "#ifdef _POSIX_SOURCE" . For example, .CW <errno.h> defines .CW EDOM , .CW ERANGE , and .CW errno , as required by the C standard. The C standard allows more names beginning with .CW E , but our header defines only those unless .CW _POSIX_SOURCE is defined, in which case the symbols required by POSIX are also defined. This means that a program that uses .CW ENAMETOOLONG cannot masquerade as a strictly conforming ANSI C program. .PP .CW Pcc and .CW cc do not predefine any preprocessor symbols except those required by the ANSI C standard: .CW __STDC__ , .CW __LINE__ , .CW __FILE__ , .CW __DATE__ , and .CW __TIME__ . Any others must be defined in the program itself or by using .CW -D on the command line. .SH Extensions .PP The discipline enforced by putting only required names in the headers is useful for exporting programs, but it gets in the way when importing programs. The compromise is to allow additional symbols in headers, additional headers, and additional library functions, but only under control of extension feature test macros. The following extensions are provided; unless otherwise specified, the additional library functions are in the default APE library. .XX .CW _LIBG_EXTENSION . This allows the use of the Plan 9 graphics library. The functions are as described in the Plan 9 manual (see .I graphics (2)) except that .CW div had to be renamed .CW ptdiv . Include the .CW <libg.h> header to declare the needed types and functions. .XX .CW _LIMITS_EXTENSION . POSIX does not require that names such as .CW PATH_MAX and .CW OPEN_MAX be defined in .CW <limits.h> , but many programs assume they are defined there. If .CW _LIMITS_EXTENSION is defined, those names will all be defined when .CW <limits.h> is included. .XX .CW _BSD_EXTENSION . This extension includes not only Berkeley Unix routines, but also a grab bag of other miscellaneous routines often found in Unix implementations. The extension allows the inclusion of any of: .CW <bsd.h> for .CW bcopy() , .CW bcmp() , and similar Berkeley functions; .CW <netdb.h> for .CW gethostbyname() , etc., and associated structures; .CW <select.h> for the Berkeley .CW select function and associated types and macros for dealing with multiple input sources; .CW <sys/ioctl.h> for the .CW ioctl function (minimally implemented); .CW <sys/param.h> for .CW NOFILES_MAX ; .CW <sys/pty.h> for pseudo-tty support via the .CW ptsname(int) and .CW ptmname(int) functions; .CW <sys/resource.h> ; .CW <sys/socket.h> for socket structures, constants, and functions; .CW <sys/time.h> for definitions of the .CW timeval and .CW timezone structures; and .CW <sys/uio.h> for the .CW iovec structure and the .CW writev and .CW readv functions used for scatter/gather I/O. Defining .CW _BSD_EXTENSION also enables various extra definitions in .CW <ctype.h> , .CW <signal.h> , .CW <stdio.h> , .CW <unistd.h> , .CW <sys/stat.h> , and .CW <sys/times.h> . .XX .CW _NET_EXTENSION . This extension allows inclusion of .CW <libnet.h> , which defines the networking functions described in the Plan 9 manual page .I dial (2). .XX .CW _PLAN9_EXTENSION . This extension allows inclusion of .CW <u.h> , .CW <lock.h> , .CW <qlock.h> , .CW <utf.h> , .CW <fmt.h> , and .CW <draw.h> . These are pieces of Plan 9 source code ported into APE, mostly from .CW <libc.h> . .XX .CW _REGEXP_EXTENSION . This extension allows inclusion of .CW <regexp.h> , which defines the regular expression matching functions described in the Plan 9 manual page .I regexp (2). .XX .CW _RESEARCH_SOURCE . This extension enables a small library of functions from the Tenth Edition Unix Research System (V10). These functions and the types needed to use them are all defined in the .CW <libv.h> header. The provided functions are: .CW srand , .CW rand , .CW nrand , .CW lrand , and .CW frand (better random number generators); .CW getpass , .CW tty_echoon , .CW tty_echooff (for dealing with the common needs for mucking with terminal characteristics); .CW min and .CW max ; .CW nap ; and .CW setfields , .CW getfields , and .CW getmfields (for parsing a line into fields). See the Research Unix System Programmer's Manual, Tenth Edition, for a description of these functions. .XX .CW _C99_SNPRINTF_EXTENSION . This extension permits the use of the return values of .I snprintf and .I vsnprintf . Before C99, the 1999 C standard, these functions usually returned the number of bytes, excluding terminating NUL, actually stored in the target string. (GNU, as usual, had to be different and returned -1 if the target string was too small.) C99 requires them to instead return the number of bytes, excluding terminating NUL, that would have been written into the target string if it were infinitely large or a negative value if an `encoding error' occurs, so old programs compiled under C99 rules will be prone to overrunning their buffers. This extension is a way for the programmer to declare that he or she understands the situation and has adjusted the code being compiled to compensate. .SH Common Problems .PP Some large systems, including X11, have been ported successfully to Plan 9 using APE (the X11 port is not included in the distribution, however, because supporting it properly is too big a job). The problems encountered fall into three categories: (1) non-ANSI C/POSIX features used; (2) inadequate simulation of POSIX functions; and (3) compiler/loader bugs. By far the majority of problems are in the first category. .PP POSIX is just starting to be a target for programmers. Most existing code is written to work with one or both of a BSD or a System V Unix. System V is fairly close to POSIX, but there are some differences. Also, many System V systems have imported some BSD features that are not part of POSIX. A good strategy for porting external programs is to first try using .CW CFLAGS=-D_POSIX_SOURCE ; if that doesn't work, try adding .CW _D_BSD_EXTENSION and perhaps include .CW <bsd.h> in source files. Here are some solutions to problems that might remain: .XX Third (environment) argument to .CW main . Use the .CW environ global instead. .XX .CW OPEN_MAX , .CW PATH_MAX , etc., assumed in .CW <limits.h> . Rewrite to call .CW sysconf or define .CW _LIMITS_EXTENSION . .XX .CW <varargs.h> . Rewrite to use .CW <stdarg.h> . .PP The second class of problems has to do with inadequacies in the Plan 9 simulation of POSIX functions. These shortcomings have rarely gotten in the way (except, perhaps, for the .CW link problem). .XX Functions for setting the userid, groupid, effective userid and effective groupid do not do anything useful. The concept is impossible to simulate in Plan 9. .CW Chown also does nothing. .XX .CW execlp and the related functions do not look at the .CW PATH environment variable. They just try the current directory and .CW /bin if the pathname is not absolute. .XX