| blob | 226f875d2e732e14a5875e8602eac4f762d8a30c |
1 .\" $OpenBSD: gcc-local.1,v 1.36 2013/02/08 07:37:43 jmc Exp $
2 .\"
3 .\" Copyright (c) 2002 Marc Espie
4 .\" Copyright (c) 2003 Anil Madhavapeddy
5 .\"
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .Dd $Mdocdate: February 8 2013 $
29 .Dt GCC-LOCAL 1
30 .Os
31 .Sh NAME
32 .Nm gcc-local
33 .Nd local modifications to gcc
34 .Sh DESCRIPTION
35 .Ox
36 uses derivatives of
37 .Xr gcc 1
38 versions 2.95.3, 3.3.6 or 4.2.1,
39 depending on machine architecture.
40 In all cases,
41 the software comes with specific modifications for
42 .Ox :
43 .Bl -dash
44 .It
45 .Nm gcc
46 does not search under
47 .Pa /usr/local
48 for include files nor for libraries:
49 as a system compiler, it only searches the system paths by default.
50 .It
51 On all architectures where the stack is non-executable,
52 trampoline code marks the smallest possible area around the trampoline stub
53 executable using
54 .Xr mprotect 2 .
55 .It
56 Trampoline code generation is disabled by default.
57 Code requiring trampolines will not compile without
58 .Fl ftrampolines .
59 The warning flag
60 .Fl Wtrampolines
61 can be used to locate trampoline instances if trampoline generation
62 is re-enabled.
63 .It
64 The
65 .Fl O2
66 option does not include
67 .Fl fstrict-aliasing ,
68 as this option causes issues on some legacy code.
69 .Fl fstrict-aliasing
70 is very unsafe with code that plays tricks with casts, bypassing the
71 already weak type system of C.
72 .It
73 The
74 .Fl O2
75 option does not include
76 .Fl fstrict-overflow ,
77 as this option causes issues on some legacy code.
78 .Fl fstrict-overflow
79 can cause surprising optimizations to occur, possibly deleting security
80 critical overflow checks.
81 .It
82 The
83 .Fl O2
84 option does not include the
85 .Fl ftree-vrp
86 optimization as it is known to be broken in
87 .Nm gcc 4.2.1 .
88 .It
89 The option
90 .Fl fno-builtin-<function>
91 was backported to
92 .Nm gcc 2.95.3 ,
93 and can be used without having to differentiate between
94 compilers.
95 .It
96 .Nm gcc
97 recognizes the extra format attribute syslog, to better match
98 the definition of
99 .Xr syslog 3 ,
100 and silence erroneous warnings when used with
101 .Fl pedantic .
102 .It
103 Even in 2.95.3,
104 .Nm gcc
105 recognizes the attribute
106 .Dv __nonnull__ ,
107 which can be used to mark arguments that can't be
108 .Dv NULL .
109 The printf format attribute does not imply
110 .Dv __nonnull__
111 for the format.
112 This allows for correct format checking on the
113 .Xr err 3
114 function family.
115 .It
116 .Nm gcc
117 recognizes the extra attribute
118 .Dv __sentinel__ ,
119 which can be used to mark varargs function that need a
120 .Dv NULL
121 pointer to mark argument termination, like
122 .Xr execl 3 .
123 This exposes latent bugs for 64-bit architectures,
124 where a terminating 0 will expand to a 32-bit int, and not a full-fledged
125 64-bits pointer.
126 .It
127 On vax,
128 .Nm gcc
129 still uses
130 .Xr setjmp 3 /
131 .Xr longjmp 3 -
132 style exceptions, and so needs extra fixes beyond the pure 2.95.3 release.
133 .Po so-called
134 .Dq sjlj
135 exceptions are also used on aviion, luna88k and mvme88k
136 .Pc
137 .It
138 On a.out platforms (i.e. vax),
139 .Nm gcc
140 uses a linker wrapper to write stubs that call global constructors and
141 destructors.
142 Those platforms use
143 .Nm gcc 2.95.3 ,
144 and those calls can be traced using
145 .Fl Wl,-trace-ctors-dtors ,
146 using
147 .Xr syslog_r 3 .
148 .It
149 On alpha,
150 .Fl mieee
151 is enabled by default to enable full compliance with
152 the IEEE floating point standard,
153 although the
154 .Dq inexact
155 flag is not maintained.
156 Additionally, rounding mode is dynamic.
157 .It
158 .Nm gcc
159 comes with the
160 .Dq ProPolice
161 stack protection extension, which is enabled by default.
162 This extension reorders local variable declarations and adds stack consistency
163 checks at run time, in order to detect stack overflows, and will attempt to
164 report the problem in the system logs by calling
165 .Xr syslog 3
166 with a
167 .Dv LOG_CRIT
168 priority message:
169 .Dq stack overflow in function XXX ,
170 and abort the faulting process.
171 It can be turned off using the
172 .Fl fno-stack-protector
173 commandline option.
174 Note that the stack protector relies on some support code in libc.
175 Stand-alone programs not linked against libc must either provide their own
176 support bits, or use the
177 .Fl fno-stack-protector
178 option.
179 There is also a
180 .Fl fstack-protector-all
181 option, that turns stack protection code on for all functions,
182 and disables any heuristic that flags some functions as safe.
183 This extended checking has a moderate runtime cost, though.
184 .It
185 On the alpha, amd64, hppa, mips64, sh and sparc64 architectures,
186 .Nm gcc
187 generates position-independent executables
188 .Pq PIEs
189 by default, allowing the system to load the resulting binary
190 at a random location.
191 This behavior can be turned off by passing
192 .Fl fno-pie
193 to the compiler and
194 .Fl nopie
195 to the linker.
196 It is not supported for static executables.
197 .It
198 .Nm gcc
199 recognizes a new flag,
200 .Fl Wbounded ,
201 to perform basic checks on functions which accept buffers and sizes.
202 An extra attribute,
203 .Dv __bounded__ ,
204 has been added to mark functions that can be
205 checked this way.
206 .It
207 .Nm gcc
208 recognizes a new format attribute, kprintf, to deal with the extra format
209 arguments
210 .Ql %b ,
211 .Ql %r ,
212 and
213 .Ql %z
214 used in the
215 .Ox
216 kernel.
217 .It
218 .Nm gcc
219 does not store its version string in objects.
220 This behavior can be restored with
221 .Fl fident .
222 .It
223 .Nm gcc
224 will not move variables initialized with the value zero
225 from the data section to the bss section.
226 The default behaviour of
227 .Nm gcc 3.3.6
228 and
229 .Nm gcc 4.2.1
230 on other systems is to perform this action, which can be restored for
231 .Ox
232 with
233 .Fl fzero-initialized-in-bss .
234 .It
235 .Nm gcc
236 does not warn for cast expressions used as lvalues outside of
237 .Fl pedantic .
238 .It
239 .Nm gcc 4.2.1
240 does not warn for pointer arguments passing or assignment with
241 different signedness outside of
242 .Fl pedantic .
243 This can be
244 re-enabled with the
245 .Fl Wpointer-sign
246 flag.
247 .It
248 Even in 2.95.3,
249 .Nm gcc
250 recognizes the preprocessor flag
251 .Fl CC
252 that lets comments in macros pass through to the output (except in
253 .Fl traditional
254 mode).
255 This is used to allow annotations in macros for
256 lint.
257 .It
258 The warning option
259 .Fl Wsystem-headers ,
260 which makes
261 .Nm gcc
262 report warnings in systems headers,
263 is enabled by default.
264 .It
265 .Nm gcc
266 supports two extra warning options:
267 .Bl -item
268 .It
269 .Fl Wstack-larger-than- Ns Va N
270 will report functions using more than
271 .Va N
272 bytes of stack space for their local variables.
273 Stack space used for other purposes (such as register window saving,
274 callee-saved registers, or outbound arguments storage)
275 is not taken into account for this check.
276 .It
277 .Fl Wvariable-decl
278 will report automatic variable declarations whose size cannot be
279 determined at compile-time.
280 .El
281 .El
282 .Sh ATTRIBUTES
283 The
284 .Dv __bounded__
285 attribute is used to type-check functions whose parameters pass fixed-length
286 buffers and their sizes.
287 The syntax for normal buffers is:
288 .Pp
289 .Li __attribute__ ((__bounded__ (
290 .Dv __buffer__ ,
291 .Va buffer ,
292 .Va length
293 .Li )))
294 .Pp
295 where
296 .Fa buffer
297 contains the parameter number (starting from 1) of the pointer to the buffer,
298 and
299 .Fa length
300 contains the parameter number of the buffer length argument.
301 .Pp
302 .Nm gcc
303 will emit a warning if the length argument is a constant larger than the
304 actual size of the buffer.
305 If the buffer is not a statically declared array of fixed length, no warnings
306 will be generated.
307 Refer to
308 .Xr memcpy 3
309 for an example of a function with this check.
310 .Pp
311 For checking strings, just use
312 .Dv __string__
313 instead of
314 .Dv __buffer__ :
315 .Pp
316 .Li __attribute__ ((__bounded__ (
317 .Dv __string__ ,
318 .Va buffer ,
319 .Va length
320 .Li )))
321 .Pp
322 In addition to the checks described above, this also tests if the
323 .Va length
324 argument was wrongly derived from a
325 .Fn sizeof "void *"
326 operation.
327 .Xr strlcpy 3
328 is a good example of a string function with this check.
329 .Pp
330 Some functions specify the length as two arguments:
331 the number of elements and the size of each element.
332 In this case, use the
333 .Dv __size__
334 attribute:
335 .Pp
336 .Li __attribute__ ((__bounded__ (
337 .Dv __size__ ,
338 .Va buffer ,
339 .Va nmemb ,
340 .Va size
341 .Li )))
342 .Pp
343 where
344 .Va buffer
345 contains the parameter number of the pointer to the buffer,
346 .Va nmemb
347 contains the parameter number of the number of members, and
348 .Va size
349 has the parameter number of the size of each element.
350 The type checks performed by
351 .Dv __size__
352 are the same as the
353 .Dv __buffer__
354 attribute.
355 See
356 .Xr fread 3
357 for an example of this type of function.
358 .Pp
359 If a function accepts a buffer parameter and specifies that it has to be of a
360 minimum length, the __minbytes__ attribute can be used:
361 .Pp
362 .Li __attribute__ ((__bounded__ (
363 .Dv __minbytes__ ,
364 .Va buffer ,
365 .Va minsize
366 .Li )))
367 .Pp
368 where
369 .Va buffer
370 contains the parameter number of the pointer to the buffer, and
371 .Va minsize
372 specifies the minimum number of bytes that the buffer should be.
373 .Xr ctime_r 3
374 is an example of this type of function.
375 .Pp
376 If
377 .Fl Wbounded
378 is specified with
379 .Fl Wformat ,
380 additional checks are performed on
381 .Xr sscanf 3
382 format strings.
383 The
384 .Ql %s
385 fields are checked for incorrect bound lengths by checking the size of the
386 buffer associated with the format argument.
387 .Sh SEE ALSO
388 .Xr gcc 1
389 .Pp
390 .Lk http://www.research.ibm.com/trl/projects/security/ssp/
391 .Sh CAVEATS
392 The
393 .Fl Wbounded
394 flag only works with statically allocated fixed-size buffers.
395 Since it is applied at compile-time, dynamically allocated memory buffers
396 and non-constant arguments are ignored.