C99(inc) - phpMan

C99(1P)                    POSIX Programmer's Manual                   C99(1P)

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.
NAME
       c99 - compile standard C programs
SYNOPSIS
       c99 [-c][-D name[=value]]...[-E][-g][-I directory] ... [-L directory]
              ... [-o outfile][-Ooptlevel][-s][-U name]...  operand ...
DESCRIPTION
       The c99 utility is an interface to the standard C  compilation  system;
       it  shall accept source code conforming to the ISO C standard. The sys-
       tem conceptually consists of a compiler and link editor. The files ref-
       erenced  by  operands  shall  be compiled and linked to produce an exe-
       cutable file. (It is unspecified whether the  linking  occurs  entirely
       within  the  operation of c99; some implementations may produce objects
       that are not fully resolved until the file is executed.)
       If the -c option is specified, for all pathname operands  of  the  form
       file .c, the files:

              $(basename pathname .c).o
       shall  be  created  as  the result of successful compilation. If the -c
       option is not specified, it is unspecified whether such  .o  files  are
       created or deleted for the file .c operands.
       If  there  are no options that prevent link editing (such as -c or -E),
       and all operands compile and link without  error,  the  resulting  exe-
       cutable  file  shall  be written according to the -o outfile option (if
       present) or to the file a.out.
       The executable file shall be created as specified in File Read,  Write,
       and Creation, except that the file permission bits shall be set to:

              S_IRWXO | S_IRWXG | S_IRWXU
       and the bits specified by the umask of the process shall be cleared.
OPTIONS
       The  c99  utility  shall  conform  to  the  Base  Definitions volume of
       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax  Guidelines,  except
       that:
        * The  -l library operands have the format of options, but their posi-
          tion within a list of operands affects the order in which  libraries
          are searched.
        * The order of specifying the -I and -L options is significant.
        * Conforming  applications  shall specify each option separately; that
          is, grouping option letters (for example, -cO) need  not  be  recog-
          nized by all implementations.
       The following options shall be supported:
       -c     Suppress  the  link-edit  phase  of  the compilation, and do not
              remove any object files that are produced.
       -g     Produce symbolic information in the object or executable  files;
              the  nature of this information is unspecified, and may be modi-
              fied by implementation-defined interactions with other options.
       -s     Produce object or executable files, or both, from which symbolic
              and  other  information  not required for proper execution using
              the exec family defined  in  the  System  Interfaces  volume  of
              IEEE Std 1003.1-2001 has been removed (stripped). If both -g and
              -s options are present, the action taken is unspecified.
       -o  outfile
              Use the pathname outfile, instead of the default a.out, for  the
              executable file produced. If the -o option is present with -c or
              -E, the result is unspecified.
       -D  name[=value]
              Define name as if by a C-language #define  directive.  If  no  =
              value  is  given,  a value of 1 shall be used. The -D option has
              lower precedence than the -U option. That is, if name is used in
              both a -U and a -D option, name shall be undefined regardless of
              the order  of  the  options.  Additional  implementation-defined
              names  may  be  provided  by the compiler. Implementations shall
              support at least 2048 bytes of -D definitions and 256 names.
       -E     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.
       -I  directory
              Change the algorithm for searching for headers whose  names  are
              not  absolute  pathnames  to  look in the directory named by the
              directory pathname before looking in  the  usual  places.  Thus,
              headers  whose  names are enclosed in double-quotes ( "" ) shall
              be searched for first in the directory  of  the  file  with  the
              #include line, then in directories named in -I options, and last
              in the usual places. For headers whose  names  are  enclosed  in
              angle  brackets  ( "<>" ), the header shall be searched for only
              in directories named in -I options and then in the usual places.
              Directories  named  in -I options shall be searched in the order
              specified. Implementations shall support at least ten  instances
              of this option in a single c99 command invocation.
       -L  directory
              Change the algorithm of searching for the libraries named in the
              -l objects to look in the directory named by the directory path-
              name before looking in the usual places. Directories named in -L
              options shall be searched in the  order  specified.  Implementa-
              tions  shall  support at least ten instances of this option in a
              single c99 command invocation. If a directory specified by a  -L
              option  contains  files named libc.a, libm.a, libl.a, or liby.a,
              the results are unspecified.
       -O  optlevel
              Specify the level of code optimization. If the optlevel  option-
              argument  is the digit '0', all special code optimizations shall
              be disabled. If it is the digit '1', the nature of the optimiza-
              tion  is unspecified. If the -O option is omitted, the nature of
              the system's default optimization is unspecified. It is unspeci-
              fied  whether  code generated in the presence of the -O 0 option
              is the same as that generated when -O is omitted. Other optlevel
              values may be supported.
       -U  name
              Remove any initial definition of name.

       Multiple instances of the -D, -I, -U, and -L options can be specified.
