All Shell Scripting Tips

5 Feb 2018

Witty 'man' page entries

Wit and humour in *nix documentation

The online manual pages (or 'man' pages for short) on Unix and Linux systems are a useful reference for checking the syntax of a given command. They sometimes also reflect the traditional humour associated with Unix systems administration.

A quick aside about the structure of 'man' pages: Each tends to be broken down into different sections; Each page belongs to a 'section' of the overall documentation, so (1) indicates general commands, (5) indicates information about file formats, and so on (see wikipedia for the full list). So to fully reference a 'man' page, it is customary to include the section after the name, like "crontab(1)" to indicate the 'crontab' command, or "crontab(5)" for the documentation about the structure of the "crontab" file. You can specify the required section via:

$> man -s 1 crontab

Within each page, there are various sections, typically "NAME", "SYNOPSIS", "DESCRIPTION", and so on. The "BUGS" section of a 'man' page is a good place to look for these nuggets.

Here are a few examples:

false(1)

false - do nothing, unsuccessfully

The false command, opposite to the true command, does nothing, and returns a non-zero (normally 1) value as a response. This can be useful for testing scripts, but has other uses too.

true(1)

true - do nothing, successfully

The true command, opposite to the false command, does nothing, successfully. This can be used, for example, in a while loop:

while true
do
  echo "`date`: I'm still running!"
  sleep 10
done

The GNU documentation does point out that true can actually return a non-zero exit code if, for example, it tries to write its version information or help output to disk!

bash(1)

In the "Bugs" section of the bash shell's 'man' page, the first item is:

It's too big and too slow.

Short and sweet. It's a great shell, but these are the two key reasons that it's been replaced by dash as the default /bin/sh by many GNU/Linux distributions.

halt(8)

The BSD halt -n command will reboot without spening time on syncing the filesystems first. The man page describes this as "Don't sync before rebooting. This can be used if a disk or the processor is on fire."

syslogd(8)

The syslogd man page has a section entitled "There are a number of methods of protecting a machine:", which includes:

if the problem persists and is not secondary to a rogue program/daemon get a
3.5 ft (approx. 1 meter) length of sucker rod* and have a chat with the user
in question.

Sucker rod def. - 3/4, 7/8 or 1in. hardened steel rod, male threaded on each
end. Primary use in the oil industry in Western North Dakota and other locations
to pump 'suck' oil from oil wells. Secondary uses are for the construction of
cattle feed lots and for dealing with the occasional recalcitrant or belligerent
individual.  

tunefs(1)

The old tunefs program's man page included the terrible pun:

You can tune a file system, but you can't tune a fish.

This was preceded by a hidden comment, visible only to those actually editing the man page:

        .\" Take this out and a Unix Demon will dog your steps from now until
        .\" the time_t's wrap around.

yum(8)

The Red Hat Package Manager utility yum has a few 'man' pages, the "Bugs" section of most of these claims that:

There of course aren't any bugs, but if you find any, you should
first consult the FAQ mentioned above and then email the mailing
list: yum@lists.baseurl.org or filed in bugzilla.

Related Links

There is also a funny-manpages project, but that is a different category; this page is for amusing entries in genuine man pages.

The GNU project also has some related funny pages.