2c 9.2 KB

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