From nobody Tue Dec 20 00:55:40 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 4NbdRJ4tDpz1GLHZ; Tue, 20 Dec 2022 00:55:40 +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 4NbdRJ4Knkz3pVq; Tue, 20 Dec 2022 00:55:40 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1671497740; 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=QFpZxPfN3JG1ROENMgS1sqSyazKKgyXs4vhCQ8W2Sqc=; b=QS7PI6wM3hWHGfa0HY5/3y0vfa2OtjPJjnqOXlnLPy0HpQ6uFsFc+DSA/eFfsmA+pFgHVg Z0DOz4cqgxY2xFymunDXzaZolIm9fcYtBYA+uouk6HCs+/XnHAMjlEhTfnoEOabol6GpKv bvcWj5fxsi9bvprGKFw6ii+dUSWrjV/6Wfead7sHXHHf/2FYVBHBtk7lWe6ZpCCyTlwuW3 wQWGur2G/inzwnr60VE1m26oVkzIbU8UD7K6oWbgT+AaH6cUJvlFy9oW7UKBkLnbsdAsMg q/kkY7XeVz9b1/+zp0IwIvzzVfQJte1Mm/cCe7FaSem9G5BMmcvdrB13x0nb6Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1671497740; 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=QFpZxPfN3JG1ROENMgS1sqSyazKKgyXs4vhCQ8W2Sqc=; b=jjLV4Snb3VYseehEW0dqKoPcbepVHD1L7vRPUtuTxIskg4RwcAb5zF/3cevwP5J0u7fR3S hrh/ki4qWy6BGWZZHb040do+nud6yCz7f09HMpVRZXa1qLAOaYkU04eI7uX4xgC9KdYQcJ wTiitLg4FgYSEIUZafkxtJQ72BGN5FQI47zZYO66d7mI8R+9KOOqPimGbpj9GbXRpftArF 3sGzzUrEKSMGjnEhKfOeE9FtbwT6j9+EiEgUAK9sH9xHKvPY/xstQHVUqSJK+q8+ve2RuE 2ylgL+ZpLFQVBelA/K3SyQ4mt0Sunn+MsnczsnVbJa+eJUaW9Y3GSYctY5sNHw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1671497740; a=rsa-sha256; cv=none; b=Rts/fkbKIvRFnK+gQY++I+BajMQuH4233nk61MOteAt/4Bzir/rYKdBwT8p0Oh+SenG/xy iiUrhiP2XzRmDAq1rBpye3LbJlF7X5mgq0hXJzNZmRVPpogwfxhCbFFpNaczyNTKvA2nIb zNxVU+X7fRuZM6eaOg6c7h6zXMDpispD23AntT+nDenGVjfKDbqNezCMPQTK976VOcm14e Uouf+i6V3y1iwZPU06tdppEcOwvCsYvBcUFZQjhkQYbJ5P71HzI/SQKH9udgpIzobti0Jn DTe4wMzmSYrKIffa9sgfltc6Vb9O+bCBcQaneyOlt6z2ZJs9EOEFmjrTelXefw== 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 4NbdRJ3HJhzGT2; Tue, 20 Dec 2022 00:55:40 +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 2BK0te9v086320; Tue, 20 Dec 2022 00:55:40 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 2BK0teTZ086319; Tue, 20 Dec 2022 00:55:40 GMT (envelope-from git) Date: Tue, 20 Dec 2022 00:55:40 GMT Message-Id: <202212200055.2BK0teTZ086319@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: c50b1adfac7b - stable/13 - 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/stable/13 X-Git-Reftype: branch X-Git-Commit: c50b1adfac7bf4711620b47da84b07a6ae74ed47 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=c50b1adfac7bf4711620b47da84b07a6ae74ed47 commit c50b1adfac7bf4711620b47da84b07a6ae74ed47 Author: Jan Schaumann AuthorDate: 2022-12-13 04:35:11 +0000 Commit: Konstantin Belousov 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 . +.\" 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 .