How to read a Linux man page

Linux University staff meetings, when they happen, (In reality these tend to be prolonged coffee breaks at the local cafe) are often times of vigorous discussions on various topics. So the other day, we asked Simon, one of our staff authors a loaded question:

“What is one of the first things a new Linux user should learn?”

Simon looked at us, thought for a moment and simply said: “How to RTFM” – meaning “how to read the fine manuals.”

We asked Simon to write an article about this, and after a few days of nagging, an email from Simon arrived. Here is what it said:

How to RTFM

Reading man pages

Man pages, short for manual page, are the traditional form of documentation for command line tools on Linux (and Unix). The current crop of man pages has a history dating back to the 80’s, when Unix didn’t care in the least about user friendliness, and so they tend to be highly technical and have a form and language all their own.

Fortunately, they can be read reasonably easily with some practise, and are a very valuable source of information for the vast collection of command line tools that helps make Unix and Linux uniquely powerful.

Structure of a Linux man page

Man pages follow a standard structure, though like with Linux and Unix there are a number of different standards that they follow. The simplest structure, and the one that all the others are derived from, starts with a synopsis, followed by a detailed description section, and finally some end-matter boilerplate.

The synopsis is a brief and rather cryptic summary of how the program can be used. It lists all the options and arguments that the program recognises and gives a brief indication of how they can be combined. Options are the ‘-b’ or ‘–blah’ part of the synopsis – they let you modify the behaviour of the program, and come in short (-b) and long (–blah) forms. Options can take arguments, either in the form ‘-b foo’ or ‘–blah=foo’. Mutually exclusive alternatives are described with the ‘|’ character – i.e. ‘foo|bar’. Finally, when an option or argument is optional this is indicated by surrounding it in square brackets.

Fortunately, you can mostly ignore the synopsis – it’s most useful as a reference once you’re already familiar with using a program. Before you reach that point the most useful section of a man page is the description.

The description section contains a detailed description of what the application does, along with a list of all the options, arguments, and what they do. This is the real guts of the man page – when you’re trying to figure out how to make the program do what you want, you’ll spend most of your time looking through the description, reading the information about each option and figuring out whether it helps you toward your goal.

This section may be broken out into a number of parts, with some extra bits on top of the basic description. The most useful of these extras is an examples section, with a set of examples of how the program is actually used. These examples can be a lifesaver – if they’re included in the man page the best way to use them is to as the basis for your command line. Copy the example and then replace the example file names and so on with your details.

Quite often there will be information about bugs or odd behaviour, error messages, environment variables, and other snippets like this. Most of it isn’t very relevant to everyday use, since it documents special cases or things that are only relevant for advanced users. However, it’s always nice to know that the information is there for those odd times when you might need it.

At the end of the man page is a bunch of meta-data about the document itself – the authors, copyright information, and frequently some contact information about the document authors and the program authors. A big thing here is an email address or other contact information for reporting bugs – in general the developers of a program love to be told about bugs, and will be very helpful in fixing them once they’re told. It’s a good way to help them out – you may not be able to write code for them, but if they don’t hear about bugs they’ll never be able to fix them.

The final part of the man page is one of the most useful: the ‘see also’ section. This is a list of related applications and man pages: generally you can simply use the man program to read this documentation, the same as the man page you’re reading in the first place. There may also be links to other documentation, on-line or in books or similar, which can also be useful.

How to read a man page

Now you know what to expect from a man page, how should you read it? Man pages aren’t like a story where you start from the beginning and read straight through to the end – it pays to pick the bits you need out of them while skipping the parts that aren’t relevant. The trick is to know how to find the relevant bits.

Assuming you know roughly what you want to do the place to start is with the description, in particular the description of what the program actually does. This should tell you whether the program will do what you want, or whether you should go looking for something else that will. Read the general description in full to find this out.

Once you’ve decided to give this program a try you should quickly flick through the list of options looking for keywords. For example, if you want to know how to list all files in a directory look for the keyword ‘all’, and quickly read about any options that look relevant. This can be helped using the search function, which can be brought up by hitting the ‘/’ key and typing in the search term. You can jump to the next instance of the term using ‘n’, and the previous instance using ‘N’.

