2c 8.0 KB

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