changelog shortlog tags branches changeset files revisions annotate raw help

Mercurial > hg > plan9front / sys/man/1/2c

changeset 7400: 561b0ec255dc
parent: 99bdb1461cbe
author: cinap_lenrek@felloff.net
date: Sun, 22 Sep 2019 19:09:25 +0200
permissions: -rw-r--r--
description: 2c(1): document 7c (arm64)
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 .TF "6c amd64 "
27 .PD
28 .TP
29 .B "0c spim
30 little-endian MIPS 3000 family
31 .TP
32 .B "1c 68000
33 Motorola MC68000
34 .TP
35 .B "2c 68020
36 Motorola MC68020
37 .TP
38 .B "5c arm
39 little-endian ARM
40 .TP
41 .B "6c amd64
42 AMD64 and compatibles (e.g., Intel EM64T)
43 .TP
44 .B "7c arm64
45 ARM64 (ARMv8)
46 .TP
47 .B "8c 386
48 Intel i386, i486, Pentium, etc.
49 .TP
50 .B "kc sparc
51 Sun SPARC
52 .TP
53 .B "qc power
54 Power PC
55 .TP
56 .B "vc mips
57 big-endian MIPS 3000 family
58 .PP
59 The compilers handle most preprocessing directives themselves; a complete
60 preprocessor is available in
61 .IR cpp (1),
62 which must be run separately.
63 .PP
64 Let the first letter of the compiler name be
65 .IR O =
66 .BR 0 ,
67 .BR 1 ,
68 .BR 2 ,
69 .BR 5 ,
70 .BR 6 ,
71 .BR 7 ,
72 .BR 8 ,
73 .BR k ,
74 .BR q ,
75 or
76 .BR v .
77 The output object files end in
78 .RI . O .
79 The letter is also the prefix of related programs:
80 .IB O a
81 is the assembler,
82 .IB O l
83 is the loader.
84 Plan 9 conventionally sets the
85 .B $objtype
86 environment variable to the
87 .I objtype
88 string appropriate to the current machine's type.
89 Plan 9 also conventionally has
90 .RI / objtype
91 directories, which contain among other things:
92 .BR include ,
93 for machine-dependent include files;
94 .BR lib ,
95 for public object code libraries;
96 .BR bin ,
97 for public programs;
98 and
99 .BR mkfile ,
100 for preconditioning
101 .IR mk (1).
102 .PP
103 The compiler options are:
104 .TF Dname
105 .PD
106 .TP
107 .BI -o " obj"
108 Place output in file
109 .I obj
110 (allowed only if there is just one input file).
111 Default is to take the last element of the input file name,
112 strip any trailing
113 .BR .c ,
114 and append
115 .RI . O .
116 .TP
117 .B -w
118 Print warning messages about unused variables, etc.
119 .TP
120 .B -B
121 Accept functions without a new-style
122 ANSI C function prototype.
123 By default, the compilers reject functions
124 used without a defined prototype,
125 although ANSI C permits them.
126 .TP
127 .BI -D\*S name=def
128 .br
129 .ns
130 .TP
131 .BI -D \*Sname
132 Define the
133 .I name
134 to the preprocessor,
135 as if by
136 .LR #define .
137 If no definition is given, the name is defined as
138 .LR 1 .
139 .TP
140 .BI -F
141 Enable type-checking of calls to
142 .IR print (2)
143 and other formatted print routines. See the discussion
144 of extensions, below.
145 .TP
146 .BI -I \*Sdir
147 An
148 .L #include
149 file whose name does not begin with
150 slash
151 or is enclosed in double quotes
152 is always
153 sought first in the directory
154 of the
155 .I file
156 argument. If this fails,
157 the
158 .I -.
159 flag is given or the name is enclosed in
160 .BR <> ,
161 it is then sought
162 in directories named in
163 .B -I
164 options,
165 then in
166 .BR /sys/include ,
167 and finally in
168 .BR /$objtype/include .
169 .TP
170 .B -.
171 Suppress the automatic searching for include files in
172 the directory of the file argument.
173 .TP
174 .B -N
175 Suppress automatic registerization and optimization.
176 .TP
177 .B -S
178 Print an assembly language version of the object code
179 on standard output as well as generating the
180 .RI . O
181 file.
182 .TP
183 .B -T
184 Pass type signatures on all external and global entities.
185 The signature is based on the C
186 .B signof
187 operator.
188 .TP
189 .B -V
190 By default, the compilers are non-standardly lax about type equality between
191 .B void*
192 values and other pointers; this flag requires ANSI C conformance.
193 .TP
194 .B -p
195 Invoke a standard ANSI C preprocessor before compiling.
196 .TP
197 .B -a
198 Instead of compiling, print on standard output acid functions (see
199 .IR acid (1))
200 for examining structures declared in the source files.
201 .TP
202 .B -aa
203 Like
204 .B -a
205 except suppress information about structures
206 declared in included header files.
207 .TP
208 .B -n
209 When used with
210 .B -a
211 or
212 .BR -aa ,
213 places acid functions in
214 .IB file .acid
215 for input
216 .IB file .c ,
217 and not on standard output.
218 .PP
219 The compilers support several extensions to ANSI C:
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 division-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 .PP
412 Other differences with ANSI C include
413 .TF \|
414 .PD
415 .TP
416 \-
417 The compilers use the original "unsigned preserving", rather than ANSI C "value preserving" rules, which means that, e.g.,
418 .B "unsigned char"
419 gets promoted to
420 .B "unsigned int"
421 rather than
422 .BR "int" .
423 .TP
424 \-
425 Parameters in macros are substituted inside of strings.
426 .SH EXAMPLE
427 For the 68020, produce a program
428 .B prog
429 from C files
430 .BR main.c
431 and
432 .BR sub.c :
433 .IP
434 .EX
435 2c -FVw main.c sub.c
436 2l -o prog main.2 sub.2
437 .EE
438 .SH FILES
439 .TF /$objtype/include
440 .TP
441 .B /sys/include
442 system area for machine-independent
443 .B #include
444 directives.
445 .TP
446 .B /$objtype/include
447 system area for machine-dependent
448 .B #include
449 directives.
450 .SH SOURCE
451 .TF /sys/src/cmd/2c,\ etc.
452 .TP
453 .B /sys/src/cmd/cc
454 machine-independent part
455 .TP
456 .BR /sys/src/cmd/2c ,\ etc.
457 machine-dependent part
458 .SH "SEE ALSO"
459 .IR 2a (1),
460 .IR 2l (1),
461 .IR cpp (1),
462 .IR mk (1),
463 .IR nm (1),
464 .IR pcc (1),
465 .IR db (1),
466 .IR acid (1)
467 .\" .IR ansitize (1)
468 .PP
469 Rob Pike,
470 ``How to Use the Plan 9 C Compiler''
471 .SH BUGS
472 The list of compilers given above is only partial,
473 not all architectures are supported on all systems,
474 some have been retired and some
475 are provided by third parties.
476 .PP
477 The default preprocessor only handles
478 .LR #define ,
479 .LR #include ,
480 .LR #undef ,
481 .LR #ifdef ,
482 .LR #line ,
483 and
484 .LR #ifndef .
485 For a full ANSI preprocessor, use
486 the
487 .B p
488 option.
489 .PP
490 The default search order for include files
491 differs to that of
492 .IR cpp (1).
493 .PP
494 Some features of C99, the 1999 ANSI C standard,
495 are implemented.
496 .PP
497 .B switch
498 expressions may not be either signedness of
499 .B vlong
500 on 32-bit architectures
501 .RI ( 8c
502 at least).
503 .PP
504 The implementation of
505 .B vlong
506 assignment can use a static location
507 and this can be disturbed by interrupts
508 (e.g., notes)
509 .RI ( 8c
510 at least).