Check to see if there are any examples listed, and if there are, base your command line on the example that seems most relevant. If there aren’t any, start with the plain command name and build from there.

If there is an option allowing you to do a dry run – i.e. to run your command without any actual changes being made – you should make use of it. Unix commands are very unforgiving, and if you make even a trivial typo it can have disastrous consequences (some time you should try running ‘rm -rf * ~’, but only on a machine where you don’t mind losing your home directory ;-).

Finally, if you find that you need more information or that the program doesn’t do what you wanted, you should look at the ‘see also’ section to try and find something that will.


So how do you decide what man page to read in the first place? This is where being able to search the man database is useful, and that’s what apropos does. To search for a keyword in every man page on the system, simply type ‘apropos word’, and let it run. It will print out the name of all the man pages that contain the word you search for along with a short description, which you can then browse through to find likely looking candidates. Just be aware that there are often enormous numbers of man pages on a Linux system, so you can easily get hundreds of lines of output! The same functionality can be accessed by running ‘man -k’.

The only other thing to remember about apropos is that it only searches the man pages of installed programs – to find documentation for programs that aren’t installed you’ll probably need to hit Google and have a look on-line. Fortunately, various groups have put the full set of man pages up on their web servers, so using Google you can often find exactly the same thing you’d find if it was installed on your computer.


To find out more about Simon, please visit our Authors page

Anatomy of a Linux System: An Overview

Anatomy of a Linux System

Here at Linux University, we have been debating the best way to show as many people as possible, in as simple way as is possible, the way a Linux based system works “under the hood”. What we talk about here will be true for all platforms supported by Linux, from a hand held such as a tablet or a mobile phone to the huge, such as a super computer in a research facility.

This is the first article in a planned series that deals with the anatomy of a Linux based system.

In general, any Linux based system comprises of several parts. These are:

The Kernel

All Linux based systems are built around the Linux Kernel. The kernel is the heart of the operating system; it is what makes the hardware go. Linux kernel is what is classed as a “monolithic kernel”, which means that all the core kernel functions and any hardware driver modules are build into a single executable which is then executed in what is known as “kernel space”, which means it has full privileged access to the underlying hardware.

The Linux kernel provides an abstraction of the hardware, along with a set of operations known as “system calls”, and controls a huge number of functions such as process control and process scheduling, reading and writing to and from the system memory, virtual memory management, and virtual file system management. In addition to these, the Linux kernel uses a host of “kernel modules”, which provide device specific and operating system function drivers, and it is these that make access to sound cards, video cards, network interfaces, keyboards, USB and eSata devices possible.

System Libraries

The “libraries” are a collection of computer code that provide a way of doing common tasks, such as reading or writing a from a file, or opening a network connection, and these are used to make programming simpler and to ensure that all programs which use a particular library interface with the kernel and other programs the same way.

All Linux systems have a number of system libraries that are used by the utility and the shell programs to to do their work. Some of these libraries are dedicated to working within the “user space” and some of them provide an abstraction of the kernel system calls such that operations that might take several system calls to achieve only require one call to the library code.

Command Shell and command line utilities

While having a good kernel is essential, there is (usually – some kernel researches out there disagree) a need to have a number of utilities that will allow the users of the system to do useful things.

These utilities most commonly consist of a command shell and a number binary programs that are used by one or more users to make request for access to system resources or for the kernel to do certain things via a set of system libraries and system calls.

Most Linux distributions use a Linux Standards Base to define its functions common a set of standard utilities and libraries, which allow users of the system to do things like mount and unmount file systems, list and access contents of a file systems, start and stop processes, load and unload kernel driver modules, and many other tasks.

Graphical User Interfaces

The “X windows system” is the most commonly used graphical user interface system provided by various Linux distributions, and it is most commonly installed on Linux based desktops and laptops, an some tablets, while most Linux based PDAs and mobile phones, including the Google Android based ones, have their own dedicated graphical user interface engines.

