1C99(1P) POSIX Programmer's Manual C99(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 c99 - compile standard C programs
13
15 c99 [-c][-D name[=value]]...[-E][-g][-I directory] ... [-L directory]
16 ... [-o outfile][-Ooptlevel][-s][-U name]... operand ...
17
19 The c99 utility is an interface to the standard C compilation system;
20 it shall accept source code conforming to the ISO C standard. The sys‐
21 tem conceptually consists of a compiler and link editor. The files ref‐
22 erenced by operands shall be compiled and linked to produce an exe‐
23 cutable file. (It is unspecified whether the linking occurs entirely
24 within the operation of c99; some implementations may produce objects
25 that are not fully resolved until the file is executed.)
26 If the -c option is specified, for all pathname operands of the form
28 file .c, the files:
29 $(basename pathname .c).o
32 shall be created as the result of successful compilation. If the -c
34 option is not specified, it is unspecified whether such .o files are
35 created or deleted for the file .c operands.
36 If there are no options that prevent link editing (such as -c or -E),
38 and all operands compile and link without error, the resulting exe‐
39 cutable file shall be written according to the -o outfile option (if
40 present) or to the file a.out.
41 The executable file shall be created as specified in File Read, Write,
43 and Creation, except that the file permission bits shall be set to:
44 S_IRWXO | S_IRWXG | S_IRWXU
47 and the bits specified by the umask of the process shall be cleared.
49
51 The c99 utility shall conform to the Base Definitions volume of
52 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, except
53 that:
54 * The -l library operands have the format of options, but their posi‐
56 tion within a list of operands affects the order in which libraries
57 are searched.
58 * The order of specifying the -I and -L options is significant.
60 * Conforming applications shall specify each option separately; that
62 is, grouping option letters (for example, -cO) need not be recog‐
63 nized by all implementations.
64 The following options shall be supported:
66 -c Suppress the link-edit phase of the compilation, and do not
68 remove any object files that are produced.
69 -g Produce symbolic information in the object or executable files;
71 the nature of this information is unspecified, and may be modi‐
72 fied by implementation-defined interactions with other options.
73 -s Produce object or executable files, or both, from which symbolic
75 and other information not required for proper execution using
76 the exec family defined in the System Interfaces volume of
77 IEEE Std 1003.1-2001 has been removed (stripped). If both -g and
78 -s options are present, the action taken is unspecified.
79 -o outfile
81 Use the pathname outfile, instead of the default a.out, for the
82 executable file produced. If the -o option is present with -c or
83 -E, the result is unspecified.
84 -D name[=value]
86 Define name as if by a C-language #define directive. If no =
88 value is given, a value of 1 shall be used. The -D option has
89 lower precedence than the -U option. That is, if name is used in
90 both a -U and a -D option, name shall be undefined regardless of
91 the order of the options. Additional implementation-defined
92 names may be provided by the compiler. Implementations shall
93 support at least 2048 bytes of -D definitions and 256 names.
94 -E Copy C-language source files to standard output, expanding all
96 preprocessor directives; no compilation shall be performed. If
97 any operand is not a text file, the effects are unspecified.
98 -I directory
100 Change the algorithm for searching for headers whose names are
101 not absolute pathnames to look in the directory named by the
102 directory pathname before looking in the usual places. Thus,
103 headers whose names are enclosed in double-quotes ( "" ) shall
104 be searched for first in the directory of the file with the
105 #include line, then in directories named in -I options, and last
106 in the usual places. For headers whose names are enclosed in
107 angle brackets ( "<>" ), the header shall be searched for only
108 in directories named in -I options and then in the usual places.
109 Directories named in -I options shall be searched in the order
110 specified. Implementations shall support at least ten instances
111 of this option in a single c99 command invocation.
112 -L directory
114 Change the algorithm of searching for the libraries named in the
115 -l objects to look in the directory named by the directory path‐
116 name before looking in the usual places. Directories named in -L
117 options shall be searched in the order specified. Implementa‐
118 tions shall support at least ten instances of this option in a
119 single c99 command invocation. If a directory specified by a -L
120 option contains files named libc.a, libm.a, libl.a, or liby.a,
121 the results are unspecified.
122 -O optlevel
124 Specify the level of code optimization. If the optlevel option-
125 argument is the digit '0', all special code optimizations shall
126 be disabled. If it is the digit '1', the nature of the optimiza‐
127 tion is unspecified. If the -O option is omitted, the nature of
128 the system's default optimization is unspecified. It is unspeci‐
129 fied whether code generated in the presence of the -O 0 option
130 is the same as that generated when -O is omitted. Other optlevel
131 values may be supported.
132 -U name
134 Remove any initial definition of name.
135 Multiple instances of the -D, -I, -U, and -L options can be specified.
138
140 An operand is either in the form of a pathname or the form -l library.
141 The application shall ensure that at least one operand of the pathname
142 form is specified. The following operands shall be supported:
143 file.c A C-language source file to be compiled and optionally linked.
145 The application shall ensure that the operand is of this form if
146 the -c option is used.
147 file.a A library of object files typically produced by the ar utility,
149 and passed directly to the link editor. Implementations may rec‐
150 ognize implementation-defined suffixes other than .a as denoting
151 object file libraries.
152 file.o An object file produced by c99 -c and passed directly to the
154 link editor. Implementations may recognize implementation-
155 defined suffixes other than .o as denoting object files.
156 The processing of other files is implementation-defined.
159 -l library
161 (The letter ell.) Search the library named:
162 liblibrary.a
165 A library shall be searched when its name is encountered, so the place‐
167 ment of a -l operand is significant. Several standard libraries can be
168 specified in this manner, as described in the EXTENDED DESCRIPTION sec‐
169 tion. Implementations may recognize implementation-defined suffixes
170 other than .a as denoting libraries.
171
174 Not used.
175
177 The input file shall be one of the following: a text file containing a
178 C-language source program, an object file in the format produced by c99
179 -c, or a library of object files, in the format produced by archiving
180 zero or more object files, using ar. Implementations may supply addi‐
181 tional utilities that produce files in these formats. Additional input
182 file formats are implementation-defined.
183
185 The following environment variables shall affect the execution of c99:
186 LANG Provide a default value for the internationalization variables
188 that are unset or null. (See the Base Definitions volume of
189 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
190 ables for the precedence of internationalization variables used
191 to determine the values of locale categories.)
192 LC_ALL If set to a non-empty string value, override the values of all
194 the other internationalization variables.
195 LC_CTYPE
197 Determine the locale for the interpretation of sequences of
198 bytes of text data as characters (for example, single-byte as
199 opposed to multi-byte characters in arguments and input files).
200 LC_MESSAGES
202 Determine the locale that should be used to affect the format
203 and contents of diagnostic messages written to standard error.
204 NLSPATH
206 Determine the location of message catalogs for the processing of
207 LC_MESSAGES .
208 TMPDIR Provide a pathname that should override the default directory
210 for temporary files, if any. On XSI-conforming systems, provide
211 a pathname that shall override the default directory for tempo‐
212 rary files, if any.
213
216 Default.
217
219 If more than one file operand ending in .c (or possibly other unspeci‐
220 fied suffixes) is given, for each such file:
221 "%s:\n", <file>
224 may be written. These messages, if written, shall precede the process‐
226 ing of each input file; they shall not be written to the standard out‐
227 put if they are written to the standard error, as described in the
228 STDERR section.
229 If the -E option is specified, the standard output shall be a text file
231 that represents the results of the preprocessing stage of the language;
232 it may contain extra information appropriate for subsequent compilation
233 passes.
234
236 The standard error shall be used only for diagnostic messages. If more
237 than one file operand ending in .c (or possibly other unspecified suf‐
238 fixes) is given, for each such file:
239 "%s:\n", <file>
242 may be written to allow identification of the diagnostic and warning
244 messages with the appropriate input file. These messages, if written,
245 shall precede the processing of each input file; they shall not be
246 written to the standard error if they are written to the standard out‐
247 put, as described in the STDOUT section.
248 This utility may produce warning messages about certain conditions that
250 do not warrant returning an error (non-zero) exit value.
251
253 Object files or executable files or both are produced in unspecified
254 formats.
255
257 Standard Libraries
258 The c99 utility shall recognize the following -l operands for standard
259 libraries:
260 -l c This operand shall make visible all functions referenced in the
262 System Interfaces volume of IEEE Std 1003.1-2001, with the pos‐
263 sible exception of those functions listed as residing in
264 <aio.h>, <arpa/inet.h>, <complex.h>, <fenv.h>, <math.h>,
265 <mqueue.h>, <netdb.h>, <netinet/in.h>, <pthread.h>, <sched.h>,
266 <semaphore.h>, <spawn.h>, <sys/socket.h>, pthread_kill(), and
267 pthread_sigmask() in <signal.h>, <trace.h>, functions marked as
268 extensions other than as part of the MF or MPR extensions in
269 <sys/mman.h>, functions marked as ADV in <fcntl.h>, and func‐
270 tions marked as CS, CPT, and TMR in <time.h>. This operand shall
271 not be required to be present to cause a search of this library.
272 -l l This operand shall make visible all functions required by the C-
274 language output of lex that are not made available through the
275 -l c operand.
276 -l pthread
278 This operand shall make visible all functions referenced in
279 <pthread.h> and pthread_kill() and pthread_sigmask() referenced
280 in <signal.h>. An implementation may search this library in the
281 absence of this operand.
282 -l m This operand shall make visible all functions referenced in
284 <math.h>, <complex.h>, and <fenv.h>. An implementation may
285 search this library in the absence of this operand.
286 -l rt This operand shall make visible all functions referenced in
288 <aio.h>, <mqueue.h>, <sched.h>, <semaphore.h>, and <spawn.h>,
289 functions marked as extensions other than as part of the MF or
290 MPR extensions in <sys/mman.h>, functions marked as ADV in
291 <fcntl.h>, and functions marked as CS, CPT, and TMR in <time.h>.
292 An implementation may search this library in the absence of this
293 operand.
294 -l trace
296 This operand shall make visible all functions referenced in
297 <trace.h>. An implementation may search this library in the
298 absence of this operand.
299 -l xnet
301 This operand makes visible all functions referenced in
302 <arpa/inet.h>, <netdb.h>, <netinet/in.h>, and <sys/socket.h>. An
303 implementation may search this library in the absence of this
304 operand.
305 -l y This operand shall make visible all functions required by the C-
307 language output of yacc that are not made available through the
308 -l c operand.
309 In the absence of options that inhibit invocation of the link editor,
312 such as -c or -E, the c99 utility shall cause the equivalent of a -l c
313 operand to be passed to the link editor as the last -l operand, causing
314 it to be searched after all other object files and libraries are
315 loaded.
316 It is unspecified whether the libraries libc.a, libm.a, librt.a,
318 libpthread.a, libl.a, liby.a, or libxnet.a exist as regular files. The
319 implementation may accept as -l operands names of objects that do not
320 exist as regular files.
321 External Symbols
323 The C compiler and link editor shall support the significance of exter‐
324 nal symbols up to a length of at least 31 bytes; the action taken upon
325 encountering symbols exceeding the implementation-defined maximum sym‐
326 bol length is unspecified.
327 The compiler and link editor shall support a minimum of 511 external
329 symbols per source or object file, and a minimum of 4095 external sym‐
330 bols in total. A diagnostic message shall be written to the standard
331 output if the implementation-defined limit is exceeded; other actions
332 are unspecified.
333 Programming Environments
335 All implementations shall support one of the following programming
336 environments as a default. Implementations may support more than one of
337 the following programming environments. Applications can use sysconf()
338 or getconf to determine which programming environments are supported.
339 Table: Programming Environments: Type Sizes
341 Programming Environment Bits in Bits in Bits in Bits in
343 getconf Name int long pointer off_t
344 _POSIX_V6_ILP32_OFF32 32 32 32 32
345 _POSIX_V6_ILP32_OFFBIG 32 32 32 >=64
346 _POSIX_V6_LP64_OFF64 32 64 64 64
347 _POSIX_V6_LPBIG_OFFBIG >=32 >=64 >=64 >=64
348 All implementations shall support one or more environments where the
350 widths of the following types are no greater than the width of type
351 long: blksize_t, cc_t, mode_t, nfds_t, pid_t, ptrdiff_t, size_t,
352 speed_t, ssize_t, suseconds_t, tcflag_t, useconds_t, wchar_t, wint_t
353 The executable files created when these environments are selected shall
355 be in a proper format for execution by the exec family of functions.
356 Each environment may be one of the ones in Programming Environments:
357 Type Sizes, or it may be another environment. The names for the envi‐
358 ronments that meet this requirement shall be output by a getconf com‐
359 mand using the _POSIX_V6_WIDTH_RESTRICTED_ENVS argument. If more than
360 one environment meets the requirement, the names of all such environ‐
361 ments shall be output on separate lines. Any of these names can then be
362 used in a subsequent getconf command to obtain the flags specific to
363 that environment with the following suffixes added as appropriate:
364 _CFLAGS
366 To get the C compiler flags.
367 _LDFLAGS
369 To get the linker/loader flags.
370 _LIBS To get the libraries.
372 This requirement may be removed in a future version of IEEE Std 1003.1.
375 When this utility processes a file containing a function called main(),
377 it shall be defined with a return type equivalent to int. Using return
378 from the initial call to main() shall be equivalent (other than with
379 respect to language scope issues) to calling exit() with the returned
380 value. Reaching the end of the initial call to main() shall be equiva‐
381 lent to calling exit(0). The implementation shall not declare a proto‐
382 type for this function.
383 Implementations provide configuration strings for C compiler flags,
385 linker/loader flags, and libraries for each supported environment. When
386 an application needs to use a specific programming environment rather
387 than the implementation default programming environment while compil‐
388 ing, the application shall first verify that the implementation sup‐
389 ports the desired environment. If the desired programming environment
390 is supported, the application shall then invoke c99 with the appropri‐
391 ate C compiler flags as the first options for the compile, the appro‐
392 priate linker/loader flags after any other options but before any oper‐
393 ands, and the appropriate libraries at the end of the operands.
394 Conforming applications shall not attempt to link together object files
396 compiled for different programming models. Applications shall also be
397 aware that binary data placed in shared memory or in files might not be
398 recognized by applications built for other programming models.
399 Table: Programming Environments: c99 and cc Arguments
401 Programming Environment c99 and cc Arguments
403 getconf Name Use getconf Name
404 _POSIX_V6_ILP32_OFF32 C Compiler Flags POSIX_V6_ILP32_OFF32_CFLAGS
405 Linker/Loader Flags POSIX_V6_ILP32_OFF32_LDFLAGS
406 Libraries POSIX_V6_ILP32_OFF32_LIBS
407 _POSIX_V6_ILP32_OFFBIG C Compiler Flags POSIX_V6_ILP32_OFFBIG_CFLAGS
408 Linker/Loader Flags POSIX_V6_ILP32_OFFBIG_LDFLAGS
409 Libraries POSIX_V6_ILP32_OFFBIG_LIBS
410 _POSIX_V6_LP64_OFF64 C Compiler Flags POSIX_V6_LP64_OFF64_CFLAGS
411 Linker/Loader Flags POSIX_V6_LP64_OFF64_LDFLAGS
412 Libraries POSIX_V6_LP64_OFF64_LIBS
413 _POSIX_V6_LPBIG_OFFBIG C Compiler Flags POSIX_V6_LPBIG_OFFBIG_CFLAGS
414 Linker/Loader Flags POSIX_V6_LPBIG_OFFBIG_LDFLAGS
415 Libraries POSIX_V6_LPBIG_OFFBIG_LIBS
416
418 The following exit values shall be returned:
419 0 Successful compilation or link edit.
421 >0 An error occurred.
423
426 When c99 encounters a compilation error that causes an object file not
427 to be created, it shall write a diagnostic to standard error and con‐
428 tinue to compile other source code operands, but it shall not perform
429 the link phase and return a non-zero exit status. If the link edit is
430 unsuccessful, a diagnostic message shall be written to standard error
431 and c99 exits with a non-zero status. A conforming application shall
432 rely on the exit status of c99, rather than on the existence or mode of
433 the executable file.
434 The following sections are informative.
436
438 Since the c99 utility usually creates files in the current directory
439 during the compilation process, it is typically necessary to run the
440 c99 utility in a directory in which a file can be created.
441 On systems providing POSIX Conformance (see the Base Definitions volume
443 of IEEE Std 1003.1-2001, Chapter 2, Conformance), c99 is required only
444 with the C-Language Development option; XSI-conformant systems always
445 provide c99.
446 Some historical implementations have created .o files when -c is not
448 specified and more than one source file is given. Since this area is
449 left unspecified, the application cannot rely on .o files being cre‐
450 ated, but it also must be prepared for any related .o files that
451 already exist being deleted at the completion of the link edit.
452 Some historical implementations have permitted -L options to be inter‐
454 spersed with -l operands on the command line. For an application to
455 compile consistently on systems that do not behave like this, it is
456 necessary for a conforming application to supply all -L options before
457 any of the -l options.
458 There is the possible implication that if a user supplies versions of
460 the standard functions (before they would be encountered by an implicit
461 -l c or explicit -l m), that those versions would be used in place of
462 the standard versions. There are various reasons this might not be
463 true (functions defined as macros, manipulations for clean name space,
464 and so on), so the existence of files named in the same manner as the
465 standard libraries within the -L directories is explicitly stated to
466 produce unspecified behavior.
467 All of the functions specified in the System Interfaces volume of
469 IEEE Std 1003.1-2001 may be made visible by implementations when the
470 Standard C Library is searched. Conforming applications must explicitly
471 request searching the other standard libraries when functions made vis‐
472 ible by those libraries are used.
473
475 1. The following usage example compiles foo.c and creates the exe‐
476 cutable file foo:
477 c99 -o foo foo.c
480 The following usage example compiles foo.c and creates the object file
482 foo.o:
483 c99 -c foo.c
486 The following usage example compiles foo.c and creates the executable
488 file a.out:
489 c99 foo.c
492 The following usage example compiles foo.c, links it with bar.o, and
494 creates the executable file a.out. It may also create and leave foo.o:
495 c99 foo.c bar.o
498 2. The following example shows how an application using threads inter‐
500 faces can test for support of and use a programming environment
501 supporting 32-bit int, long, and pointer types and an off_t type
502 using at least 64 bits:
503 if [ $(getconf _POSIX_V6_ILP32_OFFBIG) != "-1" ]
506 then
507 c99 $(getconf POSIX_V6_ILP32_OFFBIG_CFLAGS) -D_XOPEN_SOURCE=600 \
508 $(getconf POSIX_V6_ILP32_OFFBIG_LDFLAGS) foo.c -o foo \
509 $(getconf POSIX_V6_ILP32_OFFBIG_LIBS) -l pthread
510 else
511 echo ILP32_OFFBIG programming environment not supported
512 exit 1
513 fi
514 3. The following examples clarify the use and interactions of -L
516 options and -l operands.
517 Consider the case in which module a.c calls function f() in library
519 libQ.a, and module b.c calls function g() in library libp.a. Assume
520 that both libraries reside in /a/b/c. The command line to compile and
521 link in the desired way is:
522 c99 -L /a/b/c main.o a.c -l Q b.c -l p
525 In this case the -l Q operand need only precede the first -l p operand,
527 since both libQ.a and libp.a reside in the same directory.
528 Multiple -L operands can be used when library name collisions occur.
530 Building on the previous example, suppose that the user wants to use a
531 new libp.a, in /a/a/a, but still wants f() from /a/b/c/libQ.a:
532 c99 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p
535 In this example, the linker searches the -L options in the order speci‐
537 fied, and finds /a/a/a/libp.a before /a/b/c/libp.a when resolving ref‐
538 erences for b.c. The order of the -l operands is still important, how‐
539 ever.
540 4. The following example shows how an application can use a program‐
542 ming environment where the widths of the following types: blk‐
543 size_t, cc_t, mode_t, nfds_t, pid_t, ptrdiff_t, size_t, speed_t,
544 ssize_t, suseconds_t, tcflag_t, useconds_t, wchar_t, wint_t
545 are no greater than the width of type long:
547 # First choose one of the listed environments ...
550 # ... if there are no additional constraints, the first one will do:
553 CENV=$(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS | head -n l)
554 # ... or, if an environment that supports large files is preferred,
557 # look for names that contain "OFF64" or "OFFBIG". (This chooses
558 # the last one in the list if none match.)
559 for CENV in $(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS)
560 do
561 case $CENV in
562 *OFF64*|*OFFBIG*) break ;;
563 esac
564 done
565 # The chosen environment name can now be used like this:
568 c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200112L \
571 $(getconf ${CENV}_LDFLAGS) foo.c -o foo \
572 $(getconf ${CENV}_LIBS)
573
575 The c99 utility is based on the c89 utility originally introduced in
576 the ISO POSIX-2:1993 standard.
577 Some of the changes from c89 include the modification to the contents
579 of the Standard Libraries section to account for new headers and
580 options; for example, <spawn.h> added to the -l rt operand, and the -l
581 trace operand added for the Tracing functions.
582
584 None.
585
587 File Read, Write, and Creation, ar, getconf, make, nm, strip, umask(),
588 the System Interfaces volume of IEEE Std 1003.1-2001, exec, sysconf(),
589 the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Head‐
590 ers
591
593 Portions of this text are reprinted and reproduced in electronic form
594 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
595 -- Portable Operating System Interface (POSIX), The Open Group Base
596 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
597 Electrical and Electronics Engineers, Inc and The Open Group. In the
598 event of any discrepancy between this version and the original IEEE and
599 The Open Group Standard, the original IEEE and The Open Group Standard
600 is the referee document. The original Standard can be obtained online
601 at http://www.opengroup.org/unix/online.html .
602IEEE/The Open Group 2003 C99(1P)