Man

tldr; #

To get detailed help type man followed by the tool/topic you want help on:

man cd

Once open you can scroll up and down or press q to quit.

The above shows how to use the cd command:

CD(1P)                     POSIX Programmer's Manual                     CD(1P)

PROLOG
       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult  the  corresponding
       Linux  manual  page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       cd — change the working directory

SYNOPSIS
       cd [-L|-P] [directory]

       cd -

DESCRIPTION
       The cd utility shall change the working directory of the  current  shell
       execution environment (see Section 2.12, Shell Execution Environment) by
       executing the following steps in sequence. (In the following steps,  the
       symbol curpath represents an intermediate value used to simplify the de‐
       scription of the algorithm used by cd.  There  is  no  requirement  that
       curpath be made visible to the application.)

 Manual page cd(1p) line 1 (press h for help or q to quit)

Basics behind the command #

Once the command has been entered, your terminal will be filled with the pager that shows the manual you chose (if there was a man page for that tool/topic)

You should see at the very bottom of your terminal

 Manual page cd(1p) line 1 (press h for help or q to quit)

This has:

• the man page you are in,
• the line position within that man page (line number of top of screen)
• a reminder that h gives you help for the pager
• and how to quit back to your shell, q

man can be thought of as a local search engine for documentation which is then sent to less (or whatever pager has been configured/requested) to be displayed.

Moving through a man page #

As mentioned above, h will show help which will show you what navigating and searching options are possible. Rather than just repeating what the help text says, I’ll summarise what I think are the most useful but I urge you to go read the page at least once.

Navigating #

If you are familiar with vi commands, be happy as the pager uses (some of) them:

• j or cursor down is move down a line, you can use the repeat instruction so typing 12j will move down 12 lines.
• k or cursor up is move up a line, again repeat instructions can be used like 30k.
• b or w or PgUp back a screen’s worth of text, prefixing a number will alter the command however I’ve seen it do very strange things so I don’t bother with that.
• f or z or PgDn forward a screen’s worth of text, same as b for prefixing.

Searching #

• / search forwards from your current line (top line of screen), whatever you type after the / will be the term to search for once you hit enter, it will then highlight matches and you can navigate through the matches using n to find the next match (down in doc), N to find the previous (up in doc). The match will be the one on the first line of your screen.
• ? search backwards from your current line (top line of screen), same rules as /, hit enter to start, n next (so up in doc), N previous (down)
• ESC u to toggle highlighting of matches

Others #

Personally, the only others I think are useful are the !/# which can be used to execute commands which might be useful for Hacking CTFs if you have a suid flag on less or some weird access that dumps you directly into less.

I don’t use marks and I rarely find myself wanting to jump 40% of the way through the man page. Your mileage may vary.

Man page sections #

You will probably have noticed numbers in parenthesis, ( and ), when dealing with man pages. These are sections, where section means a collection of man pages. There are 9 sections as can be seen in the man page for man man man.

to specify a section to use there are a few options:

man 5 intro

man intro.5

man -s 5 intro

Note: if you don’t have an entry for intro, chances are you are missing a package (as I was until I ran pacman -Syu man-pages, this is the Arch linux package manager other distros will have different tools e.g. apt, yum, etc.)

Alternate modes #

You can pass command line args to alter the behaviour of man and make it act like other tools that I’ll talk about in a later section.

• man -f <term> is equivalent to whatis so only show exact title matches, it will show you what entries match the term however whatis has wildcard and regex support so you might want to use that instead.
• man -k <term>, is equivalent to apropos, so searches for a partial match in title or description
• man -K <term>, searches all of the man text for one or more exact matches, it also opens all the matches. The first match is opened in a pager, then you’ll need to quit the pager at which point you will be prompted to see the next match enter, skip Ctrl+D or quit completely Ctrl+c.
• man --regex <pattern> very similar to man -K but with regex capabilities.

Autocomplete #

man has autocomplete which is interesting but I’m not sure often you’d need it, maybe more useful for the c library pages when you want to look at a library to see what functions there are, for instance man tar<tab> will show something like:

tar                   tar_extract_all       tar_extract_regfile
tar_append_eof        tar_extract_blockdev  tar_extract_symlink
tar_append_file       tar_extract_chardev   tar_fd
tar_append_regfile    tar_extract_dir       tar_fdopen
tar_append_tree       tar_extract_fifo      tar.h
tar_block_read        tar_extract_file      tar_open
tar_block_write       tar_extract_glob      tar_set_file_perms
tar_close             tar_extract_hardlink  tar_skip_regfile

Configuration #

There is a configuration file for man located at /etc/man_db.conf. It basically helps man determine where to look for man pages, what default tools to use (i.e. you could change your pager here if you don’t like less) and the order or search over sections. There are other options too around cat pages and their creation/display.

The most useful part of it is probably the locations to search for man pages, this might help when installing man pages however I find that most tools can do this without me ever needing to modify this file, so most people shouldn’t need to open this file, it’s good to know it exists though.

Accompanying tools #

