Bug 268310 - add sizeof(7) man page
Summary: add sizeof(7) man page
Status: Closed Overcome By Events
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Fernando Apesteguía
URL:
Keywords:
Depends on:
Blocks: 108980
  Show dependency treegraph
 
Reported: 2022-12-11 02:52 UTC by jschauma
Modified: 2023-09-07 11:05 UTC (History)
3 users (show)

See Also:


Attachments
sizeof manual page (5.54 KB, text/plain)
2022-12-11 02:52 UTC, jschauma
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description jschauma 2022-12-11 02:52:03 UTC
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.
Comment 1 Konstantin Belousov freebsd_committer freebsd_triage 2022-12-11 14:10:05 UTC
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.
Comment 2 jschauma 2022-12-11 19:35:25 UTC
(In reply to Konstantin Belousov from comment #1)

Added a review here: https://reviews.freebsd.org/D37674
Comment 3 commit-hook freebsd_committer freebsd_triage 2022-12-13 04:44:59 UTC
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(+)
Comment 4 commit-hook freebsd_committer freebsd_triage 2022-12-20 00:56:05 UTC
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(+)
Comment 5 jschauma 2022-12-20 02:03:04 UTC
Thanks for merging, @kib!

Do you want to also intake the changes from https://reviews.freebsd.org/D37674 after your initial commit?
Comment 6 Konstantin Belousov freebsd_committer freebsd_triage 2022-12-20 02:05:33 UTC
(In reply to jschauma from comment #5)
Create a diff against current sources, then I will see what to do about it.
Comment 7 jschauma 2022-12-20 02:15:33 UTC
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
Comment 8 Konstantin Belousov freebsd_committer freebsd_triage 2022-12-20 02:20:53 UTC
Create a review for it.
Comment 9 jschauma 2022-12-20 02:32:38 UTC
https://reviews.freebsd.org/D37754
Comment 10 Fernando Apesteguía freebsd_committer freebsd_triage 2023-09-07 11:05:33 UTC
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