Casey Brant

Jan 18, 2009

man

NOTE: This post originally appeared as part of a weekly series on Unix tools I attempted to write way back in 2009 called “52in09”. Not only did it have a lame name, I didn’t make it past the first few weeks. Also, the formatting here is kind of janked up, but I’m not planning to take the time to fix it.

Intro

Last week was a fun way to kick off the 52in09 series, but if the point is to introduce a basic set of Unix commands, ‘screen’ is hardly the best place to start. Today we’re going to get back to the basics and take a look at the first command any new Unix user should learn: man.

Unix systems come with an excellent set of manuals, and ‘man’ is the program that helps you read them. They are designed to be complete and authoritative; rare is the occasion that you have a problem with a command and can’t find the answer in the man page.

If man pages are so helpful, then why do Unix tutorials like this one even exist? It’s because most of the time, man pages were written to be as terse as possible. Ultimately, this is a good thing: it means experienced users will be able to get the information they need right away. However, the terseness can leave new users a bit bewildered. So, things like 52in09 exist to point you in the right direction. Once you have some idea what to look for, the man pages will be a lot more useful.

That’s It?!

‘man’, like many Unix programs, is capable of more functionality than you’ll usually need. The majority of the time, all you have to know is man <TERM>, where &lt;TERM&gt; is the name of what you’d like to look up. This pulls up the first page man can find on that topic.

The man page will open up inside a program called a “pager”, usually ‘less’ or ‘more’, for easier reading. I’ll talk more about pagers in a future post. For now, all you need to know is that the arrow keys will move around the page, and 'q' will get you back to the command line.

Most of the information presented to you by man is self-explanatory. Note that the manuals encompass more than just commands (there are also man pages for configuration files, for example), so the layout of all pages will not be exactly the same – sections will be absent or present as appropriate. In general, though, the look of the manuals is consistent, so you’ll be comfortable once you’ve seen two or three.

The SYNOPSIS is usually near the top. This section shows the various ways you can string together the options for that command. This part can get pretty indimidating (at least it was for me) if there are a lot of options, but after you’ve muddled through the arcane syntax a few times, it will make perfect sense.

The DESCRIPTION section is the meat of most man pages. Here, you’ll find out everything there is to know about different ways you can use a given command.

apropos and whatis

There are lots of command line options and configuration settings that you can use with ‘man’, but most of them can be safely ignored unless you run into a bizarre problem. Of the ones you should know, man -k <TERM> is the most useful. If you don’t know the exact name of the utility you need, use man -k <TERM> to search through the manuals for <TERM>. You’ll get a nice list of all the matches, along with a brief description of each one. If a result looks promising, just open up its man page to read more.

man -f <TERM> is the other option I frequently use. This will give you a brief description of <TERM>, if there is a manual for it. This is faster than opening up the whole man page, and it’s also a good way to see if <TERM> has more than one man page associated with it. If so, man -s <TERM>` will open up the page for `` in section `<SECTION_NUM>`.

The -k and -f flags are useful, but it’s easy to forget which is which. apropos and whatis, respectively, will perform essentially the same function as those flags, and are easier to remember.

‘man man’ and the Road to Enlightenment

It’s funny, but it took me a few weeks as a Unix beginner before I thought to try running man man at the command line. I’m assuming that most people aren’t as slow as I am, but just in case, I’m giving you the spoiler right here. This zen-like command is your ticket to the beginnings of Unix mastery. Understand ‘man’, and you have the ability to learn almost anything about your system.

‘man -a intro’

If you’ve got some free time and want a great overview of basically your whole system, run man -a intro. This will take you on a whirlwind tour of several introductory pages. At the end of each page, hit 'q' and you’ll be shown a menu. Go through the whole set of ‘intro’ man pages, and you’ll be one step closer to guru-ship. (NOTE: I run Ubuntu Linux, and I’m not sure if the ‘intro’ man pages are available on all flavors of Unix or not.)

The Problem With ‘man’

One of the best things about Unix is that, typically, each program is small and specialized. This means that it’s not too hard to master any given tool. What’s difficult about mastering Unix isn’t learning individual commands; it’s learning how to use them together.

There are two parts to the Unix way of doing things. The first is to have a kit full of special-purpose tools. The second is to be creative about the way you use those tools, and to find powerful ways to combine them in order to accomplish difficult tasks.

The weakness of ‘man’ is that it can only tell you about a single tool at a time. Mastery of the tool kit is only half (the easier half, unfortunately) of effective Unix usership. Only experience will provide the second half.

Actually, this is what’s really beautiful about Unix. While the learning curve is much easier on graphical systems like Windows, once you learn it, you’re done; that’s all there is. With the powerful command line of Unix, there is no “done”. There are wizards who have been using Unix since it was invented, and they’re still creating new ways of doing things all the time.

Anyway, enough philosophy. Thanks for tuning in this week! As always, please leave some comments with your own tips, suggestions for future posts, errata, or what have you. See ya next week!

Hey, thanks for reading. I don’t have comments on my blog, but I’d still love to hear from you. These are the best ways to reach me:

Or, check out my other posts and projects.