c99 man page on OpenSuSE

Man page or keyword search:  
man Server   25941 pages
apropos Keyword Search (all sections)
Output format
OpenSuSE logo
[printable version]

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)
[top]

List of man pages available for OpenSuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net