diff --git a/sizeof.7 b/sizeof.7 --- /dev/null +++ b/sizeof.7 @@ -0,0 +1,299 @@ +.\" +.\" Copyright (C) 2022 Jan Schaumann . +.\" +.\" 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 AUTHOR 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 AUTHOR 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 December 12, 2022 +.Dt sizeof 7 +.Os +.Sh NAME +.Nm sizeof +operator +.Nd yield the storage size of the given operand +.Sh SYNTAX +.Nm Vt ( type ) +.br +.Nm Vt expression +.Sh DESCRIPTION +The unary +.Nm +operator yields the storage size of an expression or +data type in bytes. +.Sh DETAILS +The size of data types in C (such as e.g., integers or +pointers) may differ across hardware platforms and +implementations. +For example, systems on which integers, longs, and +pointers are using 32 bits (e.g., i386) are referred +to as using the "ILP32" data model, systems using +64 bit longs and pointers (e.g., amd64 / x86_64) +as the "LP64" data model. +.Pp +As it may be necessary or useful for a program to be able +to determine the storage size of a data type or +object, +.Nm +yields that size in +.Em char sized units . +As a result, +.Pf ' Vt sizeof(char) Ns ' +is always guaranteed to be +1. +(The number of bits per +.Vt char +is given by the +.Dv CHAR_BIT +definition in the +.In limits.h +header; many systems also provide the "number of bits +per byte" definition as +.Dv NBBY +in the +.In sys/param.h +header.) +.Sh EXAMPLES +The following examples illustrate the possible results +of calling +.Nm +on an ILP32 vs. an LP64 system: +.Pp +When applied to a simple variable or data type, +.Nm +returns the storage size of the data type of the +object: +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32)" ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(char) \ + Ta 1 \ + Ta 1 +.It Li sizeof(int) \ + Ta 4 \ + Ta 4 +.It Li sizeof(long) \ + Ta 4 \ + Ta 8 +.It Li sizeof(float) \ + Ta 4 \ + Ta 4 +.It Li sizeof(double) \ + Ta 8 \ + Ta 8 +.It Li sizeof(char *) \ + Ta 4 \ + Ta 8 +.El +.Pp +For initialized data or uninitialized arrays of a +fixed size known at compile time, +.Nm +will return the correct storage size: +.Bd -literal -offset indent +#define DATA "1234567890" +char buf1[] = "abc"; +char buf2[1024]; +char buf3[1024] = { 'a', 'b', 'c' }; +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result" +.It Sy Object or type \ + Ta Sy Result +.It Li sizeof(DATA) \ + Ta 11 +.It Li sizeof(buf1) \ + Ta 4 +.It Li sizeof(buf2) \ + Ta 1024 +.It Li sizeof(buf3) \ + Ta 1024 +.El +.Pp +The examples above are the same for ILP32 and LP64 +platforms, as they are based on character units. +.Pp +When applied to a struct or union, +.Nm +returns the total number of bytes in the object, +including any internal or trailing padding used to +align the object in memory. +This result may thus be larger than if the storage +size of each individual member had been added: +.Bd -literal -offset indent +struct s1 { + char c; +} + +struct s2 { + char *s; + int i; +} + +struct s3 { + char *s; + int i; + int j; +} + +struct s4 { + int i; + uint64_t i64; +}; + +struct s5 { + struct s1 a; + struct s2 b; + struct s3 c; + struct s4 d; +} +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32) " ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(struct s1) \ + Ta 1 \ + Ta 1 +.It Li sizeof(struct s2) \ + Ta 8 \ + Ta 16 +.It Li sizeof(struct s3) \ + Ta 12 \ + Ta 16 +.It Li sizeof(struct s4) \ + Ta 12 \ + Ta 16 +.It Li sizeof(struct s5) \ + Ta 36 \ + Ta 56 +.El +.Pp +When applied to a struct containing a flexible array +member, +.Nm +returns the size of the struct +.Em without +the array, although again possibly including any +padding the compiler deemed appropriate: +.Bd -literal -offset indent +struct flex { + char c; + long b; + char array[]; +} +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32) " ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(struct flex) \ + Ta 8 \ + Ta 16 +.El +.Pp +One of the more common uses of the +.Nm +operator is to determine the correct amount of memory +to allocate: +.Bd -literal -offset indent +int *nums = calloc(512, sizeof(int)); +.Ed +.Pp +The +.Nm +operator can be used to calculate the number of +elements in an array by dividing the size of the array +by the size of one of its elements: +.Bd -literal -offset indent +int nums[] = { 1, 2, 3, 4, 5 }; +const int howmany = sizeof(nums) / sizeof(nums[0]); +.Ed +.Pp +Many systems provide this shortcut as the macro +.Dv ntimes() +via the +.Dv sys/param.h +header file. +.Sh RESULT +The result of the +.Nm +operator is an unsigned integer type, defined in the +.Dv stddef.h +header as a +.Vt size_t . +.Sh NOTES +It is a common mistake to apply +.Nm +to a dynamically allocated array: +.Bd -literal -offset indent +char *buf; +if ((buf = malloc(BUFSIZ)) == NULL) { + perror("malloc"); +} +/* Warning: wrong! */ +(void)strncat(buf, input, sizeof(buf) - 1); +.Ed +.Pp +In that case, the operator will return the storage +size of the pointer +.Pf (' Vt sizeof(char *) Ns '), +not the +allocated memory. +.Pp +.Nm +determines the +.Ev size +of the result of the expression given, but +.Em does not +evaluate the expression: +.Bd -literal -offset indent +int a = 42; +printf("%ld - %d\\n", sizeof(a = 10), a); /* Result: "4 - 42" */ +.Ed +.Pp +Since it is evaluated by the compiler and not the +preprocessor, the +.Nm +operator cannot be used in a preprocessor expression. +.Pp +The +.Nm +operator cannot be used on a bit-field object, a +function type, or an incomplete type. +.Sh SEE ALSO +.Xr arch 7 , +.Xr operator 7 +.Sh STANDARDS +The +.Nm +operator conforms to +.St -ansiC . +.Pp +Handling of flexible array members in structures +conforms to +.St -isoC-99 . +.Sh AUTHORS +This manual page was written by +.An Jan Schaumann Aq Mt jschauma@netmeister.org .