Return to __builtin_object_size.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / ssp

Annotation of src/lib/libc/ssp/__builtin_object_size.3, Revision 1.11

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