Changeset View
Standalone View
lib/libc/secure/__builtin_object_size.3
- This file was added.
.\" $NetBSD: __builtin_object_size.3,v 1.10 2012/07/19 06:44:12 wiz Exp $ | |||||
.\" | |||||
.\" Copyright (c) 2007 The NetBSD Foundation, Inc. | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" This code is derived from software contributed to The NetBSD Foundation | |||||
.\" by Christos Zoulas. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS | |||||
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED | |||||
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |||||
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS | |||||
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |||||
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |||||
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |||||
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |||||
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |||||
.\" POSSIBILITY OF SUCH DAMAGE. | |||||
.\" | |||||
.\" | |||||
.Dd July 18, 2012 | |||||
.Dt __BUILTIN_OBJECT_SIZE 3 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm __builtin_object_size | |||||
.Nd return the size of the given object | |||||
.Sh SYNOPSIS | |||||
.Ft size_t | |||||
.Fn __builtin_object_size "void *ptr" "int type" | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Fn __builtin_object_size | |||||
function is a | |||||
.Xr gcc 1 | |||||
built-in function that returns the size of the | |||||
.Fa ptr | |||||
object if known at compile time and the object does not have any side | |||||
effects. | |||||
kib: What does it mean that the object does not have any side effects ? Is this a typo ? Or does it… | |||||
.Sh RETURN VALUES | |||||
If the size of the object is not known or it has side effects the | |||||
.Fn __builtin_object_size | |||||
Not Done Inline Actionsthe "side effects" concept is surely vague: this manpage comes from NetBSD and it looks like it came from the GCC documentation: https://gcc.gnu.org/onlinedocs/gcc/Object-Size-Checking.html It doesn't really make sense for us to document compiler features. It is preferable to create a new fortify_source(7) man page explaining the effect of -D_FORTIFY_SOURCE. pfg: the "side effects" concept is surely vague: this manpage comes from NetBSD and it looks like it… | |||||
Not Done Inline ActionsI think "side effects" are things like function calls and writes to variables in the ptr expression. However, I think this manual page documenting a pure compiler feature should not be added. jilles: I think "side effects" are things like function calls and writes to variables in the `ptr`… | |||||
Not Done Inline ActionsI have been rethinking this and documenting __builtin_object_size only makes sense if we document the difference between GCC and clang. Of course this is to be done in the context of a wider fortify_source documentation. pfg: I have been rethinking this and documenting `__builtin_object_size` only makes sense if we… | |||||
function returns: | |||||
.Bl -tag -width (size_t)\-1 -offset indent | |||||
.It Dv (size_t)\-1 | |||||
for | |||||
.Fa type | |||||
.Dv 0 | |||||
and | |||||
.Dv 1 . | |||||
.It Dv (size_t)0 | |||||
for | |||||
.Fa type | |||||
.Dv 2 | |||||
and | |||||
.Dv 3 . | |||||
.El | |||||
.Pp | |||||
If the size of the object is known, then the | |||||
.Fn __builtin_object_size | |||||
function returns the maximum size of all the objects that the compiler | |||||
knows that they can be pointed to by | |||||
.Fa ptr | |||||
when | |||||
.Fa type | |||||
.Dv \*[Am] 2 == 0 , | |||||
and the minimum size when | |||||
.Fa type | |||||
.Dv \*[Am] 2 != 0 . | |||||
.Sh SEE ALSO | |||||
.Xr gcc 1 , | |||||
.Xr __builtin_return_address 3 , | |||||
.Xr attribute 3 , | |||||
.Xr ssp 3 | |||||
.Sh HISTORY | |||||
The | |||||
.Fn __builtin_object_size | |||||
appeared in | |||||
.Tn GCC 4.1 . | |||||
.Sh CAVEATS | |||||
This is a non-standard, compiler-specific extension. | |||||
.Pp | |||||
Note that currently the object size calculation pass is only done at -O1 | |||||
or above, meaning that this function always returns \-1 when the optimizer | |||||
is off. | |||||
.Pp | |||||
There are some discussions about always doing the object size pass, but | |||||
the issue is that without the optimization pass data sizes are not going | |||||
to be correct. | |||||
.Pp | |||||
For that reason currently code fortification (size-checked replacement | |||||
functions) is disabled when optimization is off. |
What does it mean that the object does not have any side effects ? Is this a typo ? Or does it indeed means that the object must be PDO (doubt it) ?