1.\" $OpenBSD: gcc-local.1,v 1.48 2016/03/14 03:01:48 mmcc 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: March 14 2016 $ 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 36uses derivatives of 37.Xr gcc 1 38versions 3.3.6 or 4.2.1, 39depending on machine architecture. 40In all cases, 41the software comes with specific modifications for 42.Ox : 43.Bl -dash 44.It 45.Nm gcc 46does not search under 47.Pa /usr/local 48for include files nor for libraries: 49as a system compiler, it only searches the system paths by default. 50.It 51On all architectures where the stack is non-executable, 52trampoline code marks the smallest possible area around the trampoline stub 53executable using 54.Xr mprotect 2 . 55.It 56Trampoline code generation is disabled by default. 57Code requiring trampolines will not compile without 58.Fl ftrampolines . 59The warning flag 60.Fl Wtrampolines 61can be used to locate trampoline instances if trampoline generation 62is re-enabled. 63.It 64The 65.Fl O2 66option does not include 67.Fl fstrict-aliasing , 68as this option causes issues on some legacy code. 69.Fl fstrict-aliasing 70is very unsafe with code that plays tricks with casts, bypassing the 71already weak type system of C. 72.It 73The 74.Fl O2 75option does not include 76.Fl fstrict-overflow , 77as this option causes issues on some legacy code. 78.Fl fstrict-overflow 79can cause surprising optimizations to occur, possibly deleting security 80critical overflow checks. 81.It 82The 83.Fl O2 84option does not include the 85.Fl ftree-vrp 86optimization as it is known to be broken in 87.Nm gcc 4.2.1 . 88.It 89.Nm gcc 90recognizes the extra format attribute syslog, to better match 91the definition of 92.Xr syslog 3 , 93and silence erroneous warnings when used with 94.Fl pedantic . 95.It 96.Nm gcc 97recognizes the attribute 98.Dv __nonnull__ , 99which can be used to mark arguments that can't be 100.Dv NULL . 101The printf format attribute does not imply 102.Dv __nonnull__ 103for the format. 104This allows for correct format checking on the 105.Xr err 3 106function family. 107.It 108.Nm gcc 109recognizes the extra attribute 110.Dv __sentinel__ , 111which can be used to mark varargs function that need a 112.Dv NULL 113pointer to mark argument termination, like 114.Xr execl 3 . 115This exposes latent bugs for 64-bit architectures, 116where a terminating 0 will expand to a 32-bit int, and not a full-fledged 11764-bits pointer. 118.It 119On alpha, 120.Fl mieee 121is enabled by default to enable full compliance with 122the IEEE floating point standard, 123although the 124.Dq inexact 125flag is not maintained. 126Additionally, rounding mode is dynamic. 127.It 128.Nm gcc 129comes with the 130.Dq ProPolice 131stack protection extension, which is enabled by default. 132This extension reorders local variable declarations and adds stack consistency 133checks at runtime, in order to detect stack overflows, and will attempt to 134report the problem in the system logs by calling 135.Xr syslog 3 136with a 137.Dv LOG_CRIT 138priority message: 139.Dq stack overflow in function XXX , 140and abort the faulting process. 141It can be turned off using the 142.Fl fno-stack-protector 143command line option. 144Note that the stack protector relies on some support code in libc. 145Stand-alone programs not linked against libc must either provide their own 146support bits or use the 147.Fl fno-stack-protector 148option. 149.Pp 150There is a 151.Fl fstack-protector-all 152option that turns stack protection code on for all functions 153and disables any heuristic that flags some functions as safe. 154This extended checking has a moderate runtime cost though. 155There is a 156.Fl fstack-protector-strong 157option, similar to 158.Fl fstack-protector , 159which includes additional functions to be protected \(em those that 160have local array definitions 161or have references to local frame addresses. 162.It 163On the alpha, amd64, hppa, i386, mips64, powerpc, sh and sparc64 164architectures, 165.Nm gcc 166generates position-independent executables 167.Pq PIEs 168by default, allowing the system to load the resulting binary 169at a random location. 170This behavior can be turned off by passing 171.Fl fno-pie 172to the compiler and 173.Fl nopie 174to the linker. 175.It 176.Nm gcc 177recognizes a new flag which is enabled by default, 178.Fl Wbounded , 179to perform basic checks on functions which accept buffers and sizes. 180An extra attribute, 181.Dv __bounded__ , 182has been added to mark functions that can be 183checked this way. 184.It 185.Nm gcc 186recognizes a new format attribute, kprintf, to deal with the extra format 187arguments 188.Ql %b , 189.Ql %r , 190and 191.Ql %z 192used in the 193.Ox 194kernel. 195.It 196.Nm gcc 197does not store its version string in objects. 198This behavior can be restored with 199.Fl fident . 200.It 201The option 202.Fl fstack-shuffle 203will randomize the order of stack variables at compile time with 204.Nm gcc 4.2.1 , 205which can be helpful to find bugs. 206This option is silently ignored by 207.Nm gcc 3.3.6 . 208.It 209.Nm gcc 210will not move variables initialized with the value zero 211from the data section to the bss section. 212The default behaviour of 213.Nm gcc 3.3.6 214and 215.Nm gcc 4.2.1 216on other systems is to perform this action, which can be restored for 217.Ox 218with 219.Fl fzero-initialized-in-bss . 220.It 221.Nm gcc 222does not warn for cast expressions used as lvalues outside of 223.Fl pedantic . 224.It 225.Nm gcc 4.2.1 226does not warn for pointer arguments passing or assignment with 227different signedness outside of 228.Fl pedantic . 229This can be 230re-enabled with the 231.Fl Wpointer-sign 232flag. 233.It 234.Nm gcc 235recognizes the preprocessor flag 236.Fl CC 237that lets comments in macros pass through to the output (except in 238.Fl traditional 239mode). 240.It 241The warning option 242.Fl Wsystem-headers , 243which makes 244.Nm gcc 245report warnings in systems headers, 246is enabled by default. 247.It 248.Nm gcc 249supports two extra warning options: 250.Bl -item 251.It 252.Fl Wframe-larger-than= Ns Va N 253.Po 254and its non-portable alias 255.Fl Wstack-larger-than- Ns Va N 256.Pc 257will report functions using more than 258.Va N 259bytes of stack space for their local variables. 260Stack space used for other purposes (such as register window saving, 261callee-saved registers, or outbound arguments storage) 262is not taken into account for this check. 263.It 264.Fl Wvariable-decl 265will report automatic variable declarations whose size cannot be 266determined at compile-time. 267.El 268.It 269.Nm gcc 4.2.1 270and 271.Nm gcc 3.3.6 272have backported support for the GCC binary integer constants extension, 273which was first introduced in 274.Nm gcc 4.3 . 275.El 276.Sh ATTRIBUTES 277The 278.Dv __bounded__ 279attribute is used to type-check functions whose parameters pass fixed-length 280buffers and their sizes. 281The syntax for normal buffers is: 282.Pp 283.Li __attribute__ ((__bounded__ ( 284.Dv __buffer__ , 285.Va buffer , 286.Va length 287.Li ))) 288.Pp 289where 290.Fa buffer 291contains the parameter number (starting from 1) of the pointer to the buffer, 292and 293.Fa length 294contains the parameter number of the buffer length argument. 295.Pp 296.Nm gcc 297will emit a warning if the length argument is a constant larger than the 298actual size of the buffer. 299If the buffer is not a statically declared array of fixed length, no warnings 300will be generated. 301Refer to 302.Xr memcpy 3 303for an example of a function with this check. 304.Pp 305For checking strings, just use 306.Dv __string__ 307instead of 308.Dv __buffer__ : 309.Pp 310.Li __attribute__ ((__bounded__ ( 311.Dv __string__ , 312.Va buffer , 313.Va length 314.Li ))) 315.Pp 316In addition to the checks described above, this also tests if the 317.Va length 318argument was wrongly derived from a 319.Fn sizeof "void *" 320operation. 321.Xr strlcpy 3 322is a good example of a string function with this check. 323.Pp 324If a function needs string checking like 325.Dv __string__ 326but operates on element counts rather than buffer sizes, use 327.Dv __wcstring__ : 328.Pp 329.Li __attribute__ ((__bounded__ ( 330.Dv __wcstring__ , 331.Va buffer , 332.Va count 333.Li ))) 334.Pp 335An example of a string function with this check is 336.Xr wcslcpy 3 . 337.Pp 338Some functions specify the length as two arguments: 339the number of elements and the size of each element. 340In this case, use the 341.Dv __size__ 342attribute: 343.Pp 344.Li __attribute__ ((__bounded__ ( 345.Dv __size__ , 346.Va buffer , 347.Va nmemb , 348.Va size 349.Li ))) 350.Pp 351where 352.Va buffer 353contains the parameter number of the pointer to the buffer, 354.Va nmemb 355contains the parameter number of the number of members, and 356.Va size 357has the parameter number of the size of each element. 358The type checks performed by 359.Dv __size__ 360are the same as the 361.Dv __buffer__ 362attribute. 363See 364.Xr fread 3 365for an example of this type of function. 366.Pp 367If a function accepts a buffer parameter and specifies that it has to be of a 368minimum length, the __minbytes__ attribute can be used: 369.Pp 370.Li __attribute__ ((__bounded__ ( 371.Dv __minbytes__ , 372.Va buffer , 373.Va minsize 374.Li ))) 375.Pp 376where 377.Va buffer 378contains the parameter number of the pointer to the buffer, and 379.Va minsize 380specifies the minimum number of bytes that the buffer should be. 381.Xr ctime_r 3 382is an example of this type of function. 383.Pp 384If 385.Fl Wbounded 386is specified with 387.Fl Wformat , 388additional checks are performed on 389.Xr sscanf 3 390format strings. 391The 392.Ql %s 393fields are checked for incorrect bound lengths by checking the size of the 394buffer associated with the format argument. 395.Sh SEE ALSO 396.Xr gcc 1 397.Pp 398.Lk http://www.research.ibm.com/trl/projects/security/ssp/ 399.Sh CAVEATS 400The 401.Fl Wbounded 402flag only works with statically allocated fixed-size buffers. 403Since it is applied at compile-time, dynamically allocated memory buffers 404and non-constant arguments are ignored. 405