1*be04fec4SKyle Evans.\" $NetBSD: __builtin_object_size.3,v 1.11 2017/07/03 21:32:49 wiz Exp $ 2*be04fec4SKyle Evans.\" 3*be04fec4SKyle Evans.\" SPDX-License-Identifier: BSD-2-Clause 4*be04fec4SKyle Evans.\" 5*be04fec4SKyle Evans.\" Copyright (c) 2007 The NetBSD Foundation, Inc. 6*be04fec4SKyle Evans.\" All rights reserved. 7*be04fec4SKyle Evans.\" 8*be04fec4SKyle Evans.\" This code is derived from software contributed to The NetBSD Foundation 9*be04fec4SKyle Evans.\" by Christos Zoulas. 10*be04fec4SKyle Evans.\" 11*be04fec4SKyle Evans.\" Redistribution and use in source and binary forms, with or without 12*be04fec4SKyle Evans.\" modification, are permitted provided that the following conditions 13*be04fec4SKyle Evans.\" are met: 14*be04fec4SKyle Evans.\" 1. Redistributions of source code must retain the above copyright 15*be04fec4SKyle Evans.\" notice, this list of conditions and the following disclaimer. 16*be04fec4SKyle Evans.\" 2. Redistributions in binary form must reproduce the above copyright 17*be04fec4SKyle Evans.\" notice, this list of conditions and the following disclaimer in the 18*be04fec4SKyle Evans.\" documentation and/or other materials provided with the distribution. 19*be04fec4SKyle Evans.\" 20*be04fec4SKyle Evans.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 21*be04fec4SKyle Evans.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22*be04fec4SKyle Evans.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23*be04fec4SKyle Evans.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 24*be04fec4SKyle Evans.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25*be04fec4SKyle Evans.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26*be04fec4SKyle Evans.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27*be04fec4SKyle Evans.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28*be04fec4SKyle Evans.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29*be04fec4SKyle Evans.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30*be04fec4SKyle Evans.\" POSSIBILITY OF SUCH DAMAGE. 31*be04fec4SKyle Evans.\" 32*be04fec4SKyle Evans.\" 33*be04fec4SKyle Evans.Dd April 27, 2024 34*be04fec4SKyle Evans.Dt __BUILTIN_OBJECT_SIZE 3 35*be04fec4SKyle Evans.Os 36*be04fec4SKyle Evans.Sh NAME 37*be04fec4SKyle Evans.Nm __builtin_object_size 38*be04fec4SKyle Evans.Nd return the size of the given object 39*be04fec4SKyle Evans.Sh SYNOPSIS 40*be04fec4SKyle Evans.Ft size_t 41*be04fec4SKyle Evans.Fn __builtin_object_size "void *ptr" "int type" 42*be04fec4SKyle Evans.Sh DESCRIPTION 43*be04fec4SKyle EvansThe 44*be04fec4SKyle Evans.Fn __builtin_object_size 45*be04fec4SKyle Evansfunction is a 46*be04fec4SKyle Evans.Xr clang 1 47*be04fec4SKyle Evansand 48*be04fec4SKyle Evans.Xr gcc 1 49*be04fec4SKyle Evansbuilt-in function that returns the size of the object referenced by 50*be04fec4SKyle Evans.Fa ptr 51*be04fec4SKyle Evansif known at compile time. 52*be04fec4SKyle EvansIf the 53*be04fec4SKyle Evans.Fa ptr 54*be04fec4SKyle Evansexpression has any side effects, then they will not be evaluated. 55*be04fec4SKyle Evans.Sh RETURN VALUES 56*be04fec4SKyle EvansIf the size of the object is not known or the 57*be04fec4SKyle Evans.Fa ptr 58*be04fec4SKyle Evansexpression has side effects, the 59*be04fec4SKyle Evans.Fn __builtin_object_size 60*be04fec4SKyle Evansfunction returns: 61*be04fec4SKyle Evans.Bl -tag -width (size_t)\-1 -offset indent 62*be04fec4SKyle Evans.It Dv (size_t)\-1 63*be04fec4SKyle Evansfor 64*be04fec4SKyle Evans.Fa type 65*be04fec4SKyle Evans.Dv 0 66*be04fec4SKyle Evansand 67*be04fec4SKyle Evans.Dv 1 . 68*be04fec4SKyle Evans.It Dv (size_t)0 69*be04fec4SKyle Evansfor 70*be04fec4SKyle Evans.Fa type 71*be04fec4SKyle Evans.Dv 2 72*be04fec4SKyle Evansand 73*be04fec4SKyle Evans.Dv 3 . 74*be04fec4SKyle Evans.El 75*be04fec4SKyle Evans.Pp 76*be04fec4SKyle EvansIf the size of the object is known, then the 77*be04fec4SKyle Evans.Fn __builtin_object_size 78*be04fec4SKyle Evansfunction returns the maximum size of all the objects that the compiler 79*be04fec4SKyle Evansknows can be pointed to by 80*be04fec4SKyle Evans.Fa ptr 81*be04fec4SKyle Evanswhen 82*be04fec4SKyle Evans.Fa type 83*be04fec4SKyle Evans.Dv & 2 == 0 , 84*be04fec4SKyle Evansand the minimum size when 85*be04fec4SKyle Evans.Fa type 86*be04fec4SKyle Evans.Dv & 2 != 0 . 87*be04fec4SKyle Evans.Sh SEE ALSO 88*be04fec4SKyle Evans.Xr clang 1 , 89*be04fec4SKyle Evans.Xr gcc 1 , 90*be04fec4SKyle Evans.Xr __builtin_return_address 3 , 91*be04fec4SKyle Evans.Xr attribute 3 , 92*be04fec4SKyle Evans.Xr ssp 3 93*be04fec4SKyle Evans.Sh HISTORY 94*be04fec4SKyle EvansThe 95*be04fec4SKyle Evans.Fn __builtin_object_size 96*be04fec4SKyle Evansappeared in 97*be04fec4SKyle Evans.Tn GCC 4.1 . 98*be04fec4SKyle Evans.Sh CAVEATS 99*be04fec4SKyle EvansThis is a non-standard, compiler-specific extension. 100*be04fec4SKyle Evans.Pp 101*be04fec4SKyle EvansNote that currently the object size calculation pass is only done at -O1 102*be04fec4SKyle Evansor above, meaning that this function always returns \-1 when the optimizer 103*be04fec4SKyle Evansis off. 104*be04fec4SKyle Evans.Pp 105*be04fec4SKyle EvansThere are some discussions about always doing the object size pass, but 106*be04fec4SKyle Evansthe issue is that without the optimization pass data sizes are not going 107*be04fec4SKyle Evansto be correct. 108*be04fec4SKyle Evans.Pp 109*be04fec4SKyle EvansFor that reason code fortification (size-checked replacement 110*be04fec4SKyle Evansfunctions) is currently disabled when optimization is off. 111