From nobody Tue Dec 13 04:44:56 2022 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4NWQs43c4tz4jnsF; Tue, 13 Dec 2022 04:44:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4NWQs42d3kz46ML; Tue, 13 Dec 2022 04:44:56 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1670906696; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=jzTI7+oFiZyZ2iGoUDZ08aOdk3vwXOkIJXJ4+kIxO3A=; b=nSR0Lntskp3ZxXR/B+W2LAbNZW7Z24AzMbelllkLRtcd3GM8DQT782ulQVbFBYYwPpkld8 AhWaoTJURau+AS2g1rgiPoz/Og7PSAcexV0rAwOCPhkkhDpG42Ke19mroumAd9gDOggNWX XJjFuckQTU3PztxyE6a72CRz2H9BhdHMjR33skIRjr+6EwlimPfUslxT77lNV4HYgBohO/ iibAk+6TespuourLpoVX43s3q1LXZcEXV6GR/JrEHp3FCBDZunSpGy/LEPzfDjmv+Rx3+r FJLejIF9MxVuWZWhRwn2u9iR6TmNUjXcQH9YMOoO1wR1KOG3Y4G/N8Sel+CJgg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1670906696; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=jzTI7+oFiZyZ2iGoUDZ08aOdk3vwXOkIJXJ4+kIxO3A=; b=PxqwRKVo2qArBFx9qdmQo89JA+Z0yUlG+08ZSd9w4D6qZMIPE2eVw3EkBvNNeoH8fgkgnq SVjKUMA4GivC3BrfQzsSK0pzmH+pk3zc1lKtKU2qSmwpMhUqMIUx3/88bDMABCJzF05oXI Tqu8R9pwLVfF8GjfKqTpfIQ70rHxOho22ywTKrq3EbL99+L8z0tp3IerWsBkWEFfRZ0Koy JTSay/dDCasOQo/TPatIAdUhUM1acc8bc0r25aov8kn7dStOtn6yGKPXR8qR9FxMcCiRFg SdzO/A57y1LYOfu/FfA996egAPoOCviDOdTQ4aQi3XQXJfK37WklXKx0ghd/4Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1670906696; a=rsa-sha256; cv=none; b=F4pbMWRir11L1Uh6JgoIfvvP5kHEcCDKdWiM0rtJP2jQsEvGPOc6SwoXMfQi1iq29q71iT GTZN7RGfNpZRG1fbgf1FOdO0x9EtbKQ0WmviLTAQ60xIKpvIBX9ZgJ1ceQ/eR007QzG9eW Sy6PDS7kraGUO26f2PAlkjAOp5ELjx6D2nuObsREGSRXsuSASBltrzC1EDZlmN5tcRmJB1 CqoR+SR6ZYlDMr16Rw+/03YAsyxNRVDtsPeCmTPLJlj8sr4ocpGhZiEy6hnXWuquCQ2XQ3 um9wKoL1RZOvZccm7Y8Yb/2P940f6+7Ki+nLhpaP/+MeGyrywzxb81L/ds7gTA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4NWQs41h56z11y6; Tue, 13 Dec 2022 04:44:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 2BD4iuPO089938; Tue, 13 Dec 2022 04:44:56 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 2BD4iuf2089937; Tue, 13 Dec 2022 04:44:56 GMT (envelope-from git) Date: Tue, 13 Dec 2022 04:44:56 GMT Message-Id: <202212130444.2BD4iuf2089937@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: 0b75997f4c5a - main - Add sizeof(7) manual page List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 0b75997f4c5a15f02e6d5eee981a1b752dd0fd59 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=0b75997f4c5a15f02e6d5eee981a1b752dd0fd59 commit 0b75997f4c5a15f02e6d5eee981a1b752dd0fd59 Author: Jan Schaumann AuthorDate: 2022-12-13 04:35:11 +0000 Commit: Konstantin Belousov CommitDate: 2022-12-13 04:43:28 +0000 Add sizeof(7) manual page PR: 268310 Reviewed by: kib Discussed with: brooks, pauamma MFC after: 1 week Differential revision: https://reviews.freebsd.org/D37674 --- 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 51061d13b4a8..f50e31cdeb11 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 . +.\" 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 .