logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

c99.1p (33311B)


  1. '\" et
  2. .TH C99 "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. c99
  12. \(em compile standard C programs
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. c99 \fB[\fIoptions\fR...\fB] \fIpathname \fB[[\fIpathname\fB] [\fR-I \fIdirectory\fB]
  17. \fB[\fR-L \fIdirectory\fB] [\fR-l \fIlibrary\fB]]\fR...
  18. .fi
  19. .SH DESCRIPTION
  20. The
  21. .IR c99
  22. utility is an interface to the standard C compilation system; it shall
  23. accept source code conforming to the ISO\ C standard. The system conceptually
  24. consists of a compiler and link editor. The input files referenced by
  25. .IR pathname
  26. operands and
  27. .BR \-l
  28. option-arguments shall be compiled and linked to produce an executable
  29. file. (It is unspecified whether the linking occurs entirely within the
  30. operation of
  31. .IR c99 ;
  32. some implementations may produce objects that are not fully resolved
  33. until the file is executed.)
  34. .P
  35. If the
  36. .BR \-c
  37. option is specified, for all pathname operands of the form
  38. .IR file \c
  39. .BR .c ,
  40. the files:
  41. .sp
  42. .RS 4
  43. .nf
  44. $(basename \fIpathname\fR .c).o
  45. .fi
  46. .P
  47. .RE
  48. .P
  49. shall be created as the result of successful compilation. If the
  50. .BR \-c
  51. option is not specified, it is unspecified whether such
  52. .BR .o
  53. files are created or deleted for the
  54. .IR file \c
  55. .BR .c
  56. operands.
  57. .P
  58. If there are no options that prevent link editing (such as
  59. .BR \-c
  60. or
  61. .BR \-E ),
  62. and all input files compile and link without error, the resulting
  63. executable file shall be written according to the
  64. .BR \-o
  65. .IR outfile
  66. option (if present) or to the file
  67. .BR a.out .
  68. .P
  69. The executable file shall be created as specified in
  70. .IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation",
  71. except that the file permission bits shall be set to:
  72. S_IRWXO | S_IRWXG | S_IRWXU
  73. .P
  74. and the bits specified by the
  75. .IR umask
  76. of the process shall be cleared.
  77. .SH OPTIONS
  78. The
  79. .IR c99
  80. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  81. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  82. except that:
  83. .IP " *" 4
  84. Options can be interspersed with operands.
  85. .IP " *" 4
  86. The order of specifying the
  87. .BR \-L
  88. and
  89. .BR \-l
  90. options, and the order of specifying
  91. .BR \-l
  92. options with respect to
  93. .IR pathname
  94. operands is significant.
  95. .IP " *" 4
  96. Conforming applications shall specify each option separately; that is,
  97. grouping option letters (for example,
  98. .BR \-cO )
  99. need not be recognized by all implementations.
  100. .P
  101. The following options shall be supported:
  102. .IP "\fB\-c\fP" 10
  103. Suppress the link-edit phase of the compilation, and do not remove any
  104. object files that are produced.
  105. .IP "\fB\-D\ \fIname\fB[=\fIvalue\fB]\fR" 10
  106. .br
  107. Define
  108. .IR name
  109. as if by a C-language
  110. .BR #define
  111. directive. If no =\c
  112. .IR value
  113. is given, a value of 1 shall be used. The
  114. .BR \-D
  115. option has lower precedence than the
  116. .BR \-U
  117. option. That is, if
  118. .IR name
  119. is used in both a
  120. .BR \-U
  121. and a
  122. .BR \-D
  123. option,
  124. .IR name
  125. shall be undefined regardless of the order of the options. Additional
  126. implementation-defined
  127. .IR name s
  128. may be provided by the compiler. Implementations shall support at least
  129. 2\|048 bytes of
  130. .BR \-D
  131. definitions and 256
  132. .IR names .
  133. .IP "\fB\-E\fP" 10
  134. Copy C-language source files to standard output, executing all
  135. preprocessor directives; no compilation shall be performed. If any
  136. operand is not a text file, the effects are unspecified.
  137. .IP "\fB\-g\fP" 10
  138. Produce symbolic information in the object or executable files; the
  139. nature of this information is unspecified, and may be modified by
  140. implementation-defined interactions with other options.
  141. .IP "\fB\-I\ \fIdirectory\fR" 10
  142. Change the algorithm for searching for headers whose names are not
  143. absolute pathnames to look in the directory named by the
  144. .IR directory
  145. pathname before looking in the usual places. Thus, headers whose names
  146. are enclosed in double-quotes (\c
  147. .BR \(dq\^\(dq )
  148. shall be searched for first in the directory of the file with the
  149. .BR #include
  150. line, then in directories named in
  151. .BR \-I
  152. options, and last in the usual places. For headers whose names are
  153. enclosed in angle brackets (\c
  154. .BR \(dq<\|>\(dq ),
  155. the header shall be searched for only in directories named in
  156. .BR \-I
  157. options and then in the usual places. Directories named in
  158. .BR \-I
  159. options shall be searched in the order specified. If the
  160. .BR \-I
  161. option is used to specify a directory that is one of the usual places
  162. searched by default, the results are unspecified. Implementations shall
  163. support at least ten instances of this option in a single
  164. .IR c99
  165. command invocation.
  166. .IP "\fB\-L\ \fIdirectory\fR" 10
  167. Change the algorithm of searching for the libraries named in the
  168. .BR \-l
  169. objects to look in the directory named by the
  170. .IR directory
  171. pathname before looking in the usual places. Directories named in
  172. .BR \-L
  173. options shall be searched in the order specified. If the
  174. .BR \-L
  175. option is used to specify a directory that is one of the usual places
  176. searched by default, the results are unspecified. Implementations shall
  177. support at least ten instances of this option in a single
  178. .IR c99
  179. command invocation. If a directory specified by a
  180. .BR \-L
  181. option contains files with names starting with any of the strings
  182. .BR \(dqlibc.\(dq ,
  183. .BR \(dqlibl.\(dq ,
  184. .BR \(dqlibpthread.\(dq ,
  185. .BR \(dqlibm.\(dq ,
  186. .BR \(dqlibrt.\(dq ,
  187. .BR \(dqlibtrace.\(dq ,
  188. .BR \(dqlibxnet.\(dq ,
  189. or
  190. .BR \(dqliby.\(dq ,
  191. the results are unspecified.
  192. .IP "\fB\-l\ \fIlibrary\fR" 10
  193. Search the library named
  194. .BR liblibrary.a .
  195. A library shall be searched when its name is encountered, so the
  196. placement of a
  197. .BR \-l
  198. option is significant. Several standard libraries can be
  199. specified in this manner, as described in the EXTENDED DESCRIPTION
  200. section. Implementations may recognize implementation-defined
  201. suffixes other than
  202. .BR .a
  203. as denoting libraries.
  204. .IP "\fB\-O\ \fIoptlevel\fR" 10
  205. Specify the level of code optimization. If the
  206. .IR optlevel
  207. option-argument is the digit
  208. .BR '0' ,
  209. all special code optimizations shall be disabled. If it is the digit
  210. .BR '1' ,
  211. the nature of the optimization is unspecified. If the
  212. .BR \-O
  213. option is omitted, the nature of the system's default optimization is
  214. unspecified. It is unspecified whether code generated in the presence
  215. of the
  216. .BR \-O
  217. 0 option is the same as that generated when
  218. .BR \-O
  219. is omitted. Other
  220. .IR optlevel
  221. values may be supported.
  222. .IP "\fB\-o\ \fIoutfile\fR" 10
  223. Use the pathname
  224. .IR outfile ,
  225. instead of the default
  226. .BR a.out ,
  227. for the executable file produced. If the
  228. .BR \-o
  229. option is present with
  230. .BR \-c
  231. or
  232. .BR \-E ,
  233. the result is unspecified.
  234. .IP "\fB\-s\fP" 10
  235. Produce object or executable files, or both, from which symbolic and
  236. other information not required for proper execution using the
  237. .IR exec
  238. family defined in the System Interfaces volume of POSIX.1\(hy2017 has been removed (stripped). If both
  239. .BR \-g
  240. and
  241. .BR \-s
  242. options are present, the action taken is unspecified.
  243. .IP "\fB\-U\ \fIname\fR" 10
  244. Remove any initial definition of
  245. .IR name .
  246. .P
  247. Multiple instances of the
  248. .BR \-D ,
  249. .BR \-I ,
  250. .BR \-L ,
  251. .BR \-l ,
  252. and
  253. .BR \-U
  254. options can be specified.
  255. .SH OPERANDS
  256. The application shall ensure that at least one
  257. .IR pathname
  258. operand is specified. The following forms for
  259. .IR pathname
  260. operands shall be supported:
  261. .IP "\fIfile.\fBc\fR" 10
  262. A C-language source file to be compiled and optionally linked. The
  263. application shall ensure that the operand is of this form if the
  264. .BR \-c
  265. option is used.
  266. .IP "\fIfile.\fBa\fR" 10
  267. A library of object files typically produced by the
  268. .IR ar
  269. utility, and passed directly to the link editor. Implementations may
  270. recognize implementation-defined suffixes other than
  271. .BR .a
  272. as denoting object file libraries.
  273. .IP "\fIfile.\fBo\fR" 10
  274. An object file produced by
  275. .IR c99
  276. .BR \-c
  277. and passed directly to the link editor. Implementations may recognize
  278. implementation-defined suffixes other than
  279. .BR .o
  280. as denoting object files.
  281. .P
  282. The processing of other files is implementation-defined.
  283. .SH STDIN
  284. Not used.
  285. .SH "INPUT FILES"
  286. Each input file shall be one of the following: a text file containing a
  287. C-language source program, an object file in the format produced by
  288. .IR c99
  289. .BR \-c ,
  290. or a library of object files, in the format produced by archiving zero
  291. or more object files, using
  292. .IR ar .
  293. Implementations may supply additional utilities that produce files in
  294. these formats. Additional input file formats are
  295. implementation-defined.
  296. .SH "ENVIRONMENT VARIABLES"
  297. The following environment variables shall affect the execution of
  298. .IR c99 :
  299. .IP "\fILANG\fP" 10
  300. Provide a default value for the internationalization variables that are
  301. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  302. .IR "Section 8.2" ", " "Internationalization Variables"
  303. for the precedence of internationalization variables used to determine
  304. the values of locale categories.)
  305. .IP "\fILC_ALL\fP" 10
  306. If set to a non-empty string value, override the values of all the
  307. other internationalization variables.
  308. .IP "\fILC_CTYPE\fP" 10
  309. Determine the locale for the interpretation of sequences of bytes of
  310. text data as characters (for example, single-byte as opposed to
  311. multi-byte characters in arguments and input files).
  312. .IP "\fILC_MESSAGES\fP" 10
  313. .br
  314. Determine the locale that should be used to affect the format and
  315. contents of diagnostic messages written to standard error.
  316. .IP "\fINLSPATH\fP" 10
  317. Determine the location of message catalogs for the processing of
  318. .IR LC_MESSAGES .
  319. .IP "\fITMPDIR\fP" 10
  320. Provide a pathname that should override the default directory for
  321. temporary files, if any.
  322. On XSI-conforming systems, provide a pathname that shall override the
  323. default directory for temporary files, if any.
  324. .SH "ASYNCHRONOUS EVENTS"
  325. Default.
  326. .SH STDOUT
  327. If more than one
  328. .IR pathname
  329. operand ending in
  330. .BR .c
  331. (or possibly other unspecified suffixes) is given, for each such file:
  332. .sp
  333. .RS 4
  334. .nf
  335. "%s:\en", <\fIpathname\fR>
  336. .fi
  337. .P
  338. .RE
  339. .P
  340. may be written. These messages, if written, shall precede the
  341. processing of each input file; they shall not be written to the
  342. standard output if they are written to the standard error, as described
  343. in the STDERR section.
  344. .P
  345. If the
  346. .BR \-E
  347. option is specified, the standard output shall be a text file that
  348. represents the results of the preprocessing stage of the language; it
  349. may contain extra information appropriate for subsequent compilation
  350. passes.
  351. .SH STDERR
  352. The standard error shall be used only for diagnostic messages.
  353. If more than one
  354. .IR pathname
  355. operand ending in
  356. .BR .c
  357. (or possibly other unspecified suffixes) is given, for each such file:
  358. .sp
  359. .RS 4
  360. .nf
  361. "%s:\en", <\fIpathname\fR>
  362. .fi
  363. .P
  364. .RE
  365. .P
  366. may be written to allow identification of the diagnostic and warning
  367. messages with the appropriate input file. These messages, if written,
  368. shall precede the processing of each input file; they shall not be
  369. written to the standard error if they are written to the standard
  370. output, as described in the STDOUT section.
  371. .P
  372. This utility may produce warning messages about certain conditions that
  373. do not warrant returning an error (non-zero) exit value.
  374. .SH "OUTPUT FILES"
  375. Object files or executable files or both are produced in unspecified
  376. formats. If the pathname of an object file or executable file to be
  377. created by
  378. .IR c99
  379. resolves to an existing directory entry for a file that is not a regular
  380. file, it is unspecified whether
  381. .IR c99
  382. shall attempt to create the file or shall issue a diagnostic and exit
  383. with a non-zero exit status.
  384. .SH "EXTENDED DESCRIPTION"
  385. .SS "Standard Libraries"
  386. .P
  387. The
  388. .IR c99
  389. utility shall recognize the following
  390. .BR \-l
  391. options for standard libraries:
  392. .IP "\fB\-l\ c\fR" 10
  393. This option shall make available all interfaces referenced in the System Interfaces volume of POSIX.1\(hy2017,
  394. with the possible exception of those interfaces listed as residing in
  395. .IR <aio.h> ,
  396. .IR <arpa/inet.h> ,
  397. .IR <complex.h> ,
  398. .IR <fenv.h> ,
  399. .IR <math.h> ,
  400. .IR <mqueue.h> ,
  401. .IR <netdb.h> ,
  402. .IR <net/if.h> ,
  403. .IR <netinet/in.h> ,
  404. .IR <pthread.h> ,
  405. .IR <sched.h> ,
  406. .IR <semaphore.h> ,
  407. .IR <spawn.h> ,
  408. .IR <sys/socket.h> ,
  409. \fIpthread_kill\fR(),
  410. and
  411. \fIpthread_sigmask\fR()
  412. in
  413. .IR <signal.h> ,
  414. .IR <trace.h> ,
  415. interfaces marked as optional in
  416. .IR <sys/mman.h> ,
  417. interfaces marked as ADV (Advisory Information) in
  418. .IR <fcntl.h> ,
  419. and interfaces beginning with the prefix clock_ or timer_ in
  420. .IR <time.h> .
  421. This option shall not be required to be present to cause a search of
  422. this library.
  423. .IP "\fB\-l\ l\fR" 10
  424. This option shall make available all interfaces required by the
  425. C-language output of
  426. .IR lex
  427. that are not made available through the
  428. .BR "\-l\ c"
  429. option.
  430. .IP "\fB\-l\ pthread\fR" 10
  431. This option shall make available all interfaces referenced in
  432. .IR <pthread.h>
  433. and
  434. \fIpthread_kill\fR()
  435. and
  436. \fIpthread_sigmask\fR()
  437. referenced in
  438. .IR <signal.h> .
  439. An implementation may search this library in the absence of this
  440. option.
  441. .IP "\fB\-l\ m\fR" 10
  442. This option shall make available all interfaces referenced in
  443. .IR <math.h> ,
  444. .IR <complex.h> ,
  445. and
  446. .IR <fenv.h> .
  447. An implementation may search this library in the absence of this
  448. option.
  449. .IP "\fB\-l\ rt\fR" 10
  450. This option shall make available all interfaces referenced in
  451. .IR <aio.h> ,
  452. .IR <mqueue.h> ,
  453. .IR <sched.h> ,
  454. .IR <semaphore.h> ,
  455. and
  456. .IR <spawn.h> ,
  457. interfaces marked as optional in
  458. .IR <sys/mman.h> ,
  459. interfaces marked as ADV (Advisory Information) in
  460. .IR <fcntl.h> ,
  461. and interfaces beginning with the prefix clock_ and timer_ in
  462. .IR <time.h> .
  463. An implementation may search this library in the absence of this
  464. option.
  465. .IP "\fB\-l\ trace\fR" 10
  466. This option shall make available all interfaces referenced in
  467. .IR <trace.h> .
  468. An implementation may search this library in the absence of this
  469. option.
  470. .IP "\fB\-l\ xnet\fR" 10
  471. This option shall make available all interfaces referenced in
  472. .IR <arpa/inet.h> ,
  473. .IR <netdb.h> ,
  474. .IR <net/if.h> ,
  475. .IR <netinet/in.h> ,
  476. and
  477. .IR <sys/socket.h> .
  478. An implementation may search this library in the absence of this
  479. option.
  480. .IP "\fB\-l\ y\fR" 10
  481. This option shall make available all interfaces required by the
  482. C-language output of
  483. .IR yacc
  484. that are not made available through the
  485. .BR "\-l\ c"
  486. option.
  487. .P
  488. In the absence of options that inhibit invocation of the link editor,
  489. such as
  490. .BR \-c
  491. or
  492. .BR \-E ,
  493. the
  494. .IR c99
  495. utility shall cause the equivalent of a
  496. .BR "\-l\ c"
  497. option to be passed to the link editor after the last
  498. .IR pathname
  499. operand or
  500. .BR \-l
  501. option, causing it to be searched after all other object files and
  502. libraries are loaded.
  503. .P
  504. It is unspecified whether the libraries
  505. .BR libc.a ,
  506. .BR libl.a ,
  507. .BR libm.a ,
  508. .BR libpthread.a ,
  509. .BR librt.a ,
  510. .BR libtrace.a ,
  511. .BR libxnet.a ,
  512. or
  513. .BR liby.a
  514. exist as regular files. The implementation may accept as
  515. .BR \-l
  516. option-arguments names of objects that do not exist as regular files.
  517. .SS "External Symbols"
  518. .P
  519. The C compiler and link editor shall support the significance of
  520. external symbols up to a length of at least 31 bytes; the action taken
  521. upon encountering symbols exceeding the implementation-defined
  522. maximum symbol length is unspecified.
  523. .P
  524. The compiler and link editor shall support a minimum of 511 external
  525. symbols per source or object file, and a minimum of 4\|095 external
  526. symbols in total. A diagnostic message shall be written to the standard
  527. output if the implementation-defined limit is exceeded; other actions
  528. are unspecified.
  529. .SS "Header Search"
  530. .P
  531. If a file with the same name as one of the standard headers defined in the Base Definitions volume of POSIX.1\(hy2017,
  532. .IR "Chapter 13" ", " "Headers",
  533. not provided as part of the implementation, is placed in any of the
  534. usual places that are searched by default for headers, the results are
  535. unspecified.
  536. .SS "Programming Environments"
  537. .P
  538. All implementations shall support one of the following programming
  539. environments as a default. Implementations may support more than one
  540. of the following programming environments. Applications can use
  541. \fIsysconf\fR()
  542. or
  543. .IR getconf
  544. to determine which programming environments are supported.
  545. .br
  546. .sp
  547. .ce 1
  548. \fBTable 4-4: Programming Environments: Type Sizes\fR
  549. .TS
  550. center box tab(!);
  551. cB | cB | cB | cB | cB
  552. cB | cB | cB | cB | cB
  553. l | n | n | n | n.
  554. Programming Environment!Bits in!Bits in!Bits in!Bits in
  555. \fIgetconf\fP Name!int!long!pointer!off_t
  556. _
  557. _POSIX_V7_ILP32_OFF32!32!32!32!32
  558. _POSIX_V7_ILP32_OFFBIG!32!32!32!\(>=64
  559. _POSIX_V7_LP64_OFF64!32!64!64!64
  560. _POSIX_V7_LPBIG_OFFBIG!\(>=32!\(>=64!\(>=64!\(>=64
  561. .TE
  562. .P
  563. All implementations shall support one or more environments where the
  564. widths of the following types are no greater than the width of type
  565. .BR long :
  566. .TS
  567. tab(!) center;
  568. lB lB lB.
  569. T{
  570. .nf
  571. blksize_t
  572. cc_t
  573. mode_t
  574. nfds_t
  575. pid_t
  576. T}!T{
  577. .nf
  578. ptrdiff_t
  579. size_t
  580. speed_t
  581. ssize_t
  582. suseconds_t
  583. T}!T{
  584. .nf
  585. tcflag_t
  586. wchar_t
  587. wint_t
  588. .fi
  589. T}
  590. .TE
  591. .P
  592. The executable files created when these environments are selected shall
  593. be in a proper format for execution by the
  594. .IR exec
  595. family of functions. Each environment may be one of the ones in
  596. .IR "Table 4-4, Programming Environments: Type Sizes",
  597. or it may be another environment. The names for the environments that
  598. meet this requirement shall be output by a
  599. .IR getconf
  600. command using the POSIX_V7_WIDTH_RESTRICTED_ENVS argument, as a
  601. <newline>-separated
  602. list of names suitable for use with the
  603. .IR getconf
  604. .BR \-v
  605. option. If more than one environment meets the requirement, the names
  606. of all such environments shall be output on separate lines. Any of
  607. these names can then be used in a subsequent
  608. .IR getconf
  609. command to obtain the flags specific to that environment with the
  610. following suffixes added as appropriate:
  611. .IP _CFLAGS 10
  612. To get the C compiler flags.
  613. .IP _LDFLAGS 10
  614. To get the linker/loader flags.
  615. .IP _LIBS 10
  616. To get the libraries.
  617. .P
  618. This requirement may be removed in a future version.
  619. .P
  620. When this utility processes a file containing a function called
  621. \fImain\fR(),
  622. it shall be defined with a return type equivalent to
  623. .BR int .
  624. Using return from the initial call to
  625. \fImain\fR()
  626. shall be equivalent (other than with respect to language scope issues)
  627. to calling
  628. \fIexit\fR()
  629. with the returned value. Reaching the end of the initial call to
  630. \fImain\fR()
  631. shall be equivalent to calling
  632. .IR exit (0).
  633. The implementation shall not declare a prototype for this function.
  634. .P
  635. Implementations provide configuration strings for C compiler flags,
  636. linker/loader flags, and libraries for each supported environment.
  637. When an application needs to use a specific programming environment
  638. rather than the implementation default programming environment while
  639. compiling, the application shall first verify that the implementation
  640. supports the desired environment. If the desired programming
  641. environment is supported, the application shall then invoke
  642. .IR c99
  643. with the appropriate C compiler flags as the first options for the
  644. compile, the appropriate linker/loader flags after any other options
  645. except
  646. .BR \-l
  647. but before any operands or
  648. .BR \-l
  649. options, and the appropriate libraries at the end of the operands
  650. and
  651. .BR \-l
  652. options.
  653. .P
  654. Conforming applications shall not attempt to link together object files
  655. compiled for different programming models. Applications shall also be
  656. aware that binary data placed in shared memory or in files might not be
  657. recognized by applications built for other programming models.
  658. .br
  659. .sp
  660. .ce 1
  661. \fBTable 4-5: Programming Environments: \fIc99\fP Arguments\fR
  662. .TS
  663. center box tab(!);
  664. cB | cB | cB
  665. cB | cB | cB
  666. l | l | l.
  667. Programming Environment!!\fIc99\fP Arguments
  668. \fIgetconf\fP Name!Use!\fIgetconf\fP Name
  669. _
  670. _POSIX_V7_ILP32_OFF32!C Compiler Flags!POSIX_V7_ILP32_OFF32_CFLAGS
  671. !Linker/Loader Flags!POSIX_V7_ILP32_OFF32_LDFLAGS
  672. !Libraries!POSIX_V7_ILP32_OFF32_LIBS
  673. _
  674. _POSIX_V7_ILP32_OFFBIG!C Compiler Flags!POSIX_V7_ILP32_OFFBIG_CFLAGS
  675. !Linker/Loader Flags!POSIX_V7_ILP32_OFFBIG_LDFLAGS
  676. !Libraries!POSIX_V7_ILP32_OFFBIG_LIBS
  677. _
  678. _POSIX_V7_LP64_OFF64!C Compiler Flags!POSIX_V7_LP64_OFF64_CFLAGS
  679. !Linker/Loader Flags!POSIX_V7_LP64_OFF64_LDFLAGS
  680. !Libraries!POSIX_V7_LP64_OFF64_LIBS
  681. _
  682. _POSIX_V7_LPBIG_OFFBIG!C Compiler Flags!POSIX_V7_LPBIG_OFFBIG_CFLAGS
  683. !Linker/Loader Flags!POSIX_V7_LPBIG_OFFBIG_LDFLAGS
  684. !Libraries!POSIX_V7_LPBIG_OFFBIG_LIBS
  685. .TE
  686. .P
  687. In addition to the type size programming environments above, all
  688. implementations also support a multi-threaded programming environment
  689. that is orthogonal to all of the programming environments listed above.
  690. The
  691. .IR getconf
  692. utility can be used to get flags for the threaded programming environment,
  693. as indicated in
  694. .IR "Table 4-6, Threaded Programming Environment: \fIc99\fP Arguments".
  695. .sp
  696. .ce 1
  697. \fBTable 4-6: Threaded Programming Environment: \fIc99\fP Arguments\fR
  698. .TS
  699. center box tab(!);
  700. cB | cB | cB
  701. cB | cB | cB
  702. l | l | l.
  703. Programming Environment!!\fIc99\fP Arguments
  704. \fIgetconf\fP Name!Use!\fIgetconf\fP Name
  705. _
  706. _POSIX_THREADS!C Compiler Flags!POSIX_V7_THREADS_CFLAGS
  707. !Linker/Loader Flags!POSIX_V7_THREADS_LDFLAGS
  708. .TE
  709. .P
  710. These programming environment flags may be used in conjunction with any
  711. of the type size programming environments supported by the implementation.
  712. .SH "EXIT STATUS"
  713. The following exit values shall be returned:
  714. .IP "\00" 6
  715. Successful compilation or link edit.
  716. .IP >0 6
  717. An error occurred.
  718. .SH "CONSEQUENCES OF ERRORS"
  719. When
  720. .IR c99
  721. encounters a compilation error that causes an object file not to be
  722. created, it shall write a diagnostic to standard error and continue to
  723. compile other source code operands, but it shall not perform the link
  724. phase and it shall return a non-zero exit status. If the link edit is
  725. unsuccessful, a diagnostic message shall be written to standard error
  726. and
  727. .IR c99
  728. exits with a non-zero status. A conforming application shall rely on the
  729. exit status of
  730. .IR c99 ,
  731. rather than on the existence or mode of the executable file.
  732. .LP
  733. .IR "The following sections are informative."
  734. .SH "APPLICATION USAGE"
  735. Since the
  736. .IR c99
  737. utility usually creates files in the current directory during the
  738. compilation process, it is typically necessary to run the
  739. .IR c99
  740. utility in a directory in which a file can be created.
  741. .P
  742. On systems providing POSIX Conformance (see the Base Definitions volume of POSIX.1\(hy2017,
  743. .IR "Chapter 2" ", " "Conformance"),
  744. .IR c99
  745. is required only with the C-Language Development option;
  746. XSI-conformant systems always provide
  747. .IR c99 .
  748. .P
  749. Some historical implementations have created
  750. .BR .o
  751. files when
  752. .BR \-c
  753. is not specified and more than one source file is given. Since this
  754. area is left unspecified, the application cannot rely on
  755. .BR .o
  756. files being created, but it also must be prepared for any related
  757. .BR .o
  758. files that already exist being deleted at the completion of the link
  759. edit.
  760. .P
  761. There is the possible implication that if a user supplies versions of
  762. the standard functions (before they would be encountered by an implicit
  763. .BR "\-l\ c"
  764. or explicit
  765. .BR "\-l\ m" ),
  766. that those versions would be used in place of the standard versions.
  767. There are various reasons this might not be true (functions defined as
  768. macros, manipulations for clean name space, and so on), so the
  769. existence of files named in the same manner as the standard libraries
  770. within the
  771. .BR \-L
  772. directories is explicitly stated to produce unspecified behavior.
  773. .P
  774. All of the functions specified in the System Interfaces volume of POSIX.1\(hy2017 may be made visible by
  775. implementations when the Standard C Library is searched. Conforming
  776. applications must explicitly request searching the other standard
  777. libraries when functions made visible by those libraries are used.
  778. .P
  779. In the ISO\ C standard the mapping from physical source characters to the C
  780. source character set is implementation-defined. Implementations may
  781. strip white-space characters before the terminating
  782. <newline>
  783. of a (physical) line as part of this mapping and, as a consequence
  784. of this, one or more white-space characters (and no other characters)
  785. between a
  786. <backslash>
  787. character and the
  788. <newline>
  789. character that terminates the line produces implementation-defined
  790. results. Portable applications should not use such constructs.
  791. .P
  792. Some
  793. .IR c99
  794. compilers not conforming to POSIX.1\(hy2008 do not support trigraphs by default.
  795. .SH EXAMPLES
  796. .IP " 1." 4
  797. The following usage example compiles
  798. .BR foo.c
  799. and creates the executable file
  800. .BR foo :
  801. .RS 4
  802. .sp
  803. .RS 4
  804. .nf
  805. c99 -o foo foo.c
  806. .fi
  807. .P
  808. .RE
  809. .P
  810. The following usage example compiles
  811. .BR foo.c
  812. and creates the object file
  813. .BR foo.o :
  814. .sp
  815. .RS 4
  816. .nf
  817. c99 -c foo.c
  818. .fi
  819. .P
  820. .RE
  821. .P
  822. The following usage example compiles
  823. .BR foo.c
  824. and creates the executable file
  825. .BR a.out :
  826. .sp
  827. .RS 4
  828. .nf
  829. c99 foo.c
  830. .fi
  831. .P
  832. .RE
  833. .P
  834. The following usage example compiles
  835. .BR foo.c ,
  836. links it with
  837. .BR bar.o ,
  838. and creates the executable file
  839. .BR a.out .
  840. It may also create and leave
  841. .BR foo.o :
  842. .sp
  843. .RS 4
  844. .nf
  845. c99 foo.c bar.o
  846. .fi
  847. .P
  848. .RE
  849. .RE
  850. .IP " 2." 4
  851. The following example shows how an application using threads interfaces
  852. can test for support of and use a programming environment supporting
  853. 32-bit
  854. .BR int ,
  855. .BR long ,
  856. and
  857. .BR pointer
  858. types and an
  859. .BR off_t
  860. type using at least 64 bits:
  861. .RS 4
  862. .sp
  863. .RS 4
  864. .nf
  865. offbig_env=$(getconf _POSIX_V7_ILP32_OFFBIG)
  866. if [ $offbig_env != "-1" ] && [ $offbig_env != "undefined" ]
  867. then
  868. c99 $(getconf POSIX_V7_ILP32_OFFBIG_CFLAGS) \e
  869. $(getconf POSIX_V7_THREADS_CFLAGS) -D_XOPEN_SOURCE=700 \e
  870. $(getconf POSIX_V7_ILP32_OFFBIG_LDFLAGS) \e
  871. $(getconf POSIX_V7_THREADS_LDFLAGS) foo.c -o foo \e
  872. $(getconf POSIX_V7_ILP32_OFFBIG_LIBS) \e
  873. -l pthread
  874. else
  875. echo ILP32_OFFBIG programming environment not supported
  876. exit 1
  877. fi
  878. .fi
  879. .P
  880. .RE
  881. .RE
  882. .IP " 3." 4
  883. The following examples clarify the use and interactions of
  884. .BR \-L
  885. and
  886. .BR \-l
  887. options.
  888. .RS 4
  889. .P
  890. Consider the case in which module
  891. .BR a.c
  892. calls function
  893. \fIf\fR()
  894. in library
  895. .BR libQ.a ,
  896. and module
  897. .BR b.c
  898. calls function
  899. \fIg\fR()
  900. in library
  901. .BR libp.a .
  902. Assume that both libraries reside in
  903. .BR /a/b/c .
  904. The command line to compile and link in the desired way is:
  905. .sp
  906. .RS 4
  907. .nf
  908. c99 -L /a/b/c main.o a.c -l Q b.c -l p
  909. .fi
  910. .P
  911. .RE
  912. .P
  913. In this case the
  914. .BR \-L
  915. option need only precede the first
  916. .BR \-l
  917. option, since both
  918. .BR libQ.a
  919. and
  920. .BR libp.a
  921. reside in the same directory.
  922. .P
  923. Multiple
  924. .BR \-L
  925. options can be used when library name collisions occur. Building on
  926. the previous example, suppose that the user wants to use a new
  927. .BR libp.a ,
  928. in
  929. .BR /a/a/a ,
  930. but still wants
  931. \fIf\fR()
  932. from
  933. .BR /a/b/c/libQ.a :
  934. .sp
  935. .RS 4
  936. .nf
  937. c99 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p
  938. .fi
  939. .P
  940. .RE
  941. .P
  942. In this example, the linker searches the
  943. .BR \-L
  944. options in the order specified, and finds
  945. .BR /a/a/a/libp.a
  946. before
  947. .BR /a/b/c/libp.a
  948. when resolving references for
  949. .BR b.c .
  950. The order of the
  951. .BR \-l
  952. options is still important, however.
  953. .RE
  954. .IP " 4." 4
  955. The following example shows how an application can use a programming
  956. environment where the widths of the following types:
  957. .BR blksize_t ,
  958. .BR cc_t ,
  959. .BR mode_t ,
  960. .BR nfds_t ,
  961. .BR pid_t ,
  962. .BR ptrdiff_t ,
  963. .BR size_t ,
  964. .BR speed_t ,
  965. .BR ssize_t ,
  966. .BR suseconds_t ,
  967. .BR tcflag_t ,
  968. .BR wchar_t ,
  969. .BR wint_t
  970. .RS 4
  971. .P
  972. are no greater than the width of type
  973. .BR long :
  974. .sp
  975. .RS 4
  976. .nf
  977. # First choose one of the listed environments ...
  978. .P
  979. # ... if there are no additional constraints, the first one will do:
  980. CENV=$(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS | head -n l)
  981. .P
  982. # ... or, if an environment that supports large files is preferred,
  983. # look for names that contain "OFF64" or "OFFBIG". (This chooses
  984. # the last one in the list if none match.)
  985. for CENV in $(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS)
  986. do
  987. case $CENV in
  988. *OFF64*|*OFFBIG*) break ;;
  989. esac
  990. done
  991. .P
  992. # The chosen environment name can now be used like this:
  993. .P
  994. c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200809L \e
  995. $(getconf ${CENV}_LDFLAGS) foo.c -o foo \e
  996. $(getconf ${CENV}_LIBS)
  997. .fi
  998. .P
  999. .RE
  1000. .RE
  1001. .SH RATIONALE
  1002. The
  1003. .IR c99
  1004. utility is based on the
  1005. .IR c89
  1006. utility originally introduced in the ISO\ POSIX\(hy2:\|1993 standard.
  1007. .P
  1008. Some of the changes from
  1009. .IR c89
  1010. include the ability to intersperse options and operands (which many
  1011. .IR c89
  1012. implementations allowed despite it not being specified),
  1013. the description of
  1014. .BR \-l
  1015. as an option instead of an operand, and the modification to the contents
  1016. of the Standard Libraries section to account for new headers and options;
  1017. for example,
  1018. .IR <spawn.h>
  1019. added to the description of
  1020. .BR "\-l\ rt" ,
  1021. and
  1022. .BR "\-l\ trace"
  1023. added for the Tracing option.
  1024. .P
  1025. POSIX.1\(hy2008 specifies that the
  1026. .IR c99
  1027. utility must be able to use regular files for
  1028. .BR *.o
  1029. files and for
  1030. .BR a.out
  1031. files. Implementations are free to overwrite existing files of other
  1032. types when attempting to create object files and executable files, but
  1033. are not required to do so. If something other than a regular file is
  1034. specified and using it fails for any reason,
  1035. .IR c99
  1036. is required to issue a diagnostic message and exit with a non-zero exit
  1037. status. But for some file types, the problem may not be noticed for a
  1038. long time. For example, if a FIFO named
  1039. .BR a.out
  1040. exists in the current directory,
  1041. .IR c99
  1042. may attempt to open
  1043. .BR a.out
  1044. and will hang in the
  1045. \fIopen\fR()
  1046. call until another process opens the FIFO for reading. Then
  1047. .IR c99
  1048. may write most of the
  1049. .BR a.out
  1050. to the FIFO and fail when it tries to seek back close to the start of
  1051. the file to insert a timestamp (FIFOs are not seekable files). The
  1052. .IR c99
  1053. utility is also allowed to issue a diagnostic immediately if it
  1054. encounters an
  1055. .BR a.out
  1056. or
  1057. .BR *.o
  1058. file that is not a regular file. For portable use, applications should
  1059. ensure that any
  1060. .BR a.out ,
  1061. .BR \-o
  1062. option-argument, or
  1063. .BR *.o
  1064. files corresponding to any
  1065. .BR *.c
  1066. files do not conflict with names already in use that are not regular
  1067. files or symbolic links that point to regular files.
  1068. .P
  1069. On many systems, multi-threaded applications run in a programming
  1070. environment that is distinct from that used by single-threaded
  1071. applications. This multi-threaded programming environment (in addition
  1072. to needing to specify
  1073. .BR "\-l pthread"
  1074. at link time) may require additional flags to be set when headers are
  1075. processed at compile time (\c
  1076. .BR \-D_REENTRANT
  1077. being common). This programming environment is orthogonal to the type
  1078. size programming environments discussed above and listed in
  1079. .IR "Table 4-4, Programming Environments: Type Sizes".
  1080. This version of the standard adds
  1081. .IR getconf
  1082. utility calls to provide the C compiler flags and linker/loader flags
  1083. needed to support multi-threaded applications. Note that on a system
  1084. where single-threaded applications are a special case of a multi-threaded
  1085. application, both of these
  1086. .IR getconf
  1087. calls may return NULL strings; on other implementations both of
  1088. these strings may be non-NULL strings.
  1089. .P
  1090. The C standardization committee invented trigraphs (e.g.,
  1091. .BR \(dq??!\(dq
  1092. to represent
  1093. .BR '|' )
  1094. to address character portability problems in development environments
  1095. based on national variants of the 7-bit ISO/IEC\ 646:\|1991 standard character set. However,
  1096. these environments were already obsolete by the time the first ISO\ C standard was
  1097. published, and in practice trigraphs have not been used for their intended
  1098. purpose, and usually are intended to have their original meaning in K&R C.
  1099. For example, in practice a C-language source string like
  1100. .BR \(dqWhat??!\(dq
  1101. is usually intended to end in two
  1102. <question-mark>
  1103. characters and an
  1104. <exclamation-mark>,
  1105. not in
  1106. .BR '|' .
  1107. .P
  1108. When the
  1109. .BR \-E
  1110. option is used, execution of some
  1111. .BR #pragma
  1112. preprocessor directives may simply result in a copy of the directive being
  1113. included in the output as part of the allowed extra information used by
  1114. subsequent compilation passes (see STDOUT).
  1115. .SH "FUTURE DIRECTIONS"
  1116. Unlike all of the other non-OB-shaded utilities in this standard, a utility
  1117. by this name probably will not appear in the next version of this standard.
  1118. This utility's name is tied to the current revision of the ISO\ C standard at the
  1119. time this standard is approved. Since the ISO\ C standard and this standard are
  1120. maintained by different organizations on different schedules, we cannot
  1121. predict what the compiler will be named in the next version
  1122. of the standard.
  1123. .SH "SEE ALSO"
  1124. .IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation",
  1125. .IR "\fIar\fR\^",
  1126. .IR "\fIgetconf\fR\^",
  1127. .IR "\fImake\fR\^",
  1128. .IR "\fInm\fR\^",
  1129. .IR "\fIstrip\fR\^",
  1130. .IR "\fIumask\fR\^"
  1131. .P
  1132. The Base Definitions volume of POSIX.1\(hy2017,
  1133. .IR "Chapter 8" ", " "Environment Variables",
  1134. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  1135. .IR "Chapter 13" ", " "Headers"
  1136. .P
  1137. The System Interfaces volume of POSIX.1\(hy2017,
  1138. .IR "\fIexec\fR\^",
  1139. .IR "\fIsysconf\fR\^(\|)"
  1140. .\"
  1141. .SH COPYRIGHT
  1142. Portions of this text are reprinted and reproduced in electronic form
  1143. from IEEE Std 1003.1-2017, Standard for Information Technology
  1144. -- Portable Operating System Interface (POSIX), The Open Group Base
  1145. Specifications Issue 7, 2018 Edition,
  1146. Copyright (C) 2018 by the Institute of
  1147. Electrical and Electronics Engineers, Inc and The Open Group.
  1148. In the event of any discrepancy between this version and the original IEEE and
  1149. The Open Group Standard, the original IEEE and The Open Group Standard
  1150. is the referee document. The original Standard can be obtained online at
  1151. http://www.opengroup.org/unix/online.html .
  1152. .PP
  1153. Any typographical or formatting errors that appear
  1154. in this page are most likely
  1155. to have been introduced during the conversion of the source files to
  1156. man page format. To report such errors, see
  1157. https://www.kernel.org/doc/man-pages/reporting_bugs.html .