man man – What does the 1 in ls(1) mean?

/in , /by

man pages – many people would have loved to have known earlier about them. This article could be summed up as “just read man-pages(7)”. But what does that mean and why should you care?

A great feature of Unix based systems is that they usually are very well documented. However one still has to find out how to get to this documentation.

You might have come across things like crontab(5) and fortune(6). Maybe you even have read a few man pages. Whether you might be completely new or not somehow nobody ever told you how man pages really work and what that number there means.

What are man pages?

man pages are manual pages that either come with your operating system or individual software packages. This also includes libraries and other things. Every good package should come with at least one manual page, many come with more. They usually tell you things like its basic usage (syntax), give a description, sometimes examples, caveats, references, who the author of the software package is, known bugs or even history.

It can be read via the man command. Someone wanting to learn about man command itself could type man man and get an overview about the man command itself.

So what does the 1 in echo(1) mean? And why is it important?

The number in brackets is the section of the manual. But what does that mean?

man pages are structured in sections. In most cases this might not matter, but take for example crontab. Just typing in man crontab will usually open man(1). It will tell you about all the switches the crontab command has. You might wonder how to actually write a crontab entry. This can’t be found anywhere in this man page. Were they too lazy to document that? Hardly so. At the end of the manual page at the SEE ALSO paragraph you see a reference to crontab(5). This is because section 1 of the manual pages deals with commands and section 5 with file formats and configuration files.

To open it you open section with you need to specify the section before the name of the entry. In case of crontab(5) you enter:

man 5 crontab

This will give you the manual page regarding the crontab configuration file format.

Sections

To get an overview over the available sections you see man-pages(7). Keep in mind that some packages such as Tcl come with their own sections. If you have tcl installed man tcl intro will give  you the intro to this section of the manual pages.

Usage

The man command uses your system’s pager, usually less (check via echo $PAGER or printenv PAGER) to display manual pages. While less(1) will give you more details here are a few things to get you started.

  • Quit: Just press the Q-Key to close a manual page
  • Navigate: Navigation is similar to your web browser. Use arrow keys to go by line, space to jump a page and the page up and page down keys to jump a page up or down respectively.
  • Search: Use forward slash (/) followed by your search term to search through the manual page.
  • Help: In most pagers pressing the H-Key will get you to the pager’s help. It will tell you about movement, Searching, Jumping, etc.

Keep in mind. This is your systems pager, so learning this will be useful for everything else where you use your pager, which means when you view a file, use git log or other things. So time spent in learning this is certainly not wasted!

Conclusion

I hope you enjoyed this tutorial. Manual pages are a great way to keep you going, learn about interesting switches, but also caveats. Learning how to use them efficiently is something you can’t really do early enough. It makes you independent of often outdated or slightly varying documentation found in books or on the internet. While many of them are structured as references and not tutorials you will find them useful throughout your career.

Having deep knowledge in many areas is important. However, what probably is even more important is to know where to get information quickly and manual pages exist for exactly that reason. Saying that you’d look something up in a manual page, when you don’t know something in a job interview is always better than not being able to proceed at all.