Mastodawn

Number in man page titles e.g. sleep(3)

https://lalitm.com/til-number-in-man-page-titles-e-g-sleep-3/

TIL: Number in man page titles (e.g. sleep(3))

If you do Linux systems programming, you will have likely pored over man pages, either on the command line or, my personal preference, using the excellent man7.org or linux.die.net. I’ve always seen the numbers in sleep(3) and read(2) and idly wondered what they meant, but never actually bothered to look them up. That is, until a review comment on a pull request: // Behaves like man 2 basename reviewer: nit: it’s not a syscall, so “man 2” is incorrect So I looked it up. The answer was in the man(1) page (also accessible via the delightful man man command): The table below shows the section numbers of the manual followed by the types of pages they contain. 1 Executable programs or shell commands 2 System calls (functions provided by the kernel) 3 Library calls (functions within program libraries) (... less common section numbers) So my colleague was right and the code should have read // behaves like man 3 basename as basename(3) is a libc library call.

Lalit Maganti

Show thread

gerikson 1d ago

> (... less common section numbers)

One very important section number is 5 - it's for file formats. So if you forget the crontab format, you need to invoke `man 5 crontab` to read about it.

Show thread

linsomniac 1d ago

... because if you do `man crontab` you get section 1, which does not document the crontab fields.

Show thread

voidUpdate 1d ago

In fact, the only reference to crontab(5) is in the SEE ALSO section (on my version anyway), but that doesn't say why you might want to see crontab(5), just that it exists. That is spectacularly useless

Show thread

inejge 1d ago

> That is spectacularly useless

Depends. If one is aware of the meaning of section numbers, that "(5)" is very obviously suggesting that there is a file format named "crontab" which is documented. It's also pretty reasonable to suppose that the command and the file format of the same name are related.

A novice might miss the convention and the connection. Man pages are not quite novice material.

Show thread

simoncion

Hell, you don't even have to have a handle on what the section numbers mean for these things to be useful. The appearance of something in a "SEE ALSO" section indicates that the manual page author thought that that thing was both related to the thing being documented and worth reading if the current man page didn't answer all of your questions.

I can't count the number of times that following the trail laid out by 'SEE ALSO' sections a step or three has lead me to the exact thing that I never knew I needed to be using. Chasing those sections down is almost always well worth the three to ten minutes spent.

And, like, if one is expecting a man page to cover in detail everything even vaguely related to what it documents, and one doesn't feel one has ten minutes to spend reading things that people thought were important to bring to your attention... well, I guess one could go ask an LLM to slop out some related words. That'll probably take less than ten minutes, though correctness is not at all guaranteed.