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