2c 9.0 KB

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