A real intro to Unix manpages

I remember a time when I was almost completely ignorant of manpages. I was a University student, and all of the course work was being done in Java. All of the instruction leaned heavily on the all-powerful IDE. It was how we wrote code, ran the compiler, accessed documentation, and saw the output.

Then I took an intro to C course. When it came time to learn C the prof decided to teach us some basic command-line stuff. One of the first things they showed us was how to look up documentation for the different commands we would need. It went something like this:

For the gcc command, type man gcc to see all the options. For the ls command, type man ls. Even the man command has its own page at man man. Isn't that clever.
Did you have the same experience? For months that was the extent of what I knew about manpages. I thought it was just shell commands. I'll show you what I've learned about them since then.
The first thing I learned about manpages is that there are many sections. In total there are something like 9 different sections.
  • Section 1 covers shell commands. This is probably the one you are most familiar with.
  • Section 2 covers system calls.
  • Section 3 covers C library functions.
  • Section 4 covers special files (usually in /dev).
  • Section 5 covers file formats.
  • Section 6 covers games and screensavers!
  • Section 7 covers miscellania. Some really useful stuff in here!
  • Section 8 covers administrative commands.
  • Section 9 covers kernel interfaces.
Whew. I bet there's a lot more here than you thought!

I'm going to assume that you are familiar with looking up shell commands in the manpages, so I won't talk any more about section 1. You've probably already seen pages from this section when typing man grep or similar. I'll show you a few useful nuggets from the other sections.

The dreaded crontab file
Have you ever had to add an entry to a crontab file? I've done it a number of times, and I still end up looking up documentation each time. The syntax is notoriously non-obvious.
For the longest time, I would just head to Google and search for some examples. I've written previously about how I think looking up documentation on the local system is more productive than going to Google. So did you notice that Section 5 of the manpages covers file formats? Well, there's one for crontab! But you have to know how to find it.
If you just type man crontab, you're going to see documentation from Section 1 of the manpages, the docs for the crontab shell command, rather than the file format. You can tell which section you're seeing by looking in the top left corner of a manpage. For the shell command you'll see CRONTAB(1), and for the file format you'd see CRONTAB(5). This style of reference is the default way to refer to manpages. Just saying "the manpage for crontab" would be ambiguous without including the section, since it appears in multiple sections.
The trick that you need to know is that you can pass the desired section as the second argument to the man command. Like so:
    $ man 5 crontab
Seriously, go try that.
You'll see documentation about the crontab file format along with some examples. No more paging through Google!
So you can target any section like that. If you try
    $ man 2 crontab
You'll see that there's no system call called crontab, so you don't get anything.
This is getting to be longer than I planned, so I'll just throw a few useful manpages at you.
intro(2) - Each section has an intro (accessed using man 2 intro or man 5 intro). Most are pretty empty, but you can actually learn things from the system calls intro.
hosts(5) - Next time you need to figure out how to add an entry to your `/etc/hosts/` file.
fork(2) - Forking is how processes get created. This is also the C equivalent of Process.fork in Ruby.
All of the stuff in section 7 is typically only available on Linux systems. At least, I know it comes with Ubuntu, but isn't available on my Mac.
tcp(7), socket(7) - All of the stuff in section 7 provides really useful highish-level overviews. These two pages cover the TCP protocol, and the usage of sockets, respectively. Fun stuff!
If you want a few more tips, like searching the manpages, check out my blog post on the topic.
Until next time,

PS - You might be wondering about Section 6 (games and screensavers). You won't find too many commands that fit this category, but text-based games would. ski(6) is one example for the ski game. Another example is the sl(6) command, definitely check this one out if you haven't heard of it :)

comments powered by Disqus