.. include:: ../header.txt

.. _man:

Using man
============

:t:`Linux for Programmers and Users`, Section 3.6
   
.. index:: man 
.. program:: man 
.. describe:: man

    Displays documentation of commands, configuration files, system calls and
    library functions.

SYNOPSIS
   :command:`man` [section] *name*

   :command:`man` -k *topic*

.. cmdoption:: -k topic

   Search the manual pages for documentation related to the specified topic.
   
Man pages are organized in a number of sections. 
Commands are found in Section 1.  If no section is specified, the first section
containing a page for the specified name is displayed.  The typical contents of
the manual page sections are as follows.

1. User Commands
2. Systems Calls
3. Library Functions
4. Special Files
5. File Formats
6. Games
7. Miscellaneous
8. System Administration commands
9. Kernel interfaces

You may need to use section number when entry exists in multiple sections. For
example, :command:`passwd` is documented in section 1 and 5.  The 
:command:`printf` command is documented in sections 1, 1p, 3 and 3p.

.. note::

    Manual page documentation is not available for most internal shell commands
    -- try ``help cd``.

Use ``man man`` first to know how :command:`man` should be used.

.. note:: 

    Even though :command:`man` is mainly treated as a reference manual, you can
    use it as a guide for not-too-complex commands. Most commands occur in
    Section 1, so ``man command`` generally retrieves the correct man
    page for the command.

.. index:: manual page, Backus--Naur Form (BNF)
.. _bnf:

Understanding a man Page
---------------------------

The specification for the allowed usage of each command is documented in the
command's manual page according to the Backus--Naur Form (BNF).  - See
:ref:`bnf` and Figure A-5, pg 598.

  ==================  =======================================================
     Sequence              Meaning
  ==================  =======================================================
   [ strings ]         Strings may appear zero or one times.
   { strings }*        Strings may appear zero or more times.
   { strings }+        Strings may appear one or more times.
   string1|string2     string1 or string2 may appear.
   -optionlist         Zero or more single letter options may follow a dash.
  ==================  =======================================================

  
.. seealso:: :ref:`cmd_struct` for details on types of command arguments.

Example: ``wc [ -c | -m | -C ] [ -lw ] [ file ... ]``

* Most useful information is available in **SYNOPSIS** and **DESCRIPTION**.

* When options are grouped in [ ] without a \|, one or more of them can be
  used.  (``-l``, ``-w`` and ``-lw`` are valid.)

* The \| signifies an OR condition. (Only one of -c, -m or -C can be used.)

* The ... means that multiple occurrences of the preceding item are
  possible. (:command:`wc` can be used with multiple files.)

* **EXIT STATUS** indicates values returned on error.

.. note:: 

    The man documentation lists all options that can be used with a command.
    But must you use an option if it solves the problem? That depends on
    whether the application needs to be portable or not. Portability often
    means POSIX-compliance, so you may not use an option even if it solves the
    problem.

    The exit status returned by a program has importance when you use the
    program in a shell script. Mention that it often makes sense to invoke a
    command B only after command A has completed execution in an expected
    manner. The shell scripting language can check the exit status to determine
    if a program behaved in the way it was meant to.

Related Commands
--------------------

.. index:: help, whatis, apropos, shell built-in commands

.. program:: help
.. describe:: help

    Displays documentation for BASH shell built-in commands.

SYNOPSIS
    :command:`help` *command*  ...


.. program:: whatis
.. describe:: whatis

    Displays a short description of each command listed.

SYNOPSIS
    :command:`whatis` *command*  ...

::

    $ whatis login set setenv
    login(1) -sign on
    set(1) -set runtime parameters for session
    setenv (1) -change or add an environment variable


.. program:: apropos
.. describe:: apropos

    The same as ``man -k``.  It displays a list of manual pages that document
    the keyword.

SYNOPSIS
    :command:`apropos` keyword