diff options
Diffstat (limited to 'man1p/c99.1p')
| -rw-r--r-- | man1p/c99.1p | 745 |
1 files changed, 745 insertions, 0 deletions
diff --git a/man1p/c99.1p b/man1p/c99.1p new file mode 100644 index 000000000..58b2b2352 --- /dev/null +++ b/man1p/c99.1p @@ -0,0 +1,745 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "C99" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" c99 +.SH NAME +c99 \- compile standard C programs +.SH SYNOPSIS +.LP +\fBc99\fP \fB[\fP\fB-c\fP\fB][\fP\fB-D\fP +\fIname\fP\fB[\fP\fB=\fP\fIvalue\fP\fB]]\fP\fB...\fP\fB[\fP\fB-E\fP\fB][\fP\fB-g\fP\fB][\fP\fB-I\fP +\fIdirectory\fP\fB]\fP \fB...\fP \fB[\fP\fB-L\fP \fIdirectory\fP\fB]\fP\fB +.br +\ \ \ \ \ \ ...\fP \fB[\fP\fB-o\fP +\fIoutfile\fP\fB][\fP\fB-O\fP\fIoptlevel\fP\fB][\fP\fB-s\fP\fB][\fP\fB-U\fP +\fIname\fP\fB]\fP\fB...\fP +\fIoperand\fP \fB... \fP +.SH DESCRIPTION +.LP +The \fIc99\fP utility is an interface to the standard C compilation +system; it shall accept source code conforming to the +ISO\ C standard. The system conceptually consists of a compiler and +link editor. The files referenced by \fIoperand\fPs shall +be compiled and linked to produce an executable file. (It is unspecified +whether the linking occurs entirely within the operation +of \fIc99\fP; some implementations may produce objects that are not +fully resolved until the file is executed.) +.LP +If the \fB-c\fP option is specified, for all pathname operands of +the form \fIfile\fP \fB.c\fP, the files: +.sp +.RS +.nf + +\fB$(basename\fP \fIpathname\fP \fB.c).o +\fP +.fi +.RE +.LP +shall be created as the result of successful compilation. If the \fB-c\fP +option is not specified, it is unspecified whether +such \fB.o\fP files are created or deleted for the \fIfile\fP \fB.c\fP +operands. +.LP +If there are no options that prevent link editing (such as \fB-c\fP +or \fB-E\fP), and all operands compile and link without +error, the resulting executable file shall be written according to +the \fB-o\fP \fIoutfile\fP option (if present) or to the file +\fBa.out\fP. +.LP +The executable file shall be created as specified in \fIFile Read, +Write, and +Creation\fP , except that the file permission bits shall be set to: +.sp +.RS +.nf + +S_IRWXO | S_IRWXG | S_IRWXU +.fi +.RE +.LP +and the bits specified by the \fIumask\fP of the process shall be +cleared. +.SH OPTIONS +.LP +The \fIc99\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that: +.IP " *" 3 +The \fB-l\fP \fIlibrary\fP operands have the format of options, but +their position within a list of operands affects the order +in which libraries are searched. +.LP +.IP " *" 3 +The order of specifying the \fB-I\fP and \fB-L\fP options is significant. +.LP +.IP " *" 3 +Conforming applications shall specify each option separately; that +is, grouping option letters (for example, \fB-cO\fP) need +not be recognized by all implementations. +.LP +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Suppress the link-edit phase of the compilation, and do not remove +any object files that are produced. +.TP 7 +\fB-g\fP +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be +modified by implementation-defined interactions with other options. +.TP 7 +\fB-s\fP +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using +the \fIexec\fP family defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001 +has been removed (stripped). If +both \fB-g\fP and \fB-s\fP options are present, the action taken is +unspecified. +.TP 7 +\fB-o\ \fP \fIoutfile\fP +Use the pathname \fIoutfile\fP, instead of the default \fBa.out\fP, +for the executable file produced. If the \fB-o\fP option +is present with \fB-c\fP or \fB-E\fP, the result is unspecified. +.TP 7 +\fB-D\ \fP \fIname\fP\fB[=\fP\fIvalue\fP\fB]\fP +.sp +Define \fIname\fP as if by a C-language \fB#define\fP directive. If +no = \fIvalue\fP is given, a value of 1 shall be used. The +\fB-D\fP option has lower precedence than the \fB-U\fP option. That +is, if \fIname\fP is used in both a \fB-U\fP and a +\fB-D\fP option, \fIname\fP shall be undefined regardless of the order +of the options. Additional implementation-defined +\fIname\fPs may be provided by the compiler. Implementations shall +support at least 2048 bytes of \fB-D\fP definitions and 256 +\fInames\fP. +.TP 7 +\fB-E\fP +Copy C-language source files to standard output, expanding all preprocessor +directives; no compilation shall be performed. If +any operand is not a text file, the effects are unspecified. +.TP 7 +\fB-I\ \fP \fIdirectory\fP +Change the algorithm for searching for headers whose names are not +absolute pathnames to look in the directory named by the +\fIdirectory\fP pathname before looking in the usual places. Thus, +headers whose names are enclosed in double-quotes ( \fB""\fP +) shall be searched for first in the directory of the file with the +\fB#include\fP line, then in directories named in \fB-I\fP +options, and last in the usual places. For headers whose names are +enclosed in angle brackets ( \fB"<>"\fP ), the header +shall be searched for only in directories named in \fB-I\fP options +and then in the usual places. Directories named in \fB-I\fP +options shall be searched in the order specified. Implementations +shall support at least ten instances of this option in a single +\fIc99\fP command invocation. +.TP 7 +\fB-L\ \fP \fIdirectory\fP +Change the algorithm of searching for the libraries named in the \fB-l\fP +objects to look in the directory named by the +\fIdirectory\fP pathname before looking in the usual places. Directories +named in \fB-L\fP options shall be searched in the order +specified. Implementations shall support at least ten instances of +this option in a single \fIc99\fP command invocation. If a +directory specified by a \fB-L\fP option contains files named \fBlibc.a\fP, +\fBlibm.a\fP, \fBlibl.a\fP, or \fBliby.a\fP, the +results are unspecified. +.TP 7 +\fB-O\ \fP \fIoptlevel\fP +Specify the level of code optimization. If the \fIoptlevel\fP option-argument +is the digit \fB'0'\fP , all special code +optimizations shall be disabled. If it is the digit \fB'1'\fP , the +nature of the optimization is unspecified. If the \fB-O\fP +option is omitted, the nature of the system's default optimization +is unspecified. It is unspecified whether code generated in the +presence of the \fB-O\fP 0 option is the same as that generated when +\fB-O\fP is omitted. Other \fIoptlevel\fP values may be +supported. +.TP 7 +\fB-U\ \fP \fIname\fP +Remove any initial definition of \fIname\fP. +.sp +.LP +Multiple instances of the \fB-D\fP, \fB-I\fP, \fB-U\fP, and \fB-L\fP +options can be specified. +.SH OPERANDS +.LP +An \fIoperand\fP is either in the form of a pathname or the form \fB-l\fP +\fIlibrary\fP. The application shall ensure that at +least one operand of the pathname form is specified. The following +operands shall be supported: +.TP 7 +\fIfile.\fP\fBc\fP +A C-language source file to be compiled and optionally linked. The +application shall ensure that the operand is of this form if +the \fB-c\fP option is used. +.TP 7 +\fIfile.\fP\fBa\fP +A library of object files typically produced by the \fIar\fP utility, +and passed directly +to the link editor. Implementations may recognize implementation-defined +suffixes other than \fB.a\fP as denoting object file +libraries. +.TP 7 +\fIfile.\fP\fBo\fP +An object file produced by \fIc99\fP \fB-c\fP and passed directly +to the link editor. Implementations may recognize +implementation-defined suffixes other than \fB.o\fP as denoting object +files. +.sp +.LP +The processing of other files is implementation-defined. +.TP 7 +\fI-l\ library\fP +(The letter ell.) Search the library named: +.sp +.RS +.nf + +\fBlib\fP\fIlibrary\fP\fB.a +\fP +.fi +.RE +.LP +A library shall be searched when its name is encountered, so the placement +of a \fB-l\fP operand is significant. Several +standard libraries can be specified in this manner, as described in +the EXTENDED DESCRIPTION section. Implementations may recognize +implementation-defined suffixes other than \fB.a\fP as denoting libraries. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input file shall be one of the following: a text file containing +a C-language source program, an object file in the format +produced by \fIc99\fP \fB-c\fP, or a library of object files, in the +format produced by archiving zero or more object files, +using \fIar\fP. Implementations may supply additional utilities that +produce files in these +formats. Additional input file formats are implementation-defined. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIc99\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITMPDIR\fP +Provide a pathname that should override the default directory for +temporary files, if any. \ On +XSI-conforming systems, provide a pathname that shall override the +default directory for temporary files, if any. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If more than one \fIfile\fP operand ending in \fB.c\fP (or possibly +other unspecified suffixes) is given, for each such +file: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +may be written. These messages, if written, shall precede the processing +of each input file; they shall not be written to the +standard output if they are written to the standard error, as described +in the STDERR section. +.LP +If the \fB-E\fP option is specified, the standard output shall be +a text file that represents the results of the preprocessing +stage of the language; it may contain extra information appropriate +for subsequent compilation passes. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. If +more than one \fIfile\fP operand ending in \fB.c\fP (or +possibly other unspecified suffixes) is given, for each such file: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +may be written to allow identification of the diagnostic and warning +messages with the appropriate input file. These messages, +if written, shall precede the processing of each input file; they +shall not be written to the standard error if they are written to +the standard output, as described in the STDOUT section. +.LP +This utility may produce warning messages about certain conditions +that do not warrant returning an error (non-zero) exit +value. +.SH OUTPUT FILES +.LP +Object files or executable files or both are produced in unspecified +formats. +.SH EXTENDED DESCRIPTION +.SS Standard Libraries +.LP +The \fIc99\fP utility shall recognize the following \fB-l\fP operands +for standard libraries: +.TP 7 +\fB-l\ c\fP +This operand shall make visible all functions referenced in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, +with the possible exception of those functions listed as residing +in \fI<aio.h>\fP, \fI<arpa/inet.h>\fP, \fI<complex.h>\fP, \fI<fenv.h>\fP, +\fI<math.h>\fP, \fI<mqueue.h>\fP, \fI<netdb.h>\fP, \fI<netinet/in.h>\fP, +\fI<pthread.h>\fP, \fI<sched.h>\fP, \fI<semaphore.h>\fP, \fI<spawn.h>\fP, +\fI<sys/socket.h>\fP, \fIpthread_kill\fP(), and \fIpthread_sigmask\fP() +in \fI<signal.h>\fP, \fI<trace.h>\fP, functions +marked as extensions other than as part of the MF or MPR extensions +in \fI<sys/mman.h>\fP, functions marked as ADV in \fI<fcntl.h>\fP, +and functions marked as CS, CPT, and TMR in \fI<time.h>\fP. This operand +shall not be required to be present to cause a search of this +library. +.TP 7 +\fB-l\ l\fP +This operand shall make visible all functions required by the C-language +output of \fIlex\fP that are not made available through the \fB-l\ c\fP +operand. +.TP 7 +\fB-l\ pthread\fP +This operand shall make visible all functions referenced in \fI<pthread.h>\fP +and \fIpthread_kill\fP() and \fIpthread_sigmask\fP() referenced in +\fI<signal.h>\fP. An implementation may search this library in the +absence of this +operand. +.TP 7 +\fB-l\ m\fP +This operand shall make visible all functions referenced in \fI<math.h>\fP, +\fI<complex.h>\fP, and \fI<fenv.h>\fP. An +implementation may search this library in the absence of this operand. +.TP 7 +\fB-l\ rt\fP +This operand shall make visible all functions referenced in \fI<aio.h>\fP, +\fI<mqueue.h>\fP, \fI<sched.h>\fP, \fI<semaphore.h>\fP, and \fI<spawn.h>\fP, +functions marked as extensions other than as part of the MF or MPR +extensions in \fI<sys/mman.h>\fP, functions marked as ADV in \fI<fcntl.h>\fP, +and functions marked as CS, CPT, and TMR in \fI<time.h>\fP. An implementation +may search this library in the absence of this operand. +.TP 7 +\fB-l\ trace\fP +This operand shall make visible all functions referenced in \fI<trace.h>\fP. +An +implementation may search this library in the absence of this operand. +.TP 7 +\fB-l\ xnet\fP +This operand makes visible all functions referenced in \fI<arpa/inet.h>\fP, +\fI<netdb.h>\fP, \fI<netinet/in.h>\fP, and \fI<sys/socket.h>\fP. An +implementation may search this library in the absence of this +operand. +.TP 7 +\fB-l\ y\fP +This operand shall make visible all functions required by the C-language +output of \fIyacc\fP that are not made available through the \fB-l\ c\fP +operand. +.sp +.LP +In the absence of options that inhibit invocation of the link editor, +such as \fB-c\fP or \fB-E\fP, the \fIc99\fP utility +shall cause the equivalent of a \fB-l\ c\fP operand to be passed to +the link editor as the last \fB-l\fP operand, causing it +to be searched after all other object files and libraries are loaded. +.LP +It is unspecified whether the libraries \fBlibc.a\fP, \fBlibm.a\fP, +\fBlibrt.a\fP, \fBlibpthread.a\fP, \fBlibl.a\fP, +\fBliby.a\fP, or \fBlibxnet.a\fP exist as regular files. The implementation +may accept as \fB-l\fP operands names of objects +that do not exist as regular files. +.SS External Symbols +.LP +The C compiler and link editor shall support the significance of external +symbols up to a length of at least 31 bytes; the +action taken upon encountering symbols exceeding the implementation-defined +maximum symbol length is unspecified. +.LP +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4095 +external symbols in total. A diagnostic message shall be written to +the standard output if the implementation-defined limit is +exceeded; other actions are unspecified. +.SS Programming Environments +.LP +All implementations shall support one of the following programming +environments as a default. Implementations may support more +than one of the following programming environments. Applications can +use \fIsysconf\fP() +or \fIgetconf\fP to determine which programming environments are supported. +.br +.sp +.ce 1 +\fBTable: Programming Environments: Type Sizes\fP +.TS C +center; l2 l2 l2 l2 l. +\fBProgramming Environment\fP \fBBits in\fP \fBBits in\fP \fBBits in\fP \fBBits in\fP +\fB\fIgetconf\fP Name\fP \fBint\fP \fBlong\fP \fBpointer\fP \fBoff_t\fP +_POSIX_V6_ILP32_OFF32 32 32 32 32 +_POSIX_V6_ILP32_OFFBIG 32 32 32 >=64 +_POSIX_V6_LP64_OFF64 32 64 64 64 +_POSIX_V6_LPBIG_OFFBIG >=32 >=64 >=64 >=64 +.TE +.LP +All implementations shall support one or more environments where the +widths of the following types are no greater than the width +of type \fBlong\fP: +\fBblksize_t\fP, \fBcc_t\fP, \fBmode_t\fP, \fBnfds_t\fP, \fBpid_t\fP, +\fBptrdiff_t\fP, \fBsize_t\fP, +\fBspeed_t\fP, \fBssize_t\fP, \fBsuseconds_t\fP, \fBtcflag_t\fP, \fBuseconds_t\fP, +\fBwchar_t\fP, \fBwint_t\fP +.LP +The executable files created when these environments are selected +shall be in a proper format for execution by the \fIexec\fP +family of functions. Each environment may be one of the ones in Programming +Environments: Type Sizes , or +it may be another environment. The names for the environments that +meet this requirement shall be output by a \fIgetconf\fP command using +the _POSIX_V6_WIDTH_RESTRICTED_ENVS argument. If more than one +environment meets the requirement, the names of all such environments +shall be output on separate lines. Any of these names can +then be used in a subsequent \fIgetconf\fP command to obtain the flags +specific to that +environment with the following suffixes added as appropriate: +.TP 7 +_CFLAGS +To get the C compiler flags. +.TP 7 +_LDFLAGS +To get the linker/loader flags. +.TP 7 +_LIBS +To get the libraries. +.sp +.LP +This requirement may be removed in a future version of IEEE\ Std\ 1003.1. +.LP +When this utility processes a file containing a function called \fImain\fP(), +it shall be defined with a return type equivalent +to \fBint\fP. Using return from the initial call to \fImain\fP() shall +be equivalent (other than with respect to language scope +issues) to calling \fIexit\fP() with the returned value. Reaching +the end of the initial call +to \fImain\fP() shall be equivalent to calling \fIexit\fP(0). The +implementation shall not declare a prototype for this +function. +.LP +Implementations provide configuration strings for C compiler flags, +linker/loader flags, and libraries for each supported +environment. When an application needs to use a specific programming +environment rather than the implementation default programming +environment while compiling, the application shall first verify that +the implementation supports the desired environment. If the +desired programming environment is supported, the application shall +then invoke \fIc99\fP with the appropriate C compiler flags as +the first options for the compile, the appropriate linker/loader flags +after any other options but before any operands, and the +appropriate libraries at the end of the operands. +.LP +Conforming applications shall not attempt to link together object +files compiled for different programming models. Applications +shall also be aware that binary data placed in shared memory or in +files might not be recognized by applications built for other +programming models. +.br +.sp +.ce 1 +\fBTable: Programming Environments: \fIc99\fP and \fIcc\fP Arguments\fP +.TS C +center; l1 l1 l. +\fBProgramming Environment\fP \fB\ \fP \fB\fIc99\fP and \fIcc\fP Arguments\fP +\fB\fIgetconf\fP Name\fP \fBUse\fP \fB\fIgetconf\fP Name\fP +_POSIX_V6_ILP32_OFF32 C Compiler Flags POSIX_V6_ILP32_OFF32_CFLAGS +\ Linker/Loader Flags POSIX_V6_ILP32_OFF32_LDFLAGS +\ Libraries POSIX_V6_ILP32_OFF32_LIBS +_POSIX_V6_ILP32_OFFBIG C Compiler Flags POSIX_V6_ILP32_OFFBIG_CFLAGS +\ Linker/Loader Flags POSIX_V6_ILP32_OFFBIG_LDFLAGS +\ Libraries POSIX_V6_ILP32_OFFBIG_LIBS +_POSIX_V6_LP64_OFF64 C Compiler Flags POSIX_V6_LP64_OFF64_CFLAGS +\ Linker/Loader Flags POSIX_V6_LP64_OFF64_LDFLAGS +\ Libraries POSIX_V6_LP64_OFF64_LIBS +_POSIX_V6_LPBIG_OFFBIG C Compiler Flags POSIX_V6_LPBIG_OFFBIG_CFLAGS +\ Linker/Loader Flags POSIX_V6_LPBIG_OFFBIG_LDFLAGS +\ Libraries POSIX_V6_LPBIG_OFFBIG_LIBS +.TE +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful compilation or link edit. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When \fIc99\fP encounters a compilation error that causes an object +file not to be created, it shall write a diagnostic to +standard error and continue to compile other source code operands, +but it shall not perform the link phase and return a non-zero +exit status. If the link edit is unsuccessful, a diagnostic message +shall be written to standard error and \fIc99\fP exits with a +non-zero status. A conforming application shall rely on the exit status +of \fIc99\fP, rather than on the existence or mode of the +executable file. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since the \fIc99\fP utility usually creates files in the current directory +during the compilation process, it is typically +necessary to run the \fIc99\fP utility in a directory in which a file +can be created. +.LP +On systems providing POSIX Conformance (see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 2, Conformance), \fIc99\fP is required +only with the C-Language Development +option; XSI-conformant systems always provide \fIc99\fP. +.LP +Some historical implementations have created \fB.o\fP files when \fB-c\fP +is not specified and more than one source file is +given. Since this area is left unspecified, the application cannot +rely on \fB.o\fP files being created, but it also must be +prepared for any related \fB.o\fP files that already exist being deleted +at the completion of the link edit. +.LP +Some historical implementations have permitted \fB-L\fP options to +be interspersed with \fB-l\fP operands on the command line. +For an application to compile consistently on systems that do not +behave like this, it is necessary for a conforming application to +supply all \fB-L\fP options before any of the \fB-l\fP options. +.LP +There is the possible implication that if a user supplies versions +of the standard functions (before they would be encountered +by an implicit \fB-l\ c\fP or explicit \fB-l\ m\fP), that those versions +would be used in place of the standard versions. +There are various reasons this might not be true (functions defined +as macros, manipulations for clean name space, and so on), so +the existence of files named in the same manner as the standard libraries +within the \fB-L\fP directories is explicitly stated to +produce unspecified behavior. +.LP +All of the functions specified in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 may be made visible by +implementations when the Standard C Library is searched. Conforming +applications must explicitly request searching the other +standard libraries when functions made visible by those libraries +are used. +.SH EXAMPLES +.IP " 1." 4 +The following usage example compiles \fBfoo.c\fP and creates the executable +file \fBfoo\fP: +.sp +.RS +.nf + +\fBc99 -o foo foo.c +\fP +.fi +.RE +.LP +The following usage example compiles \fBfoo.c\fP and creates the object +file \fBfoo.o\fP: +.sp +.RS +.nf + +\fBc99 -c foo.c +\fP +.fi +.RE +.LP +The following usage example compiles \fBfoo.c\fP and creates the executable +file \fBa.out\fP: +.sp +.RS +.nf + +\fBc99 foo.c +\fP +.fi +.RE +.LP +The following usage example compiles \fBfoo.c\fP, links it with \fBbar.o\fP, +and creates the executable file \fBa.out\fP. It +may also create and leave \fBfoo.o\fP: +.sp +.RS +.nf + +\fBc99 foo.c bar.o +\fP +.fi +.RE +.LP +.IP " 2." 4 +The following example shows how an application using threads interfaces +can test for support of and use a programming +environment supporting 32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP +types and an \fBoff_t\fP type using at least 64 +bits: +.sp +.RS +.nf + +\fBif [ $(getconf _POSIX_V6_ILP32_OFFBIG) != "-1" ] +then + c99 $(getconf POSIX_V6_ILP32_OFFBIG_CFLAGS) -D_XOPEN_SOURCE=600 \\ + $(getconf POSIX_V6_ILP32_OFFBIG_LDFLAGS) foo.c -o foo \\ + $(getconf POSIX_V6_ILP32_OFFBIG_LIBS) -l pthread +else + echo ILP32_OFFBIG programming environment not supported + exit 1 +fi +\fP +.fi +.RE +.LP +.IP " 3." 4 +The following examples clarify the use and interactions of \fB-L\fP +options and \fB-l\fP operands. +.LP +Consider the case in which module \fBa.c\fP calls function \fIf\fP() +in library \fBlibQ.a\fP, and module \fBb.c\fP calls +function \fIg\fP() in library \fBlibp.a\fP. Assume that both libraries +reside in \fB/a/b/c\fP. The command line to compile and +link in the desired way is: +.sp +.RS +.nf + +\fBc99 -L /a/b/c main.o a.c -l Q b.c -l p +\fP +.fi +.RE +.LP +In this case the \fB-l\ Q\fP operand need only precede the first \fB-l\ p\fP +operand, since both \fBlibQ.a\fP and +\fBlibp.a\fP reside in the same directory. +.LP +Multiple \fB-L\fP operands can be used when library name collisions +occur. Building on the previous example, suppose that the +user wants to use a new \fBlibp.a\fP, in \fB/a/a/a\fP, but still wants +\fIf\fP() from \fB/a/b/c/libQ.a\fP: +.sp +.RS +.nf + +\fBc99 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p +\fP +.fi +.RE +.LP +In this example, the linker searches the \fB-L\fP options in the order +specified, and finds \fB/a/a/a/libp.a\fP before +\fB/a/b/c/libp.a\fP when resolving references for \fBb.c\fP. The order +of the \fB-l\fP operands is still important, however. +.LP +.IP " 4." 4 +The following example shows how an application can use a programming +environment where the widths of the following types: +\fBblksize_t\fP, \fBcc_t\fP, \fBmode_t\fP, \fBnfds_t\fP, \fBpid_t\fP, +\fBptrdiff_t\fP, \fBsize_t\fP, +\fBspeed_t\fP, \fBssize_t\fP, \fBsuseconds_t\fP, \fBtcflag_t\fP, \fBuseconds_t\fP, +\fBwchar_t\fP, \fBwint_t\fP +.LP +are no greater than the width of type \fBlong\fP: +.sp +.RS +.nf + +\fB# First choose one of the listed environments ... +.sp + +# ... if there are no additional constraints, the first one will do: +CENV=$(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS | head -n l) +.sp + +# ... or, if an environment that supports large files is preferred, +# look for names that contain "OFF64" or "OFFBIG". (This chooses +# the last one in the list if none match.) +for CENV in $(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS) +do + case $CENV in + *OFF64*|*OFFBIG*) break ;; + esac +done +.sp + +# The chosen environment name can now be used like this: +.sp + +c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200112L \\ +$(getconf ${CENV}_LDFLAGS) foo.c -o foo \\ +$(getconf ${CENV}_LIBS) +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIc99\fP utility is based on the \fIc89\fP utility originally +introduced in the ISO\ POSIX-2:1993 standard. +.LP +Some of the changes from \fIc89\fP include the modification to the +contents of the Standard Libraries section to account for +new headers and options; for example, \fI<spawn.h>\fP added to the +\fB-l\ rt\fP +operand, and the \fB-l\fP trace operand added for the Tracing functions. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIFile Read, Write, and Creation\fP , \fIar\fP , \fIgetconf\fP , +\fImake\fP , \fInm\fP , \fIstrip\fP , \fIumask\fP() , the System Interfaces +volume of +IEEE\ Std\ 1003.1-2001, \fIexec\fP, \fIsysconf\fP(), the Base Definitions +volume +of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |