Created attachment 238705 [details] sizeof manual page As an operator rather than a library function or syscall, 'sizeof' does not have a manual page. Its use is however not always completely obvious and especially novice programmers misunderstand its function. Being able to type 'man sizeof' to get an explanation is a lot more convenient than having to rely on Google->StackOverflow and hoping whatever answers one finds there is reasonable. I wrote a manual page for the 'sizeof' operator: https://github.com/jschauma/manpages/blob/main/man7/sizeof.7 (I've attached a copy of the manual page here to the bug as well.) If the FreeBSD Project sees value in this and would like to add this manual page to the base system, I'd be happy to sign over the copyright. Note: my mandoc-fu is weak, and fixes and improvements may well be necessary.
We do not have a C reference in the base system, at least nobody ever tried to write some. Still, I think this text is useful. As an immediate addition, I suggest you to cross-reference the arch(7) and operator(7) pages. More precise terms like LP64/ILP32 when talking about concrete sizes should improve the text. Could you please create a review (as in https://reviews.freebsd.org) for your submission? Or at least make a github PR, where inline comments could be added.
(In reply to Konstantin Belousov from comment #1) Added a review here: https://reviews.freebsd.org/D37674
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=0b75997f4c5a15f02e6d5eee981a1b752dd0fd59 commit 0b75997f4c5a15f02e6d5eee981a1b752dd0fd59 Author: Jan Schaumann <jschauma@netmeister.org> AuthorDate: 2022-12-13 04:35:11 +0000 Commit: Konstantin Belousov <kib@FreeBSD.org> 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 (new) | 287 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 288 insertions(+)
A commit in branch stable/13 references this bug: 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 (new) | 287 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 288 insertions(+)
Thanks for merging, @kib! Do you want to also intake the changes from https://reviews.freebsd.org/D37674 after your initial commit?
(In reply to jschauma from comment #5) Create a diff against current sources, then I will see what to do about it.
Here you go: --- in-tree.txt 2022-12-19 21:13:16.000000000 -0500 +++ sizeof.7 2022-12-19 21:14:16.000000000 -0500 @@ -1,6 +1,5 @@ .\" .\" 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 @@ -35,17 +34,30 @@ .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 +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, 'sizeof(char)' is always guaranteed to be 1. +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 @@ -59,13 +71,6 @@ .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 @@ -129,7 +134,7 @@ .Pp When applied to a struct or union, .Nm -returns the total number of units in the object, +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 @@ -229,7 +234,7 @@ Many systems provide this shortcut as the macro .Dv ntimes() via the -.In sys/param.h +.Dv sys/param.h header file. .Sh RESULT The result of the @@ -252,8 +257,10 @@ .Ed .Pp In that case, the operator will return the storage -size of the pointer ('sizeof(char *)'), not the -allocated memory! +size of the pointer +.Pf (' Vt sizeof(char *) Ns '), +not the +allocated memory. .Pp .Nm determines the @@ -270,6 +277,11 @@ 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
Create a review for it.
https://reviews.freebsd.org/D37754
I think we can close this one. The review https://reviews.freebsd.org/D37754 was closed because there were already changes in-tree which obsoleted the review. Among those changes there are mentions to LP64 and ILP32 that kib@ mentioned. Another relevant review that improved the manual page was: https://reviews.freebsd.org/D37683