8c 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490
  1. .TH 8C 1
  2. .SH NAME
  3. 0c, 5c, 6c, 8c, 9c, kc, qc, vc \- C compilers
  4. .SH SYNOPSIS
  5. .B 8c
  6. [
  7. .I option ...
  8. ]
  9. [
  10. .I file ...
  11. ]
  12. .br
  13. etc.
  14. .SH DESCRIPTION
  15. These commands compile the named C
  16. .I files
  17. into object files for the corresponding architecture.
  18. If there are multiple C
  19. .IR files ,
  20. the compilers will attempt to keep
  21. .B $NPROC
  22. compilations running concurrently.
  23. Associated with each compiler is a string
  24. .IR objtype ,
  25. for example
  26. .TF "6c amd64 "
  27. .PD
  28. .TP
  29. .B "0c spim
  30. little-endian MIPS 3000 family
  31. .TP
  32. .B "5c arm
  33. little-endian ARM
  34. .TP
  35. .B "6c amd64
  36. AMD64 and compatibles (e.g., Intel64)
  37. .TP
  38. .B "8c 386
  39. Intel i386, i486, Pentium, etc.
  40. .TP
  41. .B "9c power64
  42. 64-bit PowerPC
  43. .TP
  44. .B "kc sparc
  45. Sun (now Oracle) SPARC
  46. .TP
  47. .B "qc power
  48. PowerPC
  49. .TP
  50. .B "vc mips
  51. big-endian MIPS 3000 family
  52. .PP
  53. The compilers handle most preprocessing directives themselves; a complete
  54. preprocessor is available in
  55. .IR cpp (1),
  56. which must be run separately.
  57. .PP
  58. Let the first letter of the compiler name be
  59. .IR O =
  60. .BR 0 ,
  61. .BR 5 ,
  62. .BR 6 ,
  63. .BR 8 ,
  64. .BR 9 ,
  65. .BR k ,
  66. .BR q ,
  67. or
  68. .BR v .
  69. The output object files end in
  70. .RI . O .
  71. The letter is also the prefix of related programs:
  72. .IB O a
  73. is the assembler,
  74. .IB O l
  75. is the loader.
  76. Plan 9 conventionally sets the
  77. .B $objtype
  78. environment variable to the
  79. .I objtype
  80. string appropriate to the current machine's type.
  81. Plan 9 also conventionally has
  82. .RI / objtype
  83. directories, which contain among other things:
  84. .BR include ,
  85. for machine-dependent include files;
  86. .BR lib ,
  87. for public object code libraries;
  88. .BR bin ,
  89. for public programs;
  90. and
  91. .BR mkfile ,
  92. for preconditioning
  93. .IR mk (1).
  94. .PP
  95. The compiler options are:
  96. .TF Dname
  97. .PD
  98. .TP
  99. .BI -o " obj"
  100. Place output in file
  101. .I obj
  102. (allowed only if there is just one input file).
  103. Default is to take the last element of the input file name,
  104. strip any trailing
  105. .BR .c ,
  106. and append
  107. .RI . O .
  108. .TP
  109. .B -w
  110. Print warning messages about unused variables, etc.
  111. .TP
  112. .B -W
  113. Print all the messages that
  114. .B -w
  115. would print as warnings, but make them errors.
  116. .TP
  117. .B -B
  118. Accept functions without a new-style
  119. ANSI C function prototype.
  120. By default, the compilers reject functions
  121. used without a defined prototype,
  122. although ANSI C permits them.
  123. .TP
  124. .BI -D\*S name=def
  125. .br
  126. .ns
  127. .TP
  128. .BI -D \*Sname
  129. Define the
  130. .I name
  131. to the preprocessor,
  132. as if by
  133. .LR #define .
  134. If no definition is given, the name is defined as
  135. .LR 1 .
  136. .TP
  137. .BI -F
  138. Enable type-checking of calls to
  139. .IR print (2)
  140. and other formatted print routines. See the discussion
  141. of extensions, below.
  142. .TP
  143. .BI -I \*Sdir
  144. An
  145. .L #include
  146. file whose name does not begin with
  147. slash
  148. or is enclosed in double quotes
  149. is always
  150. sought first in the directory
  151. of the
  152. .I file
  153. argument. If this fails,
  154. the
  155. .I -.
  156. flag is given or the name is enclosed in
  157. .BR <> ,
  158. it is then sought
  159. in directories named in
  160. .B -I
  161. options,
  162. then in
  163. .BR /sys/include ,
  164. and finally in
  165. .BR /$objtype/include .
  166. .TP
  167. .B -.
  168. Suppress the automatic searching for include files in
  169. the directory of the file argument.
  170. .TP
  171. .B -N
  172. Suppress automatic registerization and optimization.
  173. .TP
  174. .B -S
  175. Print an assembly language version of the object code
  176. on standard output as well as generating the
  177. .RI . O
  178. file.
  179. .TP
  180. .B -T
  181. Pass type signatures on all external and global entities.
  182. The signature is based on the C
  183. .B signof
  184. operator.
  185. See
  186. .IR dynld (2).
  187. .TP
  188. .B -V
  189. By default, the compilers are non-standardly lax about type equality between
  190. .B void*
  191. values and other pointers; this flag requires ANSI C conformance.
  192. .TP
  193. .B -p
  194. Invoke a standard ANSI C preprocessor before compiling.
  195. .TP
  196. .B -a
  197. Instead of compiling, print on standard output acid functions (see
  198. .IR acid (1))
  199. for examining structures declared in the source files.
  200. .TP
  201. .B -aa
  202. Like
  203. .B -a
  204. except suppress information about structures
  205. declared in included header files.
  206. .TP
  207. .B -n
  208. When used with
  209. .B -a
  210. or
  211. .BR -aa ,
  212. places acid functions in
  213. .IB file .acid
  214. for input
  215. .IB file .c ,
  216. and not on standard output.
  217. .PP
  218. The compilers support several extensions to 1989 ANSI C,
  219. some of which were adopted in later ANSI C standards:
  220. .TF \|
  221. .PD
  222. .TP
  223. \-
  224. A structure or union may contain unnamed substructures and subunions.
  225. The fields of the substructures or
  226. subunions can then be used as if they were members of the parent
  227. structure or union (the resolution of a name conflict is unspecified).
  228. When a pointer to the outer structure or union is used in a context
  229. that is only legal for the unnamed substructure, the compiler promotes
  230. the type and adjusts the pointer value to point at the substructure.
  231. If the unnamed structure or union is of a type with a tag name specified by a
  232. .B typedef
  233. statement,
  234. the unnamed structure or union can be explicitly referenced
  235. by <struct variable>.<tagname>.
  236. .TP
  237. \-
  238. A structure value can be formed with an expression such as
  239. .EX
  240. (struct S){v1, v2, v3}
  241. .EE
  242. where the list elements are values for the fields of struct
  243. .BR S .
  244. .TP
  245. \-
  246. Array initializers can specify the indices of the array in square
  247. brackets, as
  248. .EX
  249. int a[] = { [3] 1, [10] 5 };
  250. .EE
  251. which initializes the third and tenth elements of the eleven-element array
  252. .BR a .
  253. .TP
  254. \-
  255. Structure initializers can specify the structure element by using the name
  256. following a period, as
  257. .EX
  258. struct { int x; int y; } s = { .y 1, .x 5 };
  259. .EE
  260. which initializes elements
  261. .B y
  262. and then
  263. .B x
  264. of the structure
  265. .BR s .
  266. These forms also accept the new ANSI C notation, which includes an equal sign:
  267. .EX
  268. int a[] = { [3] = 1, [10] = 5 };
  269. struct { int x; int y; } s = { .y = 1, .x = 5 };
  270. .EE
  271. .TP
  272. \-
  273. A global variable can be dedicated to a register
  274. by declaring it
  275. .B "extern register"
  276. in
  277. .I all
  278. modules and libraries.
  279. .TP
  280. \-
  281. A
  282. .B #pragma
  283. of the form
  284. .EX
  285. #pragma lib "libbio.a"
  286. .EE
  287. records that the program needs to be loaded with file
  288. .BR /$objtype/lib/libbio.a ;
  289. such lines, typically placed in library header files, obviate the
  290. .B -l
  291. option of the loaders. To help identify files in non-standard directories,
  292. within the file names in the
  293. .B #pragmas
  294. the string
  295. .B $M
  296. represents the name of the architecture
  297. (e.g.,
  298. .BR mips )
  299. and
  300. .B $O
  301. represents its identifying character
  302. (e.g.,
  303. .BR v ).
  304. .TP
  305. \-
  306. A
  307. .B #pragma
  308. of the form
  309. .EX
  310. #pragma varargck argpos error 2
  311. .EE
  312. tells the compiler that the second argument to
  313. .B error
  314. is a
  315. .BR print -like
  316. format string (see
  317. .IR print (2))
  318. that identifies the handling of subsequent arguments.
  319. The
  320. .B #pragma
  321. .EX
  322. #pragma varargck type "s" char*
  323. .EE
  324. says that the format verb
  325. .B s
  326. processes an argument of type
  327. .BR char *.
  328. The
  329. .B #pragma
  330. .EX
  331. #pragma varargck flag 'c'
  332. .EE
  333. says that
  334. .B c
  335. is a flag character.
  336. These
  337. .B #pragmas
  338. are used, if the
  339. .B -F
  340. option is enabled, to type-check calls to
  341. .B print
  342. and other such routines.
  343. .TP
  344. \-
  345. A
  346. .B #pragma
  347. with any of the following forms:
  348. .EX
  349. #pragma incomplete \fItype\fP
  350. #pragma incomplete struct \fItag\fP
  351. #pragma incomplete union \fItag\fP
  352. .EE
  353. where
  354. .I type
  355. is a
  356. .BR typedef 'd
  357. name for a structure or union type, and
  358. .I tag
  359. is a structure or union tag,
  360. tells the compiler that
  361. the corresponding type
  362. should have its signature calculated as an incomplete type
  363. even if it is subsequently fully defined.
  364. This allows the type signature mechanism to work in the presence
  365. of opaque types declared in header files, with their full definitions
  366. visible only to the code which manipulates them.
  367. With some imported software it might be necessary to turn off the
  368. signature generation completely for a large body of code (typically
  369. at the start and end of a particular include file).
  370. If
  371. .I type
  372. is the word
  373. .BR _off_ ,
  374. signature generation is turned off; if
  375. .I type
  376. is the word
  377. .BR _on_ ,
  378. the compiler will generate signatures.
  379. .TP
  380. \-
  381. The C++ comment
  382. .RB ( //
  383. to end of line)
  384. is accepted as well as the normal
  385. convention of
  386. .B /*
  387. .BR */ .
  388. .TP
  389. \-
  390. The compilers accept
  391. .B long
  392. .B long
  393. variables as a 64-bit type.
  394. The standard header typedefs this to
  395. .BR vlong .
  396. Arithmetic on
  397. .B vlong
  398. values is usually emulated by a run-time library,
  399. though in at least
  400. .IR 8c ,
  401. only division and modulus use the run-time library
  402. and the other operators generate in-line code
  403. (and
  404. .I uvlong-expression
  405. .I divison-or-modulus
  406. .BI "(1<<" constant )
  407. will turn into in-line bit operations,
  408. as is done for shorter
  409. .I unsigned
  410. expressions).
  411. .SH EXAMPLE
  412. For the 386, produce a program
  413. .B prog
  414. from C files
  415. .BR main.c
  416. and
  417. .BR sub.c :
  418. .IP
  419. .EX
  420. 8c -FVw main.c sub.c
  421. 8l -o prog main.8 sub.8
  422. .EE
  423. .SH FILES
  424. .TF /$objtype/include
  425. .TP
  426. .B /sys/include
  427. system area for machine-independent
  428. .B #include
  429. directives.
  430. .TP
  431. .B /$objtype/include
  432. system area for machine-dependent
  433. .B #include
  434. directives.
  435. .SH SOURCE
  436. .TF /sys/src/cmd/8c,\ etc.
  437. .TP
  438. .B /sys/src/cmd/cc
  439. machine-independent part
  440. .TP
  441. .BR /sys/src/cmd/8c ,\ etc.
  442. machine-dependent part
  443. .SH "SEE ALSO"
  444. .IR 8a (1),
  445. .IR 8l (1),
  446. .IR cpp (1),
  447. .IR mk (1),
  448. .IR nm (1),
  449. .IR pcc (1),
  450. .IR db (1),
  451. .IR acid (1)
  452. .\" .IR ansitize (1)
  453. .PP
  454. Rob Pike,
  455. ``How to Use the Plan 9 C Compiler''
  456. .SH BUGS
  457. The list of compilers given above is only partial,
  458. not all architectures are supported on all systems,
  459. some have been retired and some
  460. are provided by third parties.
  461. .PP
  462. The default preprocessor only handles
  463. .LR #define ,
  464. .LR #include ,
  465. .LR #undef ,
  466. .LR #ifdef ,
  467. .LR #line ,
  468. and
  469. .LR #ifndef .
  470. For a full ANSI preprocessor, use
  471. the
  472. .B p
  473. option.
  474. .PP
  475. The default search order for include files
  476. differs to that of
  477. .IR cpp (1).
  478. .PP
  479. Some new features of C99, the 1999 ANSI C standard,
  480. are implemented.
  481. No new features of C11, the 2011 ANSI C standard,
  482. are implemented.
  483. .PP
  484. The implementation of
  485. .B vlong
  486. assignment can use a static location
  487. and this can be disturbed by interrupts
  488. (e.g., notes)
  489. .RI ( 8c
  490. at least).