add sizeof(7) man page

[jschauma_netmeister.org]

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.

[jschauma_netmeister.org]

Minor formatting tweaks.

[pauamma_gundo.com]

sizeof.7

35

Not needed IIRC.

68

Is LP64 here the same thing as LLP64 above?

119

242–244

[jschauma_netmeister.org]

sizeof.7

35

Without, I get both formatted on the same line:

sizeof (type) sizeof expression

But I want

sizeof (type)
sizeof expression

68

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.

[jschauma_netmeister.org]

Update with pauamma@'s feedback.

[kib]

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.

[kib]

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.

[jschauma_netmeister.org]

Mention NBBY, ntimes(), and standards.

[jschauma_netmeister.org]

sizeof.7

57

Noted!

214

Added a note below.

[pauamma_gundo.com]

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

sizeof.7

35

Yeah, I was thinking of .Fn.

[kib]

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

[brooks]

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;
};

[kib]

sizeof.7

42

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

[jschauma_netmeister.org]

Add uint64_t example, elide "at runtime".

[jschauma_netmeister.org]

sizeof.7

42

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

136

Yeah, makes sense. Added that.

[jschauma_netmeister.org]

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?

[pstef]

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.

[kib]

In D37674#856836, @pstef wrote:

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.

[jschauma_netmeister.org]

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?

[jschauma_netmeister.org]

Rephrasing a few things based on pstef's feedback.

[pstef]

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.

[jschauma_netmeister.org]

Removed 'All rights reserved.'