At its core the X window system consists of an ‘x-server’ process that provides the abstraction of the graphics hardware and input devices to a “desktop environment” (such as Gnome, XFCE, Unity and KDE for example) and/or a “window manager” process (such as fvwm, twm, Window Maker or awesomeWM to name a few) that uses the ‘x server’ and the kernel graphics hardware to paint the actual look and feel of the graphical user interface.

The various graphical user interfaces that are possible on a system Linux come with a suite of applications and utilities to make the system look much prettier, more functional, or simply easier to use.

While not actually necessary for a fully functional Linux system, a graphical user interface can be of great help to the human user of the system, and will enable them get the most out of the system.

This concludes the initial look at Linux systems. In future instalments of this series we will take an in-depth look the kernel and kernel modules, system calls, the shell and various system utilities and what is the difference between a “desktop environment” and a “window manager”.

What is Linux?

“What is Linux?”

Linux University is about “Linux and Open Source Software Advocacy and Education”. However, it is very hard to do advocacy and education successfully, unless one has a very clear idea what is it that one is an advocate for and what is it that one educates others about. In this article we will attempt to explore the question “What is Linux?” to provide you with some idea of what it is we are talking about.

To someone new to the world of Linux and Open Source Software, the term “Linux” means a simple and narrowly defined thing. Most likely when they think about Linux, the thing that if first and foremost there is a bundle of software they have installed on their computer.

In fact, as Linux University learnt in course of our research, “What is Linux?” is a question that quite is difficult to answer in a simple and and straight forward manner. This is because the term – Linux – and therefore the question itself, means different things to different people. This is why we need to explore the various answers, so that we get to better understand and define the range of topics we will need to cover.

Linux University has taken some time to consider this question, and we believe that the term “Linux” means (at least) four very different but very also very closely related things. Here is what we found:

Linux – the name.

In the United States, the name Linux is a trademark registered to Linus Torvalds, the “inventor” and principal author of the Linux kernel.

Linux – the operating system.

Linux is a unix-like operating system based around the Linux kernel and distributed under the model of free and open source software. In this context, here at Linux University we believe that the term Linux refers to two distinct but closely bound entities.

  • First is the Linux kernel itself, classified as a monolithic type operating system kernel. The first version of the Linux kernel was released by Linus Torvalds, in 1991, and in the 20 years since then, it has been widely developed and updated.
  • Second is the Linux distribution, which is an integrated collection of Linux kernel and associated support tools and software packages that turn a supported platform into a Linux system.

As at the time of the writing of this article Linux University have counted no fewer than 25 supported platforms and a quick survey of the environment shows that Linux is used on systems of all sizes, from mobile smartphones that use the Linux based Google Android operating system, through embedded and appliance devices such as ADSL modems and routers or media player appliances, through the large corporate system to the high end research supercomputers.

Linux – the expression of the Open Source Software concept.

Here, at Linux University, we recognise the fact that to many people out there, Linux is an embodiment and an expression of a concept and a philosophy of the Free and Open Source Software.

This is because the Linux kernel and most of the software that makes up all of the Linux Distributions is made available under a Free and Open Source Software licence of soe sort and like the Linux kernel itself, each of the software packages that makes up a Linux system is written, maintained and updated by a community of individuals, all of whom contribute their time, skills and other resources to the particular project they are involved in, while making the result of their labours available to others.

Linux – the software product.

There are many Linux distributions available through the world. In fact when asked about Linux, most people will point to one of these distributions and say: ”this is Linux”. Linux University research shows that in fact each Linux distribution is a software product, as each of these a varying mix of software, education and training services, product updates and maintenance and professional services – all of which are the core components of a software product.

This “software product” based model is so successful, that by being able to offer the Linux software “for free” (or at a very low cost), companies such as Red Hat and Novell have built a billion dollar business by offering Linux operating system, bundled together subscription based support, extensive software testing and hardware platform certification, a suite of professional services and education and training services.

This concludes inaugural Linux University article. We hope that you have found it useful and informative. In future articles we will explore a lot of the concepts we mentioned here in more depth.