diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/c99.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/c99.1p | 1168 |
1 files changed, 1168 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/c99.1p b/man-pages-posix-2017/man1p/c99.1p new file mode 100644 index 0000000..f45a664 --- /dev/null +++ b/man-pages-posix-2017/man1p/c99.1p @@ -0,0 +1,1168 @@ +'\" et +.TH C99 "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +c99 +\(em compile standard C programs +.SH SYNOPSIS +.LP +.nf +c99 \fB[\fIoptions\fR...\fB] \fIpathname \fB[[\fIpathname\fB] [\fR-I \fIdirectory\fB] + \fB[\fR-L \fIdirectory\fB] [\fR-l \fIlibrary\fB]]\fR... +.fi +.SH DESCRIPTION +The +.IR c99 +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 input files referenced by +.IR pathname +operands and +.BR \-l +option-arguments shall be compiled and linked to produce an executable +file. (It is unspecified whether the linking occurs entirely within the +operation of +.IR c99 ; +some implementations may produce objects that are not fully resolved +until the file is executed.) +.P +If the +.BR \-c +option is specified, for all pathname operands of the form +.IR file \c +.BR .c , +the files: +.sp +.RS 4 +.nf + +$(basename \fIpathname\fR .c).o +.fi +.P +.RE +.P +shall be created as the result of successful compilation. If the +.BR \-c +option is not specified, it is unspecified whether such +.BR .o +files are created or deleted for the +.IR file \c +.BR .c +operands. +.P +If there are no options that prevent link editing (such as +.BR \-c +or +.BR \-E ), +and all input files compile and link without error, the resulting +executable file shall be written according to the +.BR \-o +.IR outfile +option (if present) or to the file +.BR a.out . +.P +The executable file shall be created as specified in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +except that the file permission bits shall be set to: +S_IRWXO | S_IRWXG | S_IRWXU +.P +and the bits specified by the +.IR umask +of the process shall be cleared. +.SH OPTIONS +The +.IR c99 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: +.IP " *" 4 +Options can be interspersed with operands. +.IP " *" 4 +The order of specifying the +.BR \-L +and +.BR \-l +options, and the order of specifying +.BR \-l +options with respect to +.IR pathname +operands is significant. +.IP " *" 4 +Conforming applications shall specify each option separately; that is, +grouping option letters (for example, +.BR \-cO ) +need not be recognized by all implementations. +.P +The following options shall be supported: +.IP "\fB\-c\fP" 10 +Suppress the link-edit phase of the compilation, and do not remove any +object files that are produced. +.IP "\fB\-D\ \fIname\fB[=\fIvalue\fB]\fR" 10 +.br +Define +.IR name +as if by a C-language +.BR #define +directive. If no =\c +.IR value +is given, a value of 1 shall be used. The +.BR \-D +option has lower precedence than the +.BR \-U +option. That is, if +.IR name +is used in both a +.BR \-U +and a +.BR \-D +option, +.IR name +shall be undefined regardless of the order of the options. Additional +implementation-defined +.IR name s +may be provided by the compiler. Implementations shall support at least +2\|048 bytes of +.BR \-D +definitions and 256 +.IR names . +.IP "\fB\-E\fP" 10 +Copy C-language source files to standard output, executing all +preprocessor directives; no compilation shall be performed. If any +operand is not a text file, the effects are unspecified. +.IP "\fB\-g\fP" 10 +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. +.IP "\fB\-I\ \fIdirectory\fR" 10 +Change the algorithm for searching for headers whose names are not +absolute pathnames to look in the directory named by the +.IR directory +pathname before looking in the usual places. Thus, headers whose names +are enclosed in double-quotes (\c +.BR \(dq\^\(dq ) +shall be searched for first in the directory of the file with the +.BR #include +line, then in directories named in +.BR \-I +options, and last in the usual places. For headers whose names are +enclosed in angle brackets (\c +.BR \(dq<\|>\(dq ), +the header shall be searched for only in directories named in +.BR \-I +options and then in the usual places. Directories named in +.BR \-I +options shall be searched in the order specified. If the +.BR \-I +option is used to specify a directory that is one of the usual places +searched by default, the results are unspecified. Implementations shall +support at least ten instances of this option in a single +.IR c99 +command invocation. +.IP "\fB\-L\ \fIdirectory\fR" 10 +Change the algorithm of searching for the libraries named in the +.BR \-l +objects to look in the directory named by the +.IR directory +pathname before looking in the usual places. Directories named in +.BR \-L +options shall be searched in the order specified. If the +.BR \-L +option is used to specify a directory that is one of the usual places +searched by default, the results are unspecified. Implementations shall +support at least ten instances of this option in a single +.IR c99 +command invocation. If a directory specified by a +.BR \-L +option contains files with names starting with any of the strings +.BR \(dqlibc.\(dq , +.BR \(dqlibl.\(dq , +.BR \(dqlibpthread.\(dq , +.BR \(dqlibm.\(dq , +.BR \(dqlibrt.\(dq , +.BR \(dqlibtrace.\(dq , +.BR \(dqlibxnet.\(dq , +or +.BR \(dqliby.\(dq , +the results are unspecified. +.IP "\fB\-l\ \fIlibrary\fR" 10 +Search the library named +.BR liblibrary.a . +A library shall be searched when its name is encountered, so the +placement of a +.BR \-l +option 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 +.BR .a +as denoting libraries. +.IP "\fB\-O\ \fIoptlevel\fR" 10 +Specify the level of code optimization. If the +.IR optlevel +option-argument is the digit +.BR '0' , +all special code optimizations shall be disabled. If it is the digit +.BR '1' , +the nature of the optimization is unspecified. If the +.BR \-O +option is omitted, the nature of the system's default optimization is +unspecified. It is unspecified whether code generated in the presence +of the +.BR \-O +0 option is the same as that generated when +.BR \-O +is omitted. Other +.IR optlevel +values may be supported. +.IP "\fB\-o\ \fIoutfile\fR" 10 +Use the pathname +.IR outfile , +instead of the default +.BR a.out , +for the executable file produced. If the +.BR \-o +option is present with +.BR \-c +or +.BR \-E , +the result is unspecified. +.IP "\fB\-s\fP" 10 +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using the +.IR exec +family defined in the System Interfaces volume of POSIX.1\(hy2017 has been removed (stripped). If both +.BR \-g +and +.BR \-s +options are present, the action taken is unspecified. +.IP "\fB\-U\ \fIname\fR" 10 +Remove any initial definition of +.IR name . +.P +Multiple instances of the +.BR \-D , +.BR \-I , +.BR \-L , +.BR \-l , +and +.BR \-U +options can be specified. +.SH OPERANDS +The application shall ensure that at least one +.IR pathname +operand is specified. The following forms for +.IR pathname +operands shall be supported: +.IP "\fIfile.\fBc\fR" 10 +A C-language source file to be compiled and optionally linked. The +application shall ensure that the operand is of this form if the +.BR \-c +option is used. +.IP "\fIfile.\fBa\fR" 10 +A library of object files typically produced by the +.IR ar +utility, and passed directly to the link editor. Implementations may +recognize implementation-defined suffixes other than +.BR .a +as denoting object file libraries. +.IP "\fIfile.\fBo\fR" 10 +An object file produced by +.IR c99 +.BR \-c +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .o +as denoting object files. +.P +The processing of other files is implementation-defined. +.SH STDIN +Not used. +.SH "INPUT FILES" +Each 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 +.IR c99 +.BR \-c , +or a library of object files, in the format produced by archiving zero +or more object files, using +.IR ar . +Implementations may supply additional utilities that produce files in +these formats. Additional input file formats are +implementation-defined. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR c99 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +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. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If more than one +.IR pathname +operand ending in +.BR .c +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf + +"%s:\en", <\fIpathname\fR> +.fi +.P +.RE +.P +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. +.P +If the +.BR \-E +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 +The standard error shall be used only for diagnostic messages. +If more than one +.IR pathname +operand ending in +.BR .c +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf + +"%s:\en", <\fIpathname\fR> +.fi +.P +.RE +.P +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. +.P +This utility may produce warning messages about certain conditions that +do not warrant returning an error (non-zero) exit value. +.SH "OUTPUT FILES" +Object files or executable files or both are produced in unspecified +formats. If the pathname of an object file or executable file to be +created by +.IR c99 +resolves to an existing directory entry for a file that is not a regular +file, it is unspecified whether +.IR c99 +shall attempt to create the file or shall issue a diagnostic and exit +with a non-zero exit status. +.SH "EXTENDED DESCRIPTION" +.SS "Standard Libraries" +.P +The +.IR c99 +utility shall recognize the following +.BR \-l +options for standard libraries: +.IP "\fB\-l\ c\fR" 10 +This option shall make available all interfaces referenced in the System Interfaces volume of POSIX.1\(hy2017, +with the possible exception of those interfaces listed as residing in +.IR <aio.h> , +.IR <arpa/inet.h> , +.IR <complex.h> , +.IR <fenv.h> , +.IR <math.h> , +.IR <mqueue.h> , +.IR <netdb.h> , +.IR <net/if.h> , +.IR <netinet/in.h> , +.IR <pthread.h> , +.IR <sched.h> , +.IR <semaphore.h> , +.IR <spawn.h> , +.IR <sys/socket.h> , +\fIpthread_kill\fR(), +and +\fIpthread_sigmask\fR() +in +.IR <signal.h> , +.IR <trace.h> , +interfaces marked as optional in +.IR <sys/mman.h> , +interfaces marked as ADV (Advisory Information) in +.IR <fcntl.h> , +and interfaces beginning with the prefix clock_ or timer_ in +.IR <time.h> . +This option shall not be required to be present to cause a search of +this library. +.IP "\fB\-l\ l\fR" 10 +This option shall make available all interfaces required by the +C-language output of +.IR lex +that are not made available through the +.BR "\-l\ c" +option. +.IP "\fB\-l\ pthread\fR" 10 +This option shall make available all interfaces referenced in +.IR <pthread.h> +and +\fIpthread_kill\fR() +and +\fIpthread_sigmask\fR() +referenced in +.IR <signal.h> . +An implementation may search this library in the absence of this +option. +.IP "\fB\-l\ m\fR" 10 +This option shall make available all interfaces referenced in +.IR <math.h> , +.IR <complex.h> , +and +.IR <fenv.h> . +An implementation may search this library in the absence of this +option. +.IP "\fB\-l\ rt\fR" 10 +This option shall make available all interfaces referenced in +.IR <aio.h> , +.IR <mqueue.h> , +.IR <sched.h> , +.IR <semaphore.h> , +and +.IR <spawn.h> , +interfaces marked as optional in +.IR <sys/mman.h> , +interfaces marked as ADV (Advisory Information) in +.IR <fcntl.h> , +and interfaces beginning with the prefix clock_ and timer_ in +.IR <time.h> . +An implementation may search this library in the absence of this +option. +.IP "\fB\-l\ trace\fR" 10 +This option shall make available all interfaces referenced in +.IR <trace.h> . +An implementation may search this library in the absence of this +option. +.IP "\fB\-l\ xnet\fR" 10 +This option shall make available all interfaces referenced in +.IR <arpa/inet.h> , +.IR <netdb.h> , +.IR <net/if.h> , +.IR <netinet/in.h> , +and +.IR <sys/socket.h> . +An implementation may search this library in the absence of this +option. +.IP "\fB\-l\ y\fR" 10 +This option shall make available all interfaces required by the +C-language output of +.IR yacc +that are not made available through the +.BR "\-l\ c" +option. +.P +In the absence of options that inhibit invocation of the link editor, +such as +.BR \-c +or +.BR \-E , +the +.IR c99 +utility shall cause the equivalent of a +.BR "\-l\ c" +option to be passed to the link editor after the last +.IR pathname +operand or +.BR \-l +option, causing it to be searched after all other object files and +libraries are loaded. +.P +It is unspecified whether the libraries +.BR libc.a , +.BR libl.a , +.BR libm.a , +.BR libpthread.a , +.BR librt.a , +.BR libtrace.a , +.BR libxnet.a , +or +.BR liby.a +exist as regular files. The implementation may accept as +.BR \-l +option-arguments names of objects that do not exist as regular files. +.SS "External Symbols" +.P +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. +.P +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4\|095 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 "Header Search" +.P +If a file with the same name as one of the standard headers defined in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 13" ", " "Headers", +not provided as part of the implementation, is placed in any of the +usual places that are searched by default for headers, the results are +unspecified. +.SS "Programming Environments" +.P +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\fR() +or +.IR getconf +to determine which programming environments are supported. +.br +.sp +.ce 1 +\fBTable 4-4: Programming Environments: Type Sizes\fR +.TS +center box tab(!); +cB | cB | cB | cB | cB +cB | cB | cB | cB | cB +l | n | n | n | n. +Programming Environment!Bits in!Bits in!Bits in!Bits in +\fIgetconf\fP Name!int!long!pointer!off_t +_ +_POSIX_V7_ILP32_OFF32!32!32!32!32 +_POSIX_V7_ILP32_OFFBIG!32!32!32!\(>=64 +_POSIX_V7_LP64_OFF64!32!64!64!64 +_POSIX_V7_LPBIG_OFFBIG!\(>=32!\(>=64!\(>=64!\(>=64 +.TE +.P +All implementations shall support one or more environments where the +widths of the following types are no greater than the width of type +.BR long : +.TS +tab(!) center; +lB lB lB. +T{ +.nf +blksize_t +cc_t +mode_t +nfds_t +pid_t +T}!T{ +.nf +ptrdiff_t +size_t +speed_t +ssize_t +suseconds_t +T}!T{ +.nf +tcflag_t +wchar_t +wint_t +.fi +T} +.TE +.P +The executable files created when these environments are selected shall +be in a proper format for execution by the +.IR exec +family of functions. Each environment may be one of the ones in +.IR "Table 4-4, Programming Environments: Type Sizes", +or it may be another environment. The names for the environments that +meet this requirement shall be output by a +.IR getconf +command using the POSIX_V7_WIDTH_RESTRICTED_ENVS argument, as a +<newline>-separated +list of names suitable for use with the +.IR getconf +.BR \-v +option. 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 +.IR getconf +command to obtain the flags specific to that environment with the +following suffixes added as appropriate: +.IP _CFLAGS 10 +To get the C compiler flags. +.IP _LDFLAGS 10 +To get the linker/loader flags. +.IP _LIBS 10 +To get the libraries. +.P +This requirement may be removed in a future version. +.P +When this utility processes a file containing a function called +\fImain\fR(), +it shall be defined with a return type equivalent to +.BR int . +Using return from the initial call to +\fImain\fR() +shall be equivalent (other than with respect to language scope issues) +to calling +\fIexit\fR() +with the returned value. Reaching the end of the initial call to +\fImain\fR() +shall be equivalent to calling +.IR exit (0). +The implementation shall not declare a prototype for this function. +.P +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 +.IR c99 +with the appropriate C compiler flags as the first options for the +compile, the appropriate linker/loader flags after any other options +except +.BR \-l +but before any operands or +.BR \-l +options, and the appropriate libraries at the end of the operands +and +.BR \-l +options. +.P +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 4-5: Programming Environments: \fIc99\fP Arguments\fR +.TS +center box tab(!); +cB | cB | cB +cB | cB | cB +l | l | l. +Programming Environment!!\fIc99\fP Arguments +\fIgetconf\fP Name!Use!\fIgetconf\fP Name +_ +_POSIX_V7_ILP32_OFF32!C Compiler Flags!POSIX_V7_ILP32_OFF32_CFLAGS +!Linker/Loader Flags!POSIX_V7_ILP32_OFF32_LDFLAGS +!Libraries!POSIX_V7_ILP32_OFF32_LIBS +_ +_POSIX_V7_ILP32_OFFBIG!C Compiler Flags!POSIX_V7_ILP32_OFFBIG_CFLAGS +!Linker/Loader Flags!POSIX_V7_ILP32_OFFBIG_LDFLAGS +!Libraries!POSIX_V7_ILP32_OFFBIG_LIBS +_ +_POSIX_V7_LP64_OFF64!C Compiler Flags!POSIX_V7_LP64_OFF64_CFLAGS +!Linker/Loader Flags!POSIX_V7_LP64_OFF64_LDFLAGS +!Libraries!POSIX_V7_LP64_OFF64_LIBS +_ +_POSIX_V7_LPBIG_OFFBIG!C Compiler Flags!POSIX_V7_LPBIG_OFFBIG_CFLAGS +!Linker/Loader Flags!POSIX_V7_LPBIG_OFFBIG_LDFLAGS +!Libraries!POSIX_V7_LPBIG_OFFBIG_LIBS +.TE +.P +In addition to the type size programming environments above, all +implementations also support a multi-threaded programming environment +that is orthogonal to all of the programming environments listed above. +The +.IR getconf +utility can be used to get flags for the threaded programming environment, +as indicated in +.IR "Table 4-6, Threaded Programming Environment: \fIc99\fP Arguments". +.sp +.ce 1 +\fBTable 4-6: Threaded Programming Environment: \fIc99\fP Arguments\fR +.TS +center box tab(!); +cB | cB | cB +cB | cB | cB +l | l | l. +Programming Environment!!\fIc99\fP Arguments +\fIgetconf\fP Name!Use!\fIgetconf\fP Name +_ +_POSIX_THREADS!C Compiler Flags!POSIX_V7_THREADS_CFLAGS +!Linker/Loader Flags!POSIX_V7_THREADS_LDFLAGS +.TE +.P +These programming environment flags may be used in conjunction with any +of the type size programming environments supported by the implementation. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful compilation or link edit. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When +.IR c99 +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 it shall return a non-zero exit status. If the link edit is +unsuccessful, a diagnostic message shall be written to standard error +and +.IR c99 +exits with a non-zero status. A conforming application shall rely on the +exit status of +.IR c99 , +rather than on the existence or mode of the executable file. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since the +.IR c99 +utility usually creates files in the current directory during the +compilation process, it is typically necessary to run the +.IR c99 +utility in a directory in which a file can be created. +.P +On systems providing POSIX Conformance (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 2" ", " "Conformance"), +.IR c99 +is required only with the C-Language Development option; +XSI-conformant systems always provide +.IR c99 . +.P +Some historical implementations have created +.BR .o +files when +.BR \-c +is not specified and more than one source file is given. Since this +area is left unspecified, the application cannot rely on +.BR .o +files being created, but it also must be prepared for any related +.BR .o +files that already exist being deleted at the completion of the link +edit. +.P +There is the possible implication that if a user supplies versions of +the standard functions (before they would be encountered by an implicit +.BR "\-l\ c" +or explicit +.BR "\-l\ m" ), +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 +.BR \-L +directories is explicitly stated to produce unspecified behavior. +.P +All of the functions specified in the System Interfaces volume of POSIX.1\(hy2017 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. +.P +In the ISO\ C standard the mapping from physical source characters to the C +source character set is implementation-defined. Implementations may +strip white-space characters before the terminating +<newline> +of a (physical) line as part of this mapping and, as a consequence +of this, one or more white-space characters (and no other characters) +between a +<backslash> +character and the +<newline> +character that terminates the line produces implementation-defined +results. Portable applications should not use such constructs. +.P +Some +.IR c99 +compilers not conforming to POSIX.1\(hy2008 do not support trigraphs by default. +.SH EXAMPLES +.IP " 1." 4 +The following usage example compiles +.BR foo.c +and creates the executable file +.BR foo : +.RS 4 +.sp +.RS 4 +.nf + +c99 -o foo foo.c +.fi +.P +.RE +.P +The following usage example compiles +.BR foo.c +and creates the object file +.BR foo.o : +.sp +.RS 4 +.nf + +c99 -c foo.c +.fi +.P +.RE +.P +The following usage example compiles +.BR foo.c +and creates the executable file +.BR a.out : +.sp +.RS 4 +.nf + +c99 foo.c +.fi +.P +.RE +.P +The following usage example compiles +.BR foo.c , +links it with +.BR bar.o , +and creates the executable file +.BR a.out . +It may also create and leave +.BR foo.o : +.sp +.RS 4 +.nf + +c99 foo.c bar.o +.fi +.P +.RE +.RE +.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 +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits: +.RS 4 +.sp +.RS 4 +.nf + +offbig_env=$(getconf _POSIX_V7_ILP32_OFFBIG) +if [ $offbig_env != "-1" ] && [ $offbig_env != "undefined" ] +then + c99 $(getconf POSIX_V7_ILP32_OFFBIG_CFLAGS) \e + $(getconf POSIX_V7_THREADS_CFLAGS) -D_XOPEN_SOURCE=700 \e + $(getconf POSIX_V7_ILP32_OFFBIG_LDFLAGS) \e + $(getconf POSIX_V7_THREADS_LDFLAGS) foo.c -o foo \e + $(getconf POSIX_V7_ILP32_OFFBIG_LIBS) \e + -l pthread +else + echo ILP32_OFFBIG programming environment not supported + exit 1 +fi +.fi +.P +.RE +.RE +.IP " 3." 4 +The following examples clarify the use and interactions of +.BR \-L +and +.BR \-l +options. +.RS 4 +.P +Consider the case in which module +.BR a.c +calls function +\fIf\fR() +in library +.BR libQ.a , +and module +.BR b.c +calls function +\fIg\fR() +in library +.BR libp.a . +Assume that both libraries reside in +.BR /a/b/c . +The command line to compile and link in the desired way is: +.sp +.RS 4 +.nf + +c99 -L /a/b/c main.o a.c -l Q b.c -l p +.fi +.P +.RE +.P +In this case the +.BR \-L +option need only precede the first +.BR \-l +option, since both +.BR libQ.a +and +.BR libp.a +reside in the same directory. +.P +Multiple +.BR \-L +options can be used when library name collisions occur. Building on +the previous example, suppose that the user wants to use a new +.BR libp.a , +in +.BR /a/a/a , +but still wants +\fIf\fR() +from +.BR /a/b/c/libQ.a : +.sp +.RS 4 +.nf + +c99 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p +.fi +.P +.RE +.P +In this example, the linker searches the +.BR \-L +options in the order specified, and finds +.BR /a/a/a/libp.a +before +.BR /a/b/c/libp.a +when resolving references for +.BR b.c . +The order of the +.BR \-l +options is still important, however. +.RE +.IP " 4." 4 +The following example shows how an application can use a programming +environment where the widths of the following types: +.BR blksize_t , +.BR cc_t , +.BR mode_t , +.BR nfds_t , +.BR pid_t , +.BR ptrdiff_t , +.BR size_t , +.BR speed_t , +.BR ssize_t , +.BR suseconds_t , +.BR tcflag_t , +.BR wchar_t , +.BR wint_t +.RS 4 +.P +are no greater than the width of type +.BR long : +.sp +.RS 4 +.nf + +# First choose one of the listed environments ... +.P +# ... if there are no additional constraints, the first one will do: +CENV=$(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS | head -n l) +.P +# ... 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_V7_WIDTH_RESTRICTED_ENVS) +do + case $CENV in + *OFF64*|*OFFBIG*) break ;; + esac +done +.P +# The chosen environment name can now be used like this: +.P +c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200809L \e +$(getconf ${CENV}_LDFLAGS) foo.c -o foo \e +$(getconf ${CENV}_LIBS) +.fi +.P +.RE +.RE +.SH RATIONALE +The +.IR c99 +utility is based on the +.IR c89 +utility originally introduced in the ISO\ POSIX\(hy2:\|1993 standard. +.P +Some of the changes from +.IR c89 +include the ability to intersperse options and operands (which many +.IR c89 +implementations allowed despite it not being specified), +the description of +.BR \-l +as an option instead of an operand, and the modification to the contents +of the Standard Libraries section to account for new headers and options; +for example, +.IR <spawn.h> +added to the description of +.BR "\-l\ rt" , +and +.BR "\-l\ trace" +added for the Tracing option. +.P +POSIX.1\(hy2008 specifies that the +.IR c99 +utility must be able to use regular files for +.BR *.o +files and for +.BR a.out +files. Implementations are free to overwrite existing files of other +types when attempting to create object files and executable files, but +are not required to do so. If something other than a regular file is +specified and using it fails for any reason, +.IR c99 +is required to issue a diagnostic message and exit with a non-zero exit +status. But for some file types, the problem may not be noticed for a +long time. For example, if a FIFO named +.BR a.out +exists in the current directory, +.IR c99 +may attempt to open +.BR a.out +and will hang in the +\fIopen\fR() +call until another process opens the FIFO for reading. Then +.IR c99 +may write most of the +.BR a.out +to the FIFO and fail when it tries to seek back close to the start of +the file to insert a timestamp (FIFOs are not seekable files). The +.IR c99 +utility is also allowed to issue a diagnostic immediately if it +encounters an +.BR a.out +or +.BR *.o +file that is not a regular file. For portable use, applications should +ensure that any +.BR a.out , +.BR \-o +option-argument, or +.BR *.o +files corresponding to any +.BR *.c +files do not conflict with names already in use that are not regular +files or symbolic links that point to regular files. +.P +On many systems, multi-threaded applications run in a programming +environment that is distinct from that used by single-threaded +applications. This multi-threaded programming environment (in addition +to needing to specify +.BR "\-l pthread" +at link time) may require additional flags to be set when headers are +processed at compile time (\c +.BR \-D_REENTRANT +being common). This programming environment is orthogonal to the type +size programming environments discussed above and listed in +.IR "Table 4-4, Programming Environments: Type Sizes". +This version of the standard adds +.IR getconf +utility calls to provide the C compiler flags and linker/loader flags +needed to support multi-threaded applications. Note that on a system +where single-threaded applications are a special case of a multi-threaded +application, both of these +.IR getconf +calls may return NULL strings; on other implementations both of +these strings may be non-NULL strings. +.P +The C standardization committee invented trigraphs (e.g., +.BR \(dq??!\(dq +to represent +.BR '|' ) +to address character portability problems in development environments +based on national variants of the 7-bit ISO/IEC\ 646:\|1991 standard character set. However, +these environments were already obsolete by the time the first ISO\ C standard was +published, and in practice trigraphs have not been used for their intended +purpose, and usually are intended to have their original meaning in K&R C. +For example, in practice a C-language source string like +.BR \(dqWhat??!\(dq +is usually intended to end in two +<question-mark> +characters and an +<exclamation-mark>, +not in +.BR '|' . +.P +When the +.BR \-E +option is used, execution of some +.BR #pragma +preprocessor directives may simply result in a copy of the directive being +included in the output as part of the allowed extra information used by +subsequent compilation passes (see STDOUT). +.SH "FUTURE DIRECTIONS" +Unlike all of the other non-OB-shaded utilities in this standard, a utility +by this name probably will not appear in the next version of this standard. +This utility's name is tied to the current revision of the ISO\ C standard at the +time this standard is approved. Since the ISO\ C standard and this standard are +maintained by different organizations on different schedules, we cannot +predict what the compiler will be named in the next version +of the standard. +.SH "SEE ALSO" +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +.IR "\fIar\fR\^", +.IR "\fIgetconf\fR\^", +.IR "\fImake\fR\^", +.IR "\fInm\fR\^", +.IR "\fIstrip\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "Chapter 13" ", " "Headers" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIexec\fR\^", +.IR "\fIsysconf\fR\^(\|)" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |