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)*