mirror of https://github.com/mkerrisk/man-pages
746 lines
26 KiB
Groff
746 lines
26 KiB
Groff
.\" 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 .
|