1.\" $OpenBSD: gcc-local.1,v 1.43 2014/07/10 19:14:40 matthew 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: July 10 2014 $ 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 143commandline 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. 175It is not supported for static executables. 176.It 177.Nm gcc 178recognizes a new flag which is enabled by default, 179.Fl Wbounded , 180to perform basic checks on functions which accept buffers and sizes. 181An extra attribute, 182.Dv __bounded__ , 183has been added to mark functions that can be 184checked this way. 185.It 186.Nm gcc 187recognizes a new format attribute, kprintf, to deal with the extra format 188arguments 189.Ql %b , 190.Ql %r , 191and 192.Ql %z 193used in the 194.Ox 195kernel. 196.It 197.Nm gcc 198does not store its version string in objects. 199This behavior can be restored with 200.Fl fident . 201.It 202.Nm gcc 203will not move variables initialized with the value zero 204from the data section to the bss section. 205The default behaviour of 206.Nm gcc 3.3.6 207and 208.Nm gcc 4.2.1 209on other systems is to perform this action, which can be restored for 210.Ox 211with 212.Fl fzero-initialized-in-bss . 213.It 214.Nm gcc 215does not warn for cast expressions used as lvalues outside of 216.Fl pedantic . 217.It 218.Nm gcc 4.2.1 219does not warn for pointer arguments passing or assignment with 220different signedness outside of 221.Fl pedantic . 222This can be 223re-enabled with the 224.Fl Wpointer-sign 225flag. 226.It 227.Nm gcc 228recognizes the preprocessor flag 229.Fl CC 230that lets comments in macros pass through to the output (except in 231.Fl traditional 232mode). 233This is used to allow annotations in macros for 234lint. 235.It 236The warning option 237.Fl Wsystem-headers , 238which makes 239.Nm gcc 240report warnings in systems headers, 241is enabled by default. 242.It 243.Nm gcc 244supports two extra warning options: 245.Bl -item 246.It 247.Fl Wframe-larger-than= Ns Va N 248.Po 249and its non-portable alias 250.Fl Wstack-larger-than- Ns Va N 251.Pc 252will report functions using more than 253.Va N 254bytes of stack space for their local variables. 255Stack space used for other purposes (such as register window saving, 256callee-saved registers, or outbound arguments storage) 257is not taken into account for this check. 258.It 259.Fl Wvariable-decl 260will report automatic variable declarations whose size cannot be 261determined at compile-time. 262.El 263.It 264.Nm gcc 4.2.1 265and 266.Nm gcc 3.3.6 267have backported support for the GCC binary integer constants extension, 268which was first introduced in 269.Nm gcc 4.3 . 270.El 271.Sh ATTRIBUTES 272The 273.Dv __bounded__ 274attribute is used to type-check functions whose parameters pass fixed-length 275buffers and their sizes. 276The syntax for normal buffers is: 277.Pp 278.Li __attribute__ ((__bounded__ ( 279.Dv __buffer__ , 280.Va buffer , 281.Va length 282.Li ))) 283.Pp 284where 285.Fa buffer 286contains the parameter number (starting from 1) of the pointer to the buffer, 287and 288.Fa length 289contains the parameter number of the buffer length argument. 290.Pp 291.Nm gcc 292will emit a warning if the length argument is a constant larger than the 293actual size of the buffer. 294If the buffer is not a statically declared array of fixed length, no warnings 295will be generated. 296Refer to 297.Xr memcpy 3 298for an example of a function with this check. 299.Pp 300For checking strings, just use 301.Dv __string__ 302instead of 303.Dv __buffer__ : 304.Pp 305.Li __attribute__ ((__bounded__ ( 306.Dv __string__ , 307.Va buffer , 308.Va length 309.Li ))) 310.Pp 311In addition to the checks described above, this also tests if the 312.Va length 313argument was wrongly derived from a 314.Fn sizeof "void *" 315operation. 316.Xr strlcpy 3 317is a good example of a string function with this check. 318.Pp 319If a function needs string checking like 320.Dv __string__ 321but operates on element counts rather than buffer sizes, use 322.Dv __wcstring__ : 323.Pp 324.Li __attribute__ ((__bounded__ ( 325.Dv __wcstring__ , 326.Va buffer , 327.Va count 328.Li ))) 329.Pp 330An example of a string function with this check is 331.Xr wcslcpy 3 . 332.Pp 333Some functions specify the length as two arguments: 334the number of elements and the size of each element. 335In this case, use the 336.Dv __size__ 337attribute: 338.Pp 339.Li __attribute__ ((__bounded__ ( 340.Dv __size__ , 341.Va buffer , 342.Va nmemb , 343.Va size 344.Li ))) 345.Pp 346where 347.Va buffer 348contains the parameter number of the pointer to the buffer, 349.Va nmemb 350contains the parameter number of the number of members, and 351.Va size 352has the parameter number of the size of each element. 353The type checks performed by 354.Dv __size__ 355are the same as the 356.Dv __buffer__ 357attribute. 358See 359.Xr fread 3 360for an example of this type of function. 361.Pp 362If a function accepts a buffer parameter and specifies that it has to be of a 363minimum length, the __minbytes__ attribute can be used: 364.Pp 365.Li __attribute__ ((__bounded__ ( 366.Dv __minbytes__ , 367.Va buffer , 368.Va minsize 369.Li ))) 370.Pp 371where 372.Va buffer 373contains the parameter number of the pointer to the buffer, and 374.Va minsize 375specifies the minimum number of bytes that the buffer should be. 376.Xr ctime_r 3 377is an example of this type of function. 378.Pp 379If 380.Fl Wbounded 381is specified with 382.Fl Wformat , 383additional checks are performed on 384.Xr sscanf 3 385format strings. 386The 387.Ql %s 388fields are checked for incorrect bound lengths by checking the size of the 389buffer associated with the format argument. 390.Sh SEE ALSO 391.Xr gcc 1 392.Pp 393.Lk http://www.research.ibm.com/trl/projects/security/ssp/ 394.Sh CAVEATS 395The 396.Fl Wbounded 397flag only works with statically allocated fixed-size buffers. 398Since it is applied at compile-time, dynamically allocated memory buffers 399and non-constant arguments are ignored. 400