sebastiano.tronto.net

Source files and build scripts for my personal website
git clone https://git.tronto.net/sebastiano.tronto.net
Download | Log | Files | Refs | README

man.md (9819B)


      1 # The man page reading club: man(1)
      2 
      3 *This post is part of [series](../../series)*
      4 
      5 I have been using Linux as my main operating system for the
      6 last 14 years, and as my only one for the last 10. Needless
      7 to say, I really like it. However, at the end of last year I
      8 have decided to use [OpenBSD](https://www.openbsd.org/) for my
      9 [VPS](https://en.wikipedia.org/wiki/Virtual_private_server). I had 3
     10 main reasons (spoiler: security is not one of them):
     11 
     12 * It is still UNIX: most things I am used to do with the Linux command
     13   line work exactly the same in other UNIX-like operating systems, so
     14   I would not have to learn everything from scratch.
     15 * Comprehensive base installation: a lot of things I needed,
     16   such as an http server, were already included in the base system.
     17   This results in a great consistency with the rest of the OS,
     18   for example in terms of configuration file location and syntax.
     19 * Local documentation, i.e. manual pages: having a well-written documentation
     20   attached to any piece of software you install is something that I find
     21   very valuable. I do not like the idea of having to rely on external
     22   documentation, which may or may not be specific to the OS I am using
     23   and to the specific version of the software I have installed, and
     24   googling for solutions is always a hit or miss.
     25 
     26 As I was expecting, after some time using it I was really pleased with
     27 the quality of OpenBSD's manual pages, to the point that I am sometimes
     28 using them (by ssh-ing into my server) also when I am working or writing
     29 [scripts](https://git.tronto.net/scripts) for my Linux machine.
     30 
     31 So I thought that it would be nice to take once in a while one of these
     32 manual pages, read it, and share what I learned with other people.
     33 Hence I decided to start this blog-series: "The man page reading club".
     34 
     35 ## Nuclear Apocalypse
     36 
     37 I tried to find a nice setting for this series, a funny story to introduce
     38 each of these technical posts, but I could not come up with any good idea.
     39 Luckily, a couple of weeks ago I read the short post
     40 [OpenBSD is the Perfect OS post Nuclear Apocalypse](https://confuzeus.com/shorts/openbsd-nuclear-apocalypse/)
     41 and I found it to be exactly what I was looking for!
     42 
     43 *So here you are, in a cozy underground bunker during a Nuclear
     44 Apocalypse. There is enough food and electricity for everyone, but
     45 of course no Internet. After a couple of days of social chit-chat
     46 with your new roommates you find out that you have pretty much
     47 nothing in common with them, so you turn to your trusty laptop and
     48 you install OpenBSD 7.1 - the last version released before the apocalypse.*
     49 
     50 ```
     51 From: deraadt@do-not-reply.openbsd.org (Theo de Raadt)
     52 Subject: Welcome to OpenBSD 7.1!
     53 ```
     54 
     55 *Says your screen, after you login and type `mail`.*
     56 
     57 ```
     58 For more information on how to set up your OpenBSD system, refer to the
     59 "afterboot" man page.
     60 ```
     61 
     62 *The what?*
     63 
     64 ```
     65 If you are not familiar with how to read man pages, type "man man"
     66 at a shell prompt and read the entire thing.
     67 ```
     68 
     69 *Sounds like a good idea, let's do it!*
     70 
     71 ```
     72 $ man man
     73 ```
     74 
     75 ## man(1)
     76 
     77 *Follow along at [man.openbsd.org](https://man.openbsd.org/OpenBSD-7.1/man)*
     78 
     79 The first interesting thing we see in this manual page is a thing called
     80 *synopsis*:
     81 
     82 ```
     83 SYNOPSIS
     84 	man [-acfhklw] [-C file] [-M path] [-m path] [-S subsection]
     85 	    [[-s] section] name ...
     86 ```
     87 
     88 This explains how to invoke the `man` command. The parts within square brackets
     89 are optional, and the other words such as `path` and `section` are going to be
     90 explained later in this page.
     91 
     92 A short description the tells us that `man` is used to display manual pages.
     93 It is followed by a detailed explanation of what each option does.
     94 Let's look at some of them!
     95 
     96 ```
     97 -c	Copy the manual page to the standard output instead of using
     98 	less(1) to paginate it.  This is done by default if the standard
     99 	output is not a terminal device.
    100 ```
    101 This option is not very interesting to use because of the last sentence:
    102 it is the default behavior when you need it (for example, when you pipe
    103 the output to another program). It is however interesting to read its
    104 description, because it reveals a little detail of how `man` works.
    105 Namely, that every time we open a man page we are also calling `less`!
    106 
    107 ```
    108 -h	Display only the SYNOPSIS lines of the requested manual pages.
    109 	Implies -a and -c.
    110 ```
    111 
    112 This can be useful for commands with a more complicated syntax.
    113 
    114 ```
    115 -k	A synonym for apropos(1).  Instead of name, an expression can be
    116 	provided using the syntax described in the apropos(1) manual.
    117 	By default, it displays the header lines of all matching pages.
    118 ```
    119 
    120 This sounds like some kind of search function, like a post-nuclear Google.
    121 Indeed, `man apropos` tells us:
    122 
    123 ```
    124 NAME
    125 	apropos, whatis - search manual page databases
    126 ```
    127 
    128 The page `apropos(1)` is worth a read, but I won't write a dedicated post.
    129 This utility supports searching by regular expressions and by "`mdoc` macros".
    130 If you don't know what they are, worry not: it is all well explained in
    131 `apropos(1)`. The page also contains a lot of examples, which is always
    132 appreciated.
    133 
    134 Now back to `man man`!
    135 
    136 ```
    137 [-s] section
    138 	Only select manuals from the specified section. The currently
    139 	available sections are:
    140 
    141 		1	General commands (tools and utilities).
    142 		2	System calls and error numbers.
    143 		3	Library functions.
    144 		3p	perl(1) programmer's reference guide.
    145 		4	Device drivers.
    146 		5	File formats.
    147 		6	Games.
    148 		7	Miscellaneous information.
    149 		8	System maintenance and operation commands.
    150 		9	Kernel internals.
    151 ```
    152 Manual pages are divided into sections: they are the mysterious numbers in
    153 parentheses after a command's name, like in `less(1)`. There can be pages
    154 with the same name in different sections, and with this option you can specify
    155 which one you want. For example `man printf` shows the `printf(1)` page, for
    156 the UNIX command with the same name, while `man -s 3 printf` shows the manual
    157 page for the `printf()` C library function. The syntax for this option is
    158 slightly unusual in that the `-s` itself is optional: `man 3 printf` does
    159 the same as `man -s 3 printf`.
    160 
    161 One might be tempted to think that if no section is specified, the page in the
    162 lowest-number section is shown. However:
    163 
    164 ```
    165 Within each directory, the search procedes according to the following list
    166 of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p. The first match found is shown.
    167 ```
    168 
    169 The `man` program also behaves differently depending on the value of
    170 some environment variables. For example
    171 
    172 ```
    173 MANPAGER Any non-empty value of the environment variable MANPAGER is
    174          used instead of the standard pagination program, less(1).
    175          ...
    176 
    177 PAGER    Specifies the pagination program to use when MANPAGER is not
    178          defined.  If neither PAGER nor MANPAGER is defined, less(1) is
    179          used.
    180 ```
    181 
    182 It looks like the variable `MANPAGER` is read only by `man`, while `PAGER`
    183 may be understood by other commands as well. But how do we set environment
    184 variables? One way to do this is shown in the `EXAMPLES` section:
    185 
    186 ```
    187 Read a typeset page in a PDF viewer:
    188 
    189 	$ MANPAGER=mupdf man -T pdf lpd
    190 ```
    191 
    192 Now you should complain, because I did not tell you about the `-T` option!
    193 In fact I skipped this line:
    194 
    195 ```
    196 The options -IKOTW are also supported and are documented in mandoc(1).
    197 ```
    198 
    199 A quick look at the `mandoc(1)` page tell us that
    200 the most interesting of these options are `-T`, which we have just seen,
    201 and `-O`, which allows to tune some formatting settings. For example
    202 ```
    203 man -O width=50 man
    204 ```
    205 shows you a man page using only 50 columns, while
    206 ```
    207 man -O tag=EXAMPLES man
    208 ```
    209 shows you the `man(1)` page, but starting from the `EXAMPLES` section
    210 (you can still scroll back up to the beginning of the page).
    211 
    212 Back to `man man`.
    213 
    214 ```
    215 STANDARDS
    216 	The man utility is compliant with the IEEE Std 1003.1-2008 ("POSIX.1")
    217 	specification.
    218 
    219 	The flags [-aCcfhIKlMmOSsTWw], as well as the environment variables
    220 	MACHINE, MANPAGER, and MANPATH, are extensions to that specification.
    221 ```
    222 
    223 This means that all of the stuff we read in this manual page, except for the
    224 very basic functionality of `man` - showing manual pages - is not
    225 POSIX-standard, and might be different on other systems. Be sure to check
    226 what your version of `man` does before assuming that it will behave the same
    227 as the OpenBSD one!
    228 I find it very nice that the OpenBSD man pages always tell you which parts
    229 are standard (and thus you can expect to work in the same way on other
    230 UNIX-like OSes) and which are OpenBSD-specific. It makes writing
    231 portable scripts much easier!
    232 
    233 ## Conclusions
    234 
    235 `man` is a straightforward utility and most of the time you are just going
    236 to use it by typing `man command`. However, reading this page I was still
    237 able to learn new stuff - such as the `-h` and `-O` options and the fact
    238 that `apropos` supports searching by regular expressions and tags.
    239 I hope you have learnt something new too.
    240 
    241 As you can see I have skipped a lot of things, including all the parts
    242 related to the `MANPATH`. This post does not want to
    243 be a comprehensive tutorial on the `man` command, just a
    244 survey of the subjectively most useful parts of the manual.
    245 
    246 For the next post I will either take one of the pages that was referenced
    247 here, such as `less(1)`, or dive into more exciting stuff with something
    248 like `sh(1)`.
    249 
    250 Stay tuned!
    251 
    252 ## Update 2022-09-05
    253 
    254 In [a more recent blog post](../2022-09-05-man-col) I comment on a part
    255 of the manual that I skipped, although it is actually useful for writing
    256 these blog entries:
    257 
    258 ```
    259 When using -c, most terminal devices are unable to show the
    260 markup.  To print the output of man to the terminal with markup
    261 but without using a pager, pipe it to ul(1).  To remove the
    262 markup, pipe the output to col(1) -b instead.
    263 ```
    264 
    265 If you are curious, check the [new post](../2022-09-05-man-col)!
    266 
    267 *Next in the series: [more(1)](../2022-06-08-more)*