OPERANDS
       An  operand is either in the form of a pathname or the form -l library.
       The application shall ensure that at least one operand of the  pathname
       form is specified. The following operands shall be supported:
       file.c A  C-language  source file to be compiled and optionally linked.
              The application shall ensure that the operand is of this form if
              the -c option is used.
       file.a A  library of object files typically produced by the ar utility,
              and passed directly to the link editor. Implementations may rec-
              ognize implementation-defined suffixes other than .a as denoting
              object file libraries.
       file.o An object file produced by c99 -c and  passed  directly  to  the
              link   editor.  Implementations  may  recognize  implementation-
              defined suffixes other than .o as denoting object files.

       The processing of other files is implementation-defined.
       -l library
              (The letter ell.) Search the library named:

              liblibrary.a
       A library shall be searched when its name is encountered, so the place-
       ment  of a -l operand is significant. Several standard libraries can be
       specified in this manner, as described in the EXTENDED DESCRIPTION sec-
       tion.  Implementations  may  recognize  implementation-defined suffixes
       other than .a as denoting libraries.

STDIN
       Not used.
INPUT FILES
       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 c99
       -c, or a library of object files, in the format produced  by  archiving
       zero  or  more object files, using ar. Implementations may supply addi-
       tional utilities that produce files in these formats. Additional  input
       file formats are implementation-defined.
ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of c99:
       LANG   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 Vari-
              ables for the precedence of internationalization variables  used
              to determine the values of locale categories.)
       LC_ALL If  set  to a non-empty string value, override the values of all
              the other internationalization variables.
       LC_CTYPE
              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).
       LC_MESSAGES
              Determine the locale that should be used to  affect  the  format
              and contents of diagnostic messages written to standard error.
       NLSPATH
              Determine the location of message catalogs for the processing of
              LC_MESSAGES .
       TMPDIR 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  tempo-
              rary files, if any.

ASYNCHRONOUS EVENTS
       Default.
STDOUT
       If  more than one file operand ending in .c (or possibly other unspeci-
       fied suffixes) is given, for each such file:

              "%s:\n", <file>
       may be written. These messages, if written, shall precede the  process-
       ing  of each input file; they shall not be written to the standard out-
       put if they are written to the standard  error,  as  described  in  the
       STDERR section.
       If the -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.
STDERR
       The standard error shall be used only for diagnostic messages. If  more
       than  one file operand ending in .c (or possibly other unspecified suf-
       fixes) is given, for each such file:

              "%s:\n", <file>
       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 out-
       put, as described in the STDOUT section.
       This utility may produce warning messages about certain conditions that
       do not warrant returning an error (non-zero) exit value.
OUTPUT FILES
       Object  files  or  executable files or both are produced in unspecified
       formats.
