Top

A Linux User Reference

Search tips
  • search ignores words that are less than 4 characters in length
  • searches are case insensitve
  • if a search does not return anything try it in Boolean mode then Query expansion mode by checking the appropriate radio button e.g. searching for 'cron' in just the Administration category returns nothing - presumably because the 50% threshold is reached. Boolean mode ignores this threshold so a search for 'cron' returns several hits
  • in Boolean mode preceding a word with a '+' means the result must include that word, a '-' means it must not
  • in Boolean mode '+crontab -anacron' means match articles about crontab that DO NOT mention anacron
  • to match a phrase e.g. 'manage system' check the Boolean mode radio button and enclose the phrase in quotes "some phrase ..."
  • in Query expansion mode the search context is expanded beyond the keywords you entered - relevancy of hits may well be degraded

THE SHELL

Man pages

  • Set manual pages paging program
    • Plain text manual pages require a Paging program.
    • The two most common are more (one more screen) or less (less is more), often selected via a profile script.

    Set 'more' as the man page paging program

    # export PAGER=more
                           (or)
    # export MANPAGER=more
    

    'man' uses 'pager' which overrides MANPAGER which overrides PAGER - if any are set.

    On debian, ubuntu alternatives are used

    $ file /usr/bin/pager
    /usr/bin/pager: symbolic link to `/etc/alternatives/pager'
    
    $ ls -al /etc/alternatives/pager
    lrwxrwxrwx 1 root root 9 Jul 29 19:17 /etc/alternatives/pager -> /bin/less
                                                                                 (or)
    $ update-alternatives --query pager
    Name: pager
    Link: /usr/bin/pager
    Slaves:
     pager.1.gz /usr/share/man/man1/pager.1.gz
    Status: auto
    Best: /bin/less
    Value: /bin/less
    
    ....
    

    Change pager to use 'more'

    $  sudo update-alternatives --config pager
    [sudo] password for mark: 
    There are 3 choices for the alternative pager (providing /usr/bin/pager).
    
      Selection    Path            Priority   Status
    ------------------------------------------------------------
    * 0            /bin/less        77        auto mode
      1            /bin/less        77        manual mode
      2            /bin/more        50        manual mode
      3            /usr/bin/pg      10        manual mode
    
    Press enter to keep the current choice[*], or type selection number: 2
    update-alternatives: using /bin/more to provide /usr/bin/pager (pager) in manual mode
    
    $ update-alternatives --query pager
    Name: pager
    Link: /usr/bin/pager
    Slaves:
     pager.1.gz /usr/share/man/man1/pager.1.gz
    Status: manual
    Best: /bin/less
    Value: /bin/more
    .....
    

    Change it back to 'less'

    $ sudo update-alternatives --auto pager
    update-alternatives: using /bin/less to provide /usr/bin/pager (pager) in auto mode
    

    See man pages for 'update-alternatives'.

  • Manual page sections
    Section Description
    Name Name of manual entry along with a brief description
    Synopsis Syntax/usage format
    Description Description of the item
    Options Detailed information on the command-line options
    Return Values Information on function return values
    Bugs Descriptions of unusual program behaviour or known defects
    Files Related files e.g. Configuration files
    Copyrigh tHow item can be distributed or protected
    Authors Authors
  • Format and display system manual pages
    /usr/bin/man

    See the man pages - some options change their meaning over time.

    man [options] [section] name ...
    
    Options:
     -a                Find all matching entries.  CTRL-c terminates current page,
                       next is displayed
     -d                Print debugging information
     -D                As for -d, but also display the pages
     -f                Same as whatis (1)
     -h                Help
     -k                Same as apropos (1)
     -K                Search for a string in all pages
     -t                Use troff to format pages for printing
     -w                Print location of man page(s) that would be displayed 
                       (same as 'manpath' cmd)
                       (if no name: print directories that would be searched)
     -W                As for -w, but display filenames only
     -C file           Use 'file' as configuration file
     -M path           Set search path for manual pages to 'path'
     -P pager          Use program 'pager' to display pages
     -S list           Order in which sections are searched, ';' separated section
                       list, overrides MANSECT
     -m system         Search for alternate system's man pages
    
    Sections:
     1                 User programs
     2                 System calls
     3                 Library calls
     4                 Special files (e.g. /dev)
     5                 File formats
     6                 Games
     7                 Miscellaneous
     8                 System administration
     9                 Kernel
     n                 New documentation
     o                 Old documentation
     l                 Local documentation
    

    If [section] is omitted the first hit is displayed.

    Display the location of 'ls' command's man pages

    $ man -w ls
    /usr/share/man/man1/ls.1.gz
    

    Display location of all man pages that start with man

    $ man -aw man
    /usr/share/man/en/man1/man.1.gz
    /usr/share/man/man1/man.1.gz
    /usr/share/man/man1p/man.1p.gz
    /usr/share/man/man7/man.7.gz
    

    Display the current man search path

    $ man -w
    /usr/kerberos/man:/usr/local/share/man:/usr/share/man/en:/usr/share/man
    

    Display section(7) of man's man pages and use 'less' as the pager

    # man -P less 7 man
    
  • Location of man page files and directories
    • Man page directories and files can be anywhere thought is usually in /usr/share/man.
    • It's configuration file (/etc/man.config or /etc/manpath.config) contains directives including which directories to search, what pager to use.
    • The MANPATH variable is populated after the it's configuration file is read.

    Ubuntu default configuration - /etc/man.config (dated), /etc/manpath.config

    .....
    # Every automatically generated MANPATH includes these fields
    MANPATH /usr/man
    MANPATH /usr/share/man
    .....
    
    # a mapping between executable's paths and their man pages
    MANPATH_MAP     /bin                    /usr/share/man
    MANPATH_MAP     /sbin                   /usr/share/man
    MANPATH_MAP     /usr/bin                /usr/share/man
    .....
    
    # Configure 'helper' program behaviour
    TROFF           /usr/bin/groff -Tps -mandoc
    NROFF           /usr/bin/nroff -c -mandoc 2>/dev/null
    EQN             /usr/bin/geqn -Tps
    .....
    PAGER           /usr/bin/less -is
    BROWSER         /usr/bin/less -is
    HTMLPAGER       /bin/cat
    CAT             /bin/cat
    .....
    
    # Default manual sections, default search order
    # when no '-S' option or MANSECT variable is unset
    MANSECT         1:1p:8:2:3:3p:4:5:6:7:9:0p:n:l:p:o:1x:2x:3x:4x:5x:6x:7x:8x
    .....
    # Use given decompressor for file extensions.  Must act as a filter
    .gz             /usr/bin/gunzip -c
    .bz2            /usr/bin/bzip2 -c -d
    .z
    .Z              /bin/zcat
    .F
    .Y
    .....
    
    # Enable/disable makewhatis database cron updates
    # If MAKEWHATISDBUPDATES variable is uncommented and set to n or N, cron scripts
    # /etc/cron.daily/makewhatis.cron
    # /etc/cron.weekly/makewhatis.cron
    # will not update makewhatis database.  Otherwise the database will be updated.
    #MAKEWHATISDBUPDATES    n
    .....
    

    This file could be dated as it is from a '/etc/man.config' example.

  • Determine man pages search path
    /usr/bin/manpath
    • Determine search path for manual pages.
    • If $MANPATH is set 'manpath' will display its contents and issue a warning, if not set 'manpath' will determine a suitable manual page hierarchy search path and display the results.
    • The path is determined using information gained from the man-db configuration file (/etc/manpath.config) and the user's environment.
    manpath [-qgdc] [-m system[, ...]] [-C file]
    
    Options:
     -q | --quiet                       Do not issue warnings.
     -d | --debug                       Print debugging information.
     -c | --catpath                     Produce a catpath as opposed to a manpath.
     -g | --global                      Produce a manpath consisting of all paths named
                                        as 'global' within the man-db configuration file.
     -m system[, ...]
        | --systems=system[, ...]       Include other accessible system's man page
                                        hierarchies.
     -C file | --config-file=file       Use configuration file not default of ~/.manpath.
     -h | --help
     -V | --version
    

    Display the current man search path

    $ manpath
    /usr/local/man:/usr/local/share/man:/usr/share/man
    
  • Create, update the manual page index caches
    /usr/bin/mandb

    See man pages for more information.

    $ mandb --help
    Usage: mandb [OPTION...] [MANPATH]
    
      -c, --create               create dbs from scratch, rather than updating
      -C, --config-file=FILE     use this user configuration file
      -d, --debug                emit debugging messages
      -f, --filename=FILENAME    update just the entry for this filename
      -p, --no-purge             don't purge obsolete entries from the dbs
      -q, --quiet                work quietly, except for 'bogus' warning
      -s, --no-straycats         don't look for or add stray cats to the dbs
      -t, --test                 check manual pages for correctness
      -u, --user-db              produce user databases only
      -?, --help                 give this help list
          --usage                give a short usage message
      -V, --version              print program version
    
    Mandatory or optional arguments to long options are also mandatory or optional
    for any corresponding short options.
    

    Test in debug mode

    $ mandb -d --test
    ruid=1000, euid=1000
    ++priv_drop_count = 1
    From the config file /etc/manpath.config:
    
    Mandatory mandir `/usr/man'.
    Mandatory mandir `/usr/share/man'.
    Mandatory mandir `/usr/local/share/man'.
    Path `/bin' mapped to mandir `/usr/share/man'.
    .....
    

    Update manual page index cache

    $ mandb ; echo $?
    0 man subdirectories contained newer manual pages.
    0 manual pages were added.
    0 stray cats were added.
    0 old database entries were purged.
    0
    
  • Display manual page descriptions
    /usr/bin/whatis

    Searches the manual page names and displays the manual page descriptions of any name matched.

    $ whatis --help
    Usage: whatis [OPTION...] KEYWORD...
    
      -d, --debug                emit debugging messages
      -v, --verbose              print verbose warning messages
      -r, --regex                interpret each keyword as a regex
      -w, --wildcard             the keyword(s) contain wildcards
      -l, --long                 do not trim output to terminal width
      -C, --config-file=FILE     use this user configuration file
      -L, --locale=LOCALE        define the locale for this search
      -m, --systems=SYSTEM       use manual pages from other systems
      -M, --manpath=PATH         set search path for manual pages to PATH
      -s, --sections=LIST, --section=LIST
                                 search only these sections (colon-separated)
      -?, --help                 give this help list
          --usage                give a short usage message
      -V, --version              print program version
    
    Mandatory or optional arguments to long options are also mandatory or optional
    for any corresponding short options.
    

    Get a short description about a command

    $ whatis find
    find (1)                - search for files in a directory hierarchy
    
    $ whatis whatis
    whatis (1)           - display manual page descriptions 
    
  • Search manual pages
    /usr/bin/apropos
    • Similar to 'whatis', searches the manual page names and descriptions.
    • Some options allow for greater definition on how keyword(s) should be interpreted i.e. as a pattern, exactly, wildcard.
    apropos [options] keyword ...
    

    Get a description of man page entries for files starting with wpa_

    $ apropos wpa_
    wpa_action (8)      - wpa_cli action script
    wpa_background (8)  - Background information on Wi-Fi Protected \
                          Access and IEEE 802.11i
    wpa_cli (8)         - WPA command line client
    ....
    
  • Create the whatis database
    /usr/bin/makewhatis

    Command usage

    makewhatis [-u] [-v] [-w] 
               [-s sections ] 
               [-c [catpath]] 
               [manpath]
    
    Options:
     -u                    Update database with new pages.
     -v                    Verbose output.
     -w                    Use manpath obtained from 'man --path'.
     -s sections           Looks in the sections of manpath or catpath.
     -c catpath            Preformatted manual pages located in catpath are scanned.
    

    Man page examples:

    Rebuild only /usr/X11R6/man/whatis and /usr/local/man/whatis

    # makewhatis /usr/X11R6/man /usr/local/man
    

    Rebuild all the databases, including those of the Finnish and French translations

    # LANGUAGE=fi:fr:it makewhatis -w
    
  • Two other documentation programs
    xman

    X-windows man pages interface

    yelp

    Gnome help browser

  • Informational documents
    /usr/share/doc
    • Tutorials, HOWTO guides, READMEs, FAQs or even user manuals.
    • Not part of FHS so a bit haphazard in layout and format.
    • Most files are ascii text, some in HTML, compressed or what have you.
    Info pages

    Free Software Foundation created info files, processed with the info program, from the makers of emacs.

    They provide extensive navigation facilities including the ability to jump to other sections. Search commands are more like emac's e.g. 'ctrl-s' searches forwards, 'ctrl-r' searches backwards, arrow keys move around.

    Follow links (indicated with a star) using the Enter key.

    Use vi key bindings

    $ info --vi-keys
    
  • Info page viewer
    pinfo
    • An alternative info-file viewer
    • May be included.
    • Works much like a text based web browser.
    Some pinfo commands
    
     TAB                    Move among hypertext links
     enter                  Follow hypertext link
     d                      Return to top (directory node) of the menu
     ?                      List all info commands
     p                      Move to previous page
     n                      Move to next page
     u                      Move up 1 level in texinfo directory
     q                      Quit
     h                      Primer for 1st. time users
     /string                Enter a string
     /pattern               Search forward for pattern (can be a regex)