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

If you like man trivia (and why else would you be reading this?) you could check out the top comment at https://unix.stackexchange.com/questions/405783/why-does-man...

(discussed at https://news.ycombinator.com/item?id=27994194)

Why does man print "gimme gimme gimme" at 00:30?

We've noticed that some of our automatic tests fail when they run at 00:30 but work fine the rest of the day. They fail with the message gimme gimme gimme in stderr, which wasn't expected. Why are...

Unix & Linux Stack Exchange

Reading this makes me wonder if Easter eggs are ever appropriate for something as ubiquitous as man.

Easter eggs are always appropriate but it is imperative (and important) to understand how they could affect anything and everything.

Which means you need to usually make it explicit to call them (man --abba or something) than something that "surprises" the user.

Almost everything had an easter egg in it back in the day. When computing was more fun and less serious.

They fell out of favor when people realized they were a security issue, because it was a code path that rarely got tested.

Or they were removed for other reasons than security.

In Star Trek: 25th Anniversary, we had a hidden animation of Captain Kirk's toupee jumping off his head and running out of the room. It was caught before release and they made us take it out since no one wanted to piss off William Shatner.

"The developer of the man-db, Colin Watson, decided that there was enough fun and the story won't get forgotten"

Haha! Adequate amount of fun was provided, please resume regular man activities.

Another fun related one: If your username is Tyler and you run shutdown, instead of the usual message it will say "Oh, good morning Mr. Tyler, going down?"

Discovered this in college when I was shoulder surfing a coworker who always used the username Tyler. When he typed shutdown I called it out, and he said, "wait, it doesn't do that for you? I always assumed it said that for everyone and just replaced the username!".

(For those of you too young to know, it's a reference to an Aerosmith song)

A great innovation over simple AB testing

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.

linsomniac 1d ago

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

IshKebab 1d ago

That is incredibly stupid. A documentation system designed by someone who doesn't understand how people use documentation.

If man was designed by someone with any taste at all it would at least give you a menu to select (1) crontab command, (5) crontab file format. Maybe we need a rewrite in Rust to fix that.

Or a minor alteration to an existing program to support a good suggestion.

Why is it that the Rust community thinks that the solution to every flaw in an application is a rewrite in Rust?

mattkrause 1d ago

It might be more helpful to write a Rust-based snark detector first.

Could be, but I don't think so in this case given a cursory review of the parent poster's history.

It does that, depending on implementation.

> If man was designed by someone with any taste at all it would at least give you a menu [...]

My goodness. Man was written on a paper teletype.

SoftTalker 1d ago

And since man pages could take minutes to print out, if you needed one you'd tear that section of paper off and keep it in a binder for future (and faster) reference.

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

> 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.

simoncion 1d ago

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.

driftcoder 1d ago

man -k crontab is the real trick here. shows both sections so you don't have to already know the number exists.

voidUpdate 1d ago

It only shows a description though.

Incidentally, man --help on my machine shows "-k, --apropos equivalent to apropos", which isn't very useful. I know the two are equivalent, because they're on the same line of switches, what does it actually do?

With some further man digging, apropos is actually a separate program that looks through man page names/descriptions for the argument. Unless you run it with no arguments, in which case it just outputs "apropos what?" Instead of an actual error message like "No search term provided" or something

simoncion 1d ago

> Incidentally, man --help on my machine shows "-k, --apropos equivalent to apropos", which isn't very useful.

That's your hint to execute either 'man apropos' or 'man man'. Both tell you in detail what the flag and utility do.

You seem likely to be very disappointed in the '-h'/'-H' output of utilities from the BSD tradition. The output is often a list of all of the (almost always exclusively short) options presented as a sea of characters... and nothing else.

PhilipRoman 1d ago

Interestingly, the section doesn't actually have to start with a number. TCL man pages use the 'n' section and 'man' resolves them just fine despite the ambiguity. Conversely, manpage names can also start with numbers, although this is rare (I found only one such example: man 30-systemd-environment-d-generator)

My favorite piece of man trivia is from the source of the tunefs BSD man page, which contains:

    .\" Take this out and a Unix Daemon will dog your steps from now until
    .\" the time_t's wrap around.
    .Pp
    You can tune a file system, but you cannot tune a fish.

https://github.com/freebsd/freebsd-src/blob/main/sbin/tunefs...

freebsd-src/sbin/tunefs/tunefs.8 at main · freebsd/freebsd-src

The FreeBSD src tree publish-only repository. Experimenting with 'simple' pull requests.... - freebsd/freebsd-src

GitHub

gmassman 1d ago

I guess the joke is you can scale a file system or a fish, but can only tune a file system?

fragmede 1d ago

Tuna is a type of fish so the joke is that they sound the same.

SoftTalker 1d ago

There was also the record You Can Tune a Piano, but You Can't Tuna Fish by REO Speedwagon, I had assumed that's what the tunefs man page was referencing as that was a best-selling record at around the time Unix was being developed.

throwanem 1d ago

Yes. It had been a popular joke in the US, I believe about a generation before. (Probably the joke came in around the same time as canned tuna.)

pwdisswordfishy 1d ago

You can tune a fish, it's that the command for that is fish_config instead.

Thousands of keystrokes saved by not having to type “man syscall”… and millions of hours lost by confused folks like OP (and myself)