EXTENDED DESCRIPTION
   Standard Libraries
       The c99 utility shall recognize the following -l operands for  standard
       libraries:
       -l c   This  operand shall make visible all functions referenced in the
              System Interfaces volume of IEEE Std 1003.1-2001, with the  pos-
              sible  exception  of  those  functions  listed  as  residing  in
              <aio.h>,   <arpa/inet.h>,   <complex.h>,   <fenv.h>,   <math.h>,
              <mqueue.h>,  <netdb.h>,  <netinet/in.h>, <pthread.h>, <sched.h>,
              <semaphore.h>, <spawn.h>,  <sys/socket.h>,  pthread_kill(),  and
              pthread_sigmask()  in <signal.h>, <trace.h>, functions marked as
              extensions other than as part of the MF  or  MPR  extensions  in
              <sys/mman.h>,  functions  marked  as ADV in <fcntl.h>, and func-
              tions marked as CS, CPT, and TMR in <time.h>. This operand shall
              not be required to be present to cause a search of this library.
       -l l   This operand shall make visible all functions required by the C-
              language output of lex that are not made available  through  the
              -l c operand.
       -l pthread
              This  operand  shall  make  visible  all functions referenced in
              <pthread.h> and pthread_kill() and pthread_sigmask()  referenced
              in  <signal.h>. An implementation may search this library in the
              absence of this operand.
       -l m   This operand shall make  visible  all  functions  referenced  in
              <math.h>,  <complex.h>,  and  <fenv.h>.  An  implementation  may
              search this library in the absence of this operand.
       -l rt  This operand shall make  visible  all  functions  referenced  in
              <aio.h>,  <mqueue.h>,  <sched.h>,  <semaphore.h>, and <spawn.h>,
              functions marked as extensions other than as part of the  MF  or
              MPR  extensions  in  <sys/mman.h>,  functions  marked  as ADV in
              <fcntl.h>, and functions marked as CS, CPT, and TMR in <time.h>.
              An implementation may search this library in the absence of this
              operand.
       -l trace
              This operand shall make  visible  all  functions  referenced  in
              <trace.h>.   An  implementation  may  search this library in the
              absence of this operand.
       -l xnet
              This  operand  makes  visible  all   functions   referenced   in
              <arpa/inet.h>, <netdb.h>, <netinet/in.h>, and <sys/socket.h>. An
              implementation may search this library in the  absence  of  this
              operand.
       -l y   This operand shall make visible all functions required by the C-
              language output of yacc that are not made available through  the
              -l c operand.

       In  the  absence of options that inhibit invocation of the link editor,
       such as -c or -E, the c99 utility shall cause the equivalent of a  -l c
       operand to be passed to the link editor as the last -l operand, causing
       it to be searched after  all  other  object  files  and  libraries  are
       loaded.
       It  is  unspecified  whether  the  libraries  libc.a,  libm.a, librt.a,
       libpthread.a, libl.a, liby.a, or libxnet.a exist as regular files.  The
       implementation  may  accept as -l operands names of objects that do not
       exist as regular files.
   External Symbols
       The C compiler and link editor shall support the significance of exter-
       nal  symbols up to a length of at least 31 bytes; the action taken upon
       encountering symbols exceeding the implementation-defined maximum  sym-
       bol length is unspecified.
       The  compiler  and  link editor shall support a minimum of 511 external
       symbols per source or object file, and a minimum of 4095 external  sym-
       bols  in  total.  A diagnostic message shall be written to the standard
       output if the implementation-defined limit is exceeded;  other  actions
       are unspecified.
   Programming Environments
       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 sysconf()
       or getconf to determine which programming environments are supported.
                     Table: Programming Environments: Type Sizes
             Programming Environment  Bits in  Bits in  Bits in  Bits in
             getconf Name             int      long     pointer  off_t
             _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
       All implementations shall support one or more  environments  where  the
       widths  of  the  following  types are no greater than the width of type
       long:  blksize_t,  cc_t,  mode_t,  nfds_t,  pid_t,  ptrdiff_t,  size_t,
       speed_t, ssize_t, suseconds_t, tcflag_t, useconds_t, wchar_t, wint_t
       The executable files created when these environments are selected shall
       be in a proper format for execution by the exec  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  envi-
       ronments  that  meet this requirement shall be output by a getconf com-
       mand using the _POSIX_V6_WIDTH_RESTRICTED_ENVS argument. If  more  than
       one  environment  meets the requirement, the names of all such environ-
       ments shall be output on separate lines. Any of these names can then be
       used  in  a  subsequent getconf command to obtain the flags specific to
       that environment with the following suffixes added as appropriate:
       _CFLAGS
              To get the C compiler flags.
       _LDFLAGS
              To get the linker/loader flags.
       _LIBS  To get the libraries.

       This requirement may be removed in a future version of IEEE Std 1003.1.
       When this utility processes a file containing a function called main(),
       it  shall be defined with a return type equivalent to int. Using return
       from the initial call to main() shall be equivalent  (other  than  with
       respect  to  language scope issues) to calling exit() with the returned
       value. Reaching the end of the initial call to main() shall be  equiva-
       lent  to calling exit(0). The implementation shall not declare a proto-
       type for this function.
       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 compil-
       ing, the application shall first verify that  the  implementation  sup-
       ports  the  desired environment. If the desired programming environment
       is supported, the application shall then invoke c99 with the  appropri-
       ate  C  compiler flags as the first options for the compile, the appro-
       priate linker/loader flags after any other options but before any oper-
       ands, and the appropriate libraries at the end of the operands.
       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.
                Table: Programming Environments: c99 and cc Arguments
      Programming Environment                     c99 and cc Arguments
      getconf Name            Use                 getconf Name
      _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
EXIT STATUS
       The following exit values shall be returned:
        0     Successful compilation or link edit.
       >0     An error occurred.

