1.\" $OpenBSD: gcc-local.1,v 1.18 2008/06/10 13:12:43 merdely 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: June 10 2008 $ 29.Dt GCC-LOCAL 1 30.Os 31.Sh NAME 32.Nm gcc-local 33.Nd local modifications to gcc 34.Sh DESCRIPTION 35Some 36.Ox 37platforms use a derivative of 38.Nm gcc 2.95.3 , 39others use a derivative of 40.Nm gcc 3.3.5 . 41In both cases, 42the 43.Nm gcc 44software comes with specific modifications for 45.Ox . 46.Bl -dash 47.It 48.Nm gcc 49does not search under 50.Pa /usr/local 51for include files nor for libraries: 52as a system compiler, it only searches the system paths by default. 53.It 54On 55.Ox , 56the 57.Fl pthread 58option should be used to link threaded code, isolating the program from 59operating system details. 60.It 61On most architectures, 62trampoline code marks the smallest possible area around the trampoline stub 63executable using 64.Xr mprotect 2 , 65since the stack area is by default non-executable. 66.It 67On 68.Ox , 69by default, trampoline code generation is disabled. 70Code requiring trampolines will not compile without 71.Fl ftrampolines . 72The warning flag 73.Fl Wtrampolines 74can be used to locate trampoline instances if trampoline generation 75is re-enabled. 76.It 77The 78.Fl O2 79option does not include 80.Fl fstrict-aliasing , 81as this option causes issues on some legacy code. 82.Fl fstrict-aliasing 83is very unsafe with code that plays tricks with casts, bypassing the 84already weak type system of C. 85.It 86The option 87.Fl fno-builtin-<function> 88was backported from 89.Nm gcc 3.3.5 , 90to 91.Nm gcc 2.95.3 , 92and can be used without having to differentiate between 93both compilers. 94.It 95.Nm gcc 96recognizes the extra format attribute syslog, to better match 97the definition of 98.Xr syslog 3 , 99and silence erroneous warnings when used with 100.Fl pedantic . 101.It 102Even in 2.95.3, 103.Nm gcc 104recognizes the attribute 105.Dv __nonnull__ , 106which can be used to mark arguments that can't be 107.Dv NULL . 108The printf format attribute does not imply 109.Dv __nonnull__ 110for the format. 111This allows for correct format checking on the 112.Xr err 3 113function family. 114.It 115.Nm gcc 116recognizes the extra attribute 117.Dv __sentinel__ , 118which can be used to mark varargs function that need a 119.Dv NULL 120pointer to mark argument termination, like 121.Xr execl 3 . 122This exposes latent bugs for 64-bit architectures, 123where a terminating 0 will expand to a 32-bit int, and not a full-fledged 12464-bits pointer. 125.It 126On some 127.Ox 128platforms, 129.Nm gcc 130still uses 131.Xr setjmp 3 / 132.Xr longjmp 3 - 133style exceptions, and so needs extra fixes beyond the pure 2.95.3 release. 134.It 135On a few 136platforms (mostly a.out), 137.Nm gcc 138uses a linker wrapper to write stubs that call global constructors and 139destructors. 140Those platforms use 141.Nm gcc 2.95.3 , 142and those calls can be traced using 143.Fl Wl,-trace-ctors-dtors , 144using 145.Xr syslog_r 3 . 146.It 147On alpha, 148.Fl mieee 149is enabled by default to enable full compliance with 150the IEEE floating point standard. 151.It 152On 153.Ox , 154.Nm gcc 155comes with the 156.Dq ProPolice 157stack protection extension, which is enabled by default. 158This extension reorders local variable declarations and adds stack consistency 159checks at run time, in order to detect stack overflows, and will attempt to 160report the problem in the system logs by calling 161.Xr syslog 3 162with a 163.Dv LOG_CRIT 164priority message: 165.Dq stack overflow in function XXX , 166and abort the faulting process. 167It can be turned off using the 168.Fl fno-stack-protector 169commandline option. 170Note that the stack protector relies on some support code in libc. 171Stand-alone programs not linked against libc must either provide their own 172support bits, or use the 173.Fl fno-stack-protector 174option. 175There is also a 176.Fl fstack-protector-all 177option, that turns stack protection code on for all functions, 178and disables any heuristic that flags some functions as safe. 179This extended checking has a moderate runtime cost, though. 180.It 181.Nm gcc 182recognizes a new flag, 183.Fl Wbounded , 184to perform basic checks on functions which accept buffers and sizes. 185An extra attribute, 186.Dv __bounded__ , 187has been added to mark functions that can be 188checked this way. 189.It 190.Nm gcc 191recognizes a new format attribute, kprintf, to deal with the extra format 192arguments 193.Ql %b , 194.Ql %r , 195and 196.Ql %z 197used in the 198.Ox 199kernel. 200.It 201.Nm gcc 202does not store its version string in objects. 203This behavior can be restored with 204.Fl fident . 205.It 206On 207.Ox , 208.Nm gcc 209will not move variables initialized with the value zero 210from the data section to the bss section. 211The default behaviour of 212.Nm gcc 3.3.5 213on other systems is to perform this action, which can be restored for 214.Ox 215with 216.Fl fzero-initialized-in-bss . 217.It 218On 219.Ox , 220.Nm gcc 221does not warn for cast expressions used as lvalues outside of 222.Fl pedantic . 223.It 224Even in 2.95.3, 225.Nm gcc 226recognizes the preprocessor flag 227.Fl CC 228that lets comments in macros pass through to the output (except in 229.Fl traditional 230mode). 231This is used to allow annotations in macros for 232.Xr lint 1 . 233.It 234On 235.Ox , 236.Nm gcc 237supports two extra warning options: 238.Bl -item 239.It 240.Fl Wstack-larger-than- Ns Va N 241will report functions using more than 242.Va N 243bytes of stack space for their local variables. 244Stack space used for other purposes (such as register window saving, 245callee-saved registers, or outbound arguments storage) 246is not taken into account for this check. 247.It 248.Fl Wvariable-decl 249will report automatic variable declarations whose size cannot be 250determined at compile-time. 251.El 252.El 253.Sh ATTRIBUTES 254The 255.Dv __bounded__ 256attribute is used to type-check functions whose parameters pass fixed-length 257buffers and their sizes. 258The syntax for normal buffers is: 259.Pp 260.Li __attribute__ ((__bounded__ ( 261.Dv __buffer__ , 262.Va buffer , 263.Va length 264.Li ))) 265.Pp 266where 267.Fa buffer 268contains the parameter number (starting from 1) of the pointer to the buffer, 269and 270.Fa length 271contains the parameter number of the buffer length argument. 272.Pp 273.Nm gcc 274will emit a warning if the length argument is a constant larger than the 275actual size of the buffer. 276If the buffer is not a statically declared array of fixed length, no warnings 277will be generated. 278Refer to 279.Xr memcpy 3 280for an example of a function with this check. 281.Pp 282For checking strings, just use 283.Dv __string__ 284instead of 285.Dv __buffer__ : 286.Pp 287.Li __attribute__ ((__bounded__ ( 288.Dv __string__ , 289.Va buffer , 290.Va length 291.Li ))) 292.Pp 293In addition to the checks described above, this also tests if the 294.Va length 295argument was wrongly derived from a 296.Fn sizeof "void *" 297operation. 298.Xr strlcpy 3 299is a good example of a string function with this check. 300.Pp 301Some functions specify the length as two arguments: 302the number of elements and the size of each element. 303In this case, use the 304.Dv __size__ 305attribute: 306.Pp 307.Li __attribute__ ((__bounded__ ( 308.Dv __size__ , 309.Va buffer , 310.Va nmemb , 311.Va size 312.Li ))) 313.Pp 314where 315.Va buffer 316contains the parameter number of the pointer to the buffer, 317.Va nmemb 318contains the parameter number of the number of members, and 319.Va size 320has the parameter number of the size of each element. 321The type checks performed by 322.Dv __size__ 323are the same as the 324.Dv __buffer__ 325attribute. 326See 327.Xr fread 3 328for an example of this type of function. 329.Pp 330If a function accepts a buffer parameter and specifies that it has to be of a 331minimum length, the __minbytes__ attribute can be used: 332.Pp 333.Li __attribute__ ((__bounded__ ( 334.Dv __minbytes__ , 335.Va buffer , 336.Va minsize 337.Li ))) 338.Pp 339where 340.Va buffer 341contains the parameter number of the pointer to the buffer, and 342.Va minsize 343specifies the minimum number of bytes that the buffer should be. 344.Xr ctime_r 3 345is an example of this type of function. 346.Pp 347If 348.Fl Wbounded 349is specified with 350.Fl Wformat , 351additional checks are performed on 352.Xr sscanf 3 353format strings. 354The 355.Ql %s 356fields are checked for incorrect bound lengths by checking the size of the 357buffer associated with the format argument. 358.Sh SEE ALSO 359.Xr gcc 1 360.Pp 361.Pa http://www.research.ibm.com/trl/projects/security/ssp/ 362.Sh CAVEATS 363The 364.Fl Wbounded 365flag only works with statically allocated fixed-size buffers. 366Since it is applied at compile-time, dynamically allocated memory buffers 367and non-constant arguments are ignored. 368