There are 2 helpful tools that will make navigating through the thousands of man pages a little easier, namely whatis and apropos.

whatis #

The whatis command uses the man pages to give a one line summary of a tool along with the name of the man pages it relates to. whatis searches through the name sections of the man pages to find an exact match by default and shows the description associated with any matches.

❯ whatis cd     
cd (n)               - Change working directory

❯ whatis pwd   
pwd (1)              - print name of current/working directory
pwd (n)              - Return the absolute path of the current working directory

You can use wildcard searches by passing the -w (or --wildcard) flag like so:

❯ whatis -w 'pw*'        
pw-cat (1)           - Play and record media with PipeWire
pw-cli (1)           - The PipeWire Command Line Interface
pw-dot (1)           - The PipeWire dot graph dump

Note that I use zsh shell rather than bash and I found I needed to quote the search term when using wildcards otherwise my shell tried to expand the term and failed showing me a zsh: no matches found: pw* error

You can also use regex by passing the -r (or --regex) flag.

If you want more information you would now use the man command on the result name (first column without the section number, e.g. man pw-cli.

You can get the same functionality by passing the if flag to man:

❯ man -f pwd
pwd (1)              - print name of current/working directory
pwd (n)              - Return the absolute path of the current working directory

apropos #

apropos is a very similar tool to whatis but differs by searching through the name and description of the man pages rather than just matching on exact name.

❯ apropos cd     
akaidump (1)         - Dump an AKAI media (i.e. CDROM) as disk image file to your HD.
arm-none-eabi-gcov-dump (1) - offline gcda and gcno profile dump tool
arm-none-eabi-gcov-tool (1) - offline gcda profile processing tool
avr-gcov-dump (1)    - offline gcda and gcno profile dump tool
avr-gcov-tool (1)    - offline gcda profile processing tool
BN_gcd (3ssl)        - arithmetic operations on BIGNUMs
cd (n)               - Change working directory
cd-convert (1)       - Color Manager Testing Tool
...
# many more entries cut from results for brevity

It also supports wildcard or regex searches by using either the --wildcard/-w flag or the --regex/-r. Don’t forget to add quotes around your search term/regex though otherwise it might return no results (the shells will eat any unquoted asterisks or question marks as it will think of them as glob patterns). It should look something like this:

apropos --regex '.*snoop'     

The above will show any of the bpftrace snoop tools, if you have bpftrace installed.

Alternative tools/techniques #

Obviously there is the internet (I include AI with this) which is an amazing source of help, there are even man pages hosted on the internet:

• Arch’s man pages for those like me on Arch, these are in addition to Arch’s docs which are pretty muc the best on the internet.

• Debian’s man pages would be my choice of non-rolling distro

• FreeBSD (and I’m sure other editions of BSD) have man pages since it is also part of the Unix ecosystem.

• Finally, I’ve only just discovered this but am thinking of making it my default bookmark for man pages, the manned.org have man pages for a few distros and also have links to other sites hosting man pages. Very nice.

There are many online versions of man pages, if you want to see a comparison of some of them, have a look at this gist.

However there are a few other ways to get help that run locally too.

info #

info is a complex alternative to man, it can actually display man pages but also has its own library of “info” documents. On it’s own, info will load up it’s directory of pages

File: dir,      Node: Top,      This is the top of the INFO tree.

This is the Info main menu (aka directory node).
A few useful Info commands:

  'q' quits;
  'H' lists all Info commands;
  'h' starts the Info tutorial;
  'mTexinfo RET' visits the Texinfo manual, etc.

* Menu:

Archiving
* Cpio: (cpio).                 Copy-in-copy-out archiver to tape or disk.
* Tar: (tar).                   Making tape (or disk) archives.
* Xorrecord: (xorrecord).       Emulates CD/DVD/BD program cdrecord
* Xorriso: (xorriso).           Burns ISO 9660 on CD, DVD, BD.
* Xorriso-dd-target: (xorriso-dd-target).
                                Device evaluator and disk image copier for
                                  GNU/Linux
* Xorriso-tcltk: (xorriso-tcltk).
-----Info: (dir)Top, 2693 lines --Top---------------------------------------------
No 'Prev' or 'Up' for this node within this document

You can also filter the menu using info -a tar to find all tar related documents, or search like apropos for a string using info -k bpf for any documents with the “bpf” string within it. info is as complex as man, I think it’s more popular in the Emacs half of the Linux user base (I might be wrong about that). If you want to know more, why not try man info or info info if you feel brave.

–help #

Passing a --help argument to a command should usually give you a quick cheat sheet style output for the command’s options.

help (bash builtin) #

This won’t work for me on zsh, but if you are a bash user then you have access to this command. It is a basic list of shell commands that will work in bash, you can just run help to show all the commands or help function where we want to learn more about the function command.

tldr #

Using a tool like tldr will give you common examples of commands, I personally use the rust based version called tealdeer. tldr doesn’t install any man pages, so man tldr won’t work, it does however support the --help argument and it can show common uses for itself with tldr tldr.