CONSEQUENCES OF ERRORS
       When c99 encounters a compilation error that causes an object file  not
       to  be  created, it shall write a diagnostic to standard error and con-
       tinue 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  c99  exits  with a non-zero status. A conforming application shall
       rely on the exit status of c99, rather than on the existence or mode of
       the executable file.
       The following sections are informative.
APPLICATION USAGE
       Since  the  c99  utility usually creates files in the current directory
       during the compilation process, it is typically necessary  to  run  the
       c99 utility in a directory in which a file can be created.
       On systems providing POSIX Conformance (see the Base Definitions volume
       of IEEE Std 1003.1-2001, Chapter 2, Conformance), c99 is required  only
       with  the  C-Language Development option; XSI-conformant systems always
       provide c99.
       Some historical implementations have created .o files when  -c  is  not
       specified  and  more  than one source file is given. Since this area is
       left unspecified, the application cannot rely on .o  files  being  cre-
       ated,  but  it  also  must  be  prepared  for any related .o files that
       already exist being deleted at the completion of the link edit.
       Some historical implementations have permitted -L options to be  inter-
       spersed  with  -l  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 -L options before
       any of the -l options.
       There is the possible implication that if a user supplies  versions  of
       the standard functions (before they would be encountered by an implicit
       -l c or explicit -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 -L directories is  explicitly  stated  to
       produce unspecified behavior.
       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 vis-
       ible by those libraries are used.
EXAMPLES
        1. The  following  usage  example  compiles foo.c and creates the exe-
           cutable file foo:

           c99 -o foo foo.c
       The following usage example compiles foo.c and creates the object  file
       foo.o:

              c99 -c foo.c
       The  following  usage example compiles foo.c and creates the executable
       file a.out:

              c99 foo.c
       The following usage example compiles foo.c, links it  with  bar.o,  and
       creates the executable file a.out. It may also create and leave foo.o:

              c99 foo.c bar.o
        2. The following example shows how an application using threads inter-
           faces can test for support of and  use  a  programming  environment
           supporting  32-bit  int,  long, and pointer types and an off_t type
           using at least 64 bits:

           if [ $(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
        3. The following examples clarify  the  use  and  interactions  of  -L
           options and -l operands.
       Consider  the  case  in  which module a.c calls function f() in library
       libQ.a, and module b.c calls function g()  in  library  libp.a.  Assume
       that  both  libraries reside in /a/b/c. The command line to compile and
       link in the desired way is:

              c99 -L /a/b/c main.o a.c -l Q b.c -l p
       In this case the -l Q operand need only precede the first -l p operand,
       since both libQ.a and libp.a reside in the same directory.
       Multiple  -L  operands  can be used when library name collisions occur.
       Building on the previous example, suppose that the user wants to use  a
       new libp.a, in /a/a/a, but still wants f() from /a/b/c/libQ.a:

              c99 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p
       In this example, the linker searches the -L options in the order speci-
       fied, and finds /a/a/a/libp.a before /a/b/c/libp.a when resolving  ref-
       erences  for b.c. The order of the -l operands is still important, how-
       ever.
        4. The following example shows how an application can use  a  program-
           ming  environment  where  the  widths  of the following types: blk-
           size_t, cc_t, mode_t, nfds_t, pid_t,  ptrdiff_t,  size_t,  speed_t,
           ssize_t, suseconds_t, tcflag_t, useconds_t, wchar_t, wint_t
       are no greater than the width of type long:

              # First choose one of the listed environments ...

              # ... if there are no additional constraints, the first one will do:
              CENV=$(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS | head -n l)

              # ... 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

              # The chosen environment name can now be used like this:

              c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200112L \
              $(getconf ${CENV}_LDFLAGS) foo.c -o foo \
              $(getconf ${CENV}_LIBS)
RATIONALE
       The  c99  utility  is based on the c89 utility originally introduced in
       the ISO POSIX-2:1993 standard.
       Some of the changes from c89 include the modification to  the  contents
       of  the  Standard  Libraries  section  to  account  for new headers and
       options; for example, <spawn.h> added to the -l rt operand, and the  -l
       trace operand added for the Tracing functions.
FUTURE DIRECTIONS
       None.
SEE ALSO
       File  Read, Write, and Creation, ar, getconf, make, nm, strip, umask(),
       the System Interfaces volume of IEEE Std 1003.1-2001, exec,  sysconf(),
       the  Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Head-
       ers
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 .

IEEE/The Open Group                  2003                              C99(1P)