git: c50b1adfac7b - stable/13 - Add sizeof(7) manual page
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Tue, 20 Dec 2022 00:55:40 UTC
The branch stable/13 has been updated by kib:
URL: https://cgit.FreeBSD.org/src/commit/?id=c50b1adfac7bf4711620b47da84b07a6ae74ed47
commit c50b1adfac7bf4711620b47da84b07a6ae74ed47
Author: Jan Schaumann <jschauma@netmeister.org>
AuthorDate: 2022-12-13 04:35:11 +0000
Commit: Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-12-20 00:53:47 +0000
Add sizeof(7) manual page
PR: 268310
(cherry picked from commit 0b75997f4c5a15f02e6d5eee981a1b752dd0fd59)
---
share/man/man7/Makefile | 1 +
share/man/man7/sizeof.7 | 287 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 288 insertions(+)
diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index be7a5ae30500..1ecd7363af1e 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -26,6 +26,7 @@ MAN= arch.7 \
release.7 \
sdoc.7 \
security.7 \
+ sizeof.7 \
sprog.7 \
stats.7 \
stdint.7 \
diff --git a/share/man/man7/sizeof.7 b/share/man/man7/sizeof.7
new file mode 100644
index 000000000000..25ebfa11a0f4
--- /dev/null
+++ b/share/man/man7/sizeof.7
@@ -0,0 +1,287 @@
+.\"
+.\" Copyright (C) 2022 Jan Schaumann <jschauma@netmeister.org>.
+.\" All rights reserved.
+.\"
+.\" 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 size of primitive data types in C may differ
+across hardware platforms and implementations.
+It may be necessary or useful for a program to be able
+to determine the storage size of a data type or object.
+.Pp
+The unary
+.Nm
+operator yields the storage size of an expression or
+data type in
+.Em char sized units .
+As a result, 'sizeof(char)' 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
+Different platforms may use different data models.
+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
+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 units 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
+.In 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 ('sizeof(char *)'), 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.
+.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 .