Page MenuHomeFreeBSD

add sizeof(7) man page
ClosedPublic

Authored by jschauma_netmeister.org on Dec 11 2022, 7:33 PM.
Tags
None
Referenced Files
Unknown Object (File)
Feb 12 2024, 1:59 PM
Unknown Object (File)
Jan 19 2024, 7:24 PM
Unknown Object (File)
Jan 14 2024, 11:02 AM
Unknown Object (File)
Jan 14 2024, 1:51 AM
Unknown Object (File)
Jan 5 2024, 5:44 PM
Unknown Object (File)
Dec 28 2023, 5:31 AM
Unknown Object (File)
Dec 25 2023, 5:11 PM
Unknown Object (File)
Dec 22 2023, 6:33 PM

Details

Summary

Per https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=268310

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.

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.

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

pauamma_gundo.com added inline comments.
sizeof.7
36

Not needed IIRC.

69

Is LP64 here the same thing as LLP64 above?

120
243–245
jschauma_netmeister.org added inline comments.
sizeof.7
36

Without, I get both formatted on the same line:

sizeof (type) sizeof expression

But I want

sizeof (type)
sizeof expression

69

It's not - good catch! "LLP64" is "long long integer", with a "long" being 32 bits.

I'm updating the diff with the correction to use "LP64" consistently.

sizeof.7
57

BSD also historically provided NBBY symbol in sys/param.h, it is used quite often.

214

Then, mention the handy nitmes() macro from sys/param.h.

Would be also useful to state, either in SEE ALSO section, or in the main text, that the definitive description for sizeof is provided by the ISO C standard, whatever edition.

Mention NBBY, ntimes(), and standards.

sizeof.7
57

Noted!

214

Added a note below.

Text LGTM now, but my understanding of C is both hazy and dated, so take that with salt.

sizeof.7
36

Yeah, I was thinking of .Fn.

Can you send the git patch to me, with proper metadata (mostly author) set? Thanks.

This revision is now accepted and ready to land.Dec 12 2022, 5:26 PM
brooks added inline comments.
sizeof.7
42

This is misleading. sizeof() is never evaluated at runtime.

136

It might be worth including an example that illustrates the difference in padding of 64-bit types between i386 and other architectures. Something like:

struct s {
    int I;
    uint64_t i64;
};
sizeof.7
42

Are you sure? For variable-length arrays, it is.

Add uint64_t example, elide "at runtime".

This revision now requires review to proceed.Dec 12 2022, 6:25 PM
sizeof.7
42

Removed "at runtime". I think the rationale holds without anyway.

136

Yeah, makes sense. Added that.

In D37674#856694, @kib wrote:

Can you send the git patch to me, with proper metadata (mostly author) set? Thanks.

Sorry, it's not clear to me what you need, probably because I'm not familiar with the FreeBSD code integration process. I can generate a PR on github to FreeBSD's repository, if that's what you're asking for? Or email you the original file?

This revision was not accepted when it landed; it landed in state Needs Review.Dec 13 2022, 4:45 AM
Closed by commit rG0b75997f4c5a: Add sizeof(7) manual page (authored by jschauma_netmeister.org, committed by kib). · Explain Why
This revision was automatically updated to reflect the committed changes.

Initial review.

share/man/man7/sizeof.7
3 ↗(On Diff #114085)

Unfortunate addition.

37 ↗(On Diff #114085)

The description should first and foremost define or describe what sizeof is and then hint at when to use it.
Of course sizeof can be evaluated at runtime, and the omission of this information is a missed opportunity.

38 ↗(On Diff #114085)

"Primitive data types" is never well defined for this context, it would be best to stick to what the current standard says: expression, parenthesized type.
Missed opportunity to talk about incomplete types including void and function types.

47 ↗(On Diff #114085)

It's simpler to say that it yields the size in bytes.

48 ↗(On Diff #114085)

Isn't some kind of formatting needed here?

132 ↗(On Diff #114085)

I guess the units are "the char units", but it's confusing to say anything other than "bytes".

226 ↗(On Diff #114085)

The whole document as it landed reinforces the incorrect style that demands to 1) always enclose the operand in brackets (but this is necessary only for types) and 2) pretend that the operator is a function by omitting the space between the operator and the operand (in BSD this is further reinforced by return(0)).

We could keep it that way, but use this example to show that it's not the only style in the world:
const int howmany = sizeof nums / sizeof nums[0];

255 ↗(On Diff #114085)

Formatting?

256 ↗(On Diff #114085)

It's rare for manual pages to yell.

Initial review.

I put the edits along your suggestions into D37683

share/man/man7/sizeof.7
38 ↗(On Diff #114085)

The point of this sentence is to talk about primitive types, whatever they are. In fact, the reference to arch(7) should be good enough.

47 ↗(On Diff #114085)

Then the question should be answered what byte is in this context (as opposed to byte as defined by specific machine architecture). The C std language byte -- addressable unit of data storage large enough to hold any member of the basic character set of the execution environment is IMO worse than slightly clumsy char sized units.

Feel free to propose some middle-ground formulation there.

226 ↗(On Diff #114085)

The text uses the style(9) preferred formatting, which is to always put () around sizeof argument, be it type or expression.

share/man/man7/sizeof.7
3 ↗(On Diff #114085)

As per the original bug, I'm happy to assign the copyright to FreeBSD; please suggest the correct text you use here.

47 ↗(On Diff #114085)

I think it should be fine to use "yields the storage size in bytes" in the description and perhaps merely mention the "char units" / CHAR_BIT info into the "notes" section?

Rephrasing a few things based on pstef's feedback.

share/man/man7/sizeof.7
3 ↗(On Diff #114085)

I think just dropping the "All rights reserved." should be ideal.

47 ↗(On Diff #114085)

Sounds good, but also what kib wrote in the other diff sounds ok too.

226 ↗(On Diff #114085)

Maybe, but I have a mildly strong opinion that the target audience of this manual page are not only FreeBSD developers but anybody who wonders about sizeof in C and they happen to be logged into a FreeBSD running machine. The opportunity to refer someone to style(9) arises when they propose a patch to FreeBSD.