1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org> 2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 3 .\" Copyright (c) 1980 Regents of the University of California. 4 .\" The Berkeley software License Agreement specifies the terms and conditions 5 .\" for redistribution. 6 .Dd Jul 18, 2014 7 .Dt MAN 1 8 .Os 9 .Sh NAME 10 .Nm man 11 .Nd find and display reference manual pages 12 .Sh SYNOPSIS 13 .Nm 14 .Op Fl 15 .Op Fl adFlrt 16 .Op Fl T Ar macro-package 17 .Op Fl M Ar path 18 .Op Fl s Ar section 19 .Ar name ... 20 .Nm 21 .Op Fl M Ar path 22 .Op Fl s Ar section 23 .Fl k 24 .Ar keyword 25 .Ar ... 26 .Nm 27 .Op Fl M Ar path 28 .Op Fl s Ar section 29 .Fl f 30 .Ar 31 .Nm 32 .Op Fl M Ar path 33 .Fl w 34 .Sh DESCRIPTION 35 The 36 .Nm 37 command displays information from the reference manuals. It 38 displays complete manual pages that you select by 39 .Ar name , 40 or one-line summaries selected either by 41 .Ar keyword 42 .Pq Fl k , 43 or by the name of an associated file 44 .Pq Fl f . 45 If no manual page is located, 46 .Nm 47 prints an error message. 48 .Ss "Source Format" 49 Reference Manual pages are marked up with either 50 .Xr man 5 , 51 or 52 .Xr mdoc 5 53 language tags. The 54 .Nm 55 command recognizes the type of markup and 56 processes the file accordingly. 57 . 58 .Ss "Location of Manual Pages" 59 . 60 The online Reference Manual page directories are conventionally located in 61 .Pa /usr/share/man . 62 Each directory corresponds to a 63 section of the manual. Since these directories are optionally installed, they 64 might not reside on your host. You might have to mount 65 .Pa /usr/share/man 66 from a host on which they do reside. 67 The 68 .Nm 69 command reformats a page whenever it is requested. 70 .Pp 71 If the standard output is not a terminal, or if the 72 .Fl 73 flag is given, 74 .Nm 75 pipes its output through 76 .Xr cat 1 . 77 Otherwise, 78 .Nm 79 pipes its output through a pager such as 80 .Xr more 1 81 to handle paging and underlining on the screen. 82 .Sh OPTIONS 83 The following options are supported: 84 .Bl -tag -width indent 85 .It Fl a 86 Shows all manual pages matching 87 .Ar name 88 within the 89 .Ev MANPATH 90 search path. Manual pages are displayed in the order found. 91 .It Fl d 92 Debugs. Displays what a section-specifier evaluates to, method used for 93 searching, and paths searched by 94 .Nm . 95 .It Fl f Ar file ... 96 Attempts to locate manual pages related to any of the given 97 .Ar file 98 names. It strips the leading path name components from each 99 .Ar file , 100 and then prints one-line summaries containing the resulting basename or names. 101 This option also uses the 102 .Pa whatis 103 database. 104 .It Fl F 105 This option is present for backwards compatibility and is documented 106 here for reference only. It performs no function. 107 .It Fl k Ar keyword ... 108 Prints out one-line summaries from the 109 .Pa whatis 110 database (table of contents) that contain any of the given 111 .Ar keyword . 112 The 113 .Pa whatis 114 database is created using the 115 .Fl w 116 option. 117 .It Fl l 118 Lists all manual pages found matching 119 .Ar name 120 within the search path. 121 .It Fl M Ar path 122 Specifies an alternate search path for manual pages. The 123 .Ar path 124 is a colon-separated list of directories that contain manual page directory 125 subtrees. For example, if 126 .Ar path 127 is 128 .Pa /usr/share/man:/usr/local/man , 129 .Nm 130 searches for 131 .Ar name 132 in the standard location, and then 133 .Pa /usr/local/man . 134 When used with the 135 .Fl k , 136 .Fl f , 137 or 138 .Fl w 139 options, the 140 .Fl M 141 option must appear first. Each directory in the 142 .Ar path 143 is assumed to contain subdirectories of the form 144 .Pa man* , 145 one for each section. This option overrides the 146 .Ev MANPATH 147 environment variable. 148 .It Fl r 149 Reformats the manual page, checking for formatting errors, but does not 150 display it. 151 .It Fl s Ar section 152 Specifies sections of the manual for 153 .Nm 154 to search. The directories searched for 155 .Ar name 156 are limited to those specified by 157 .Ar section . 158 .Ar section 159 can be a numerical digit, perhaps followed by one or more letters 160 to match the desired section of the manual, for example, 161 .Li "3libucb". 162 Also, 163 .Ar section 164 can be a word, for example, 165 .Li local , 166 .Li new , 167 .Li old , 168 .Li public . 169 .Ar section 170 can also be a letter. To specify multiple sections, 171 separate each section with a comma. This option overrides the 172 .Ev MANPATH 173 environment variable and the 174 .Pa man.cf 175 file. See 176 .Sx Search Path 177 below for an explanation of how 178 .Nm 179 conducts its search. 180 .It Fl t 181 Arranges for the specified manual pages to be sent to the default 182 printer as PostScript. 183 .It Fl T Ar macro-package 184 This option is present for backwards compatibility and is documented 185 here for reference only. It performs no function. 186 .It Fl w 187 Updates the 188 .Nm whatis 189 database. 190 .El 191 .Sh OPERANDS 192 The following operand is supported: 193 .Bl -tag -width indent 194 .It Ar name 195 The name of a standard utility or a keyword. 196 .El 197 .Sh USAGE 198 The usage of 199 .Nm 200 is described below: 201 . 202 .Ss "Manual Page Sections" 203 . 204 Entries in the reference manuals are organized into 205 .Em sections . 206 A section 207 name consists of a major section name, typically a single digit, optionally 208 followed by a subsection name, typically one or more letters. An unadorned 209 major section name, for example, 210 .Qq 9 , 211 does not act as an abbreviation for 212 the subsections of that name, such as 213 .Qq 9e , 214 .Qq 9f , 215 or 216 .Qq 9s . 217 That is, each subsection must be searched separately by 218 .Nm 219 .Fl s . 220 Each section contains descriptions apropos to a particular reference category, 221 with subsections refining these distinctions. See the 222 .Em intro 223 manual pages for an explanation of the classification used in this release. 224 . 225 .Ss "Search Path" 226 . 227 Before searching for a given 228 .Ar name , 229 .Nm 230 constructs a list of candidate directories and sections. 231 It searches for 232 .Ar name 233 in the directories specified by the 234 .Ev MANPATH 235 environment variable. 236 .Lp 237 In the absence of 238 .Ev MANPATH , 239 .Nm 240 constructs its search path based upon the 241 .Ev PATH 242 environment variable, primarily by substituting 243 .Li man 244 for the last component of the 245 .Ev PATH 246 element. Special provisions are added 247 to account for unique characteristics of directories such as 248 .Pa /sbin , 249 .Pa /usr/ucb , 250 .Pa /usr/xpg4/bin , 251 and others. If the file argument contains 252 a 253 .Qq / 254 character, the 255 .Em dirname 256 portion of the argument is used in place of 257 .Ev PATH 258 elements to construct the search path. 259 .Lp 260 Within the manual page directories, 261 .Nm 262 confines its search to the 263 sections specified in the following order: 264 .Bl -bullet 265 .It 266 .Ar sections 267 specified on the command line with the 268 .Fl s 269 option 270 .It 271 .Ar sections 272 embedded in the 273 .Ev MANPATH 274 environment variable 275 .It 276 .Ar sections 277 specified in the 278 .Pa man.cf 279 file for each directory specified in the 280 .Ev MANPATH 281 environment variable 282 .El 283 If none of the above exist, 284 .Nm 285 searches each directory in the manual 286 page path, and displays the first matching manual page found. 287 .Lp 288 The 289 .Pa man.cf 290 file has the following format: 291 .Lp 292 .Dl Pf MANSECTS= Ar section , Ns Op Ar section... 293 .Lp 294 Lines beginning with 295 .Sq Li # 296 and blank lines are considered comments, and are 297 ignored. Each directory specified in 298 .Ev MANPATH 299 can contain a manual page 300 configuration file, specifying the default search order for that directory. 301 .Sh "Referring to Other Manual Pages" 302 If the first line of the manual page is a reference to another manual 303 page entry fitting the pattern: 304 .Lp 305 .Dl \&.so man*/\fIsourcefile\fR 306 .Lp 307 .Nm 308 processes the indicated file in place of the current one. The 309 reference must be expressed as a path name relative to the root of the manual 310 page directory subtree. 311 .Lp 312 When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR 313 ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual 314 manner. 315 .Sh ENVIRONMENT VARIABLES 316 See 317 .Xr environ 5 318 for descriptions of the following environment variables 319 that affect the execution of 320 .Nm man : 321 .Ev LANG , 322 .Ev LC_ALL , 323 .Ev LC_CTYPE , 324 .Ev LC_MESSAGES , 325 and 326 .Ev NLSPATH . 327 .Bl -tag -width indent 328 .It Ev MANPATH 329 A colon-separated list of directories; each directory can be followed by a 330 comma-separated list of sections. If set, its value overrides 331 \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR 332 file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in 333 turn, override these values.) 334 .It Ev PAGER 335 A program to use for interactively delivering 336 output to the screen. If not set, 337 .Sq Nm more Fl s 338 is used. See 339 .Xr more 1 . 340 .El 341 .Sh FILES 342 .Bl -tag -width indent 343 .It Pa /usr/share/man 344 Root of the standard manual page directory subtree 345 .It Pa /usr/share/man/man?/* 346 Unformatted manual entries 347 .It Pa /usr/share/man/whatis 348 Table of contents and keyword database 349 .It Pa man.cf 350 Default search order by section 351 .El 352 .Sh EXIT STATUS 353 .Ex -std man 354 .Sh EXAMPLES 355 . 356 .Ss Example 1: Creating a PostScript Version of a man page 357 . 358 The following example spools the 359 .Xr pipe 2 360 man page in PostScript to the default printer: 361 .Pp 362 .Dl % man -t -s 2 pipe 363 .Pp 364 Note that 365 .Xr mandoc 1 366 can be used to obtain the PostScript content directly. 367 .Ss Example 2: Creating a Text Version of a man page 368 The following example creates the 369 .Xr pipe 2 370 man page in ASCII text: 371 .Pp 372 .Dl % man pipe.2 | col -x -b > pipe.text 373 .Sh CODE SET INDEPENDENCE 374 Enabled. 375 .Sh INTERFACE STABILITY 376 .Nm Committed . 377 .Sh SEE ALSO 378 .Xr apropos 1 , 379 .Xr cat 1 , 380 .Xr col 1 , 381 .Xr mandoc 1 , 382 .Xr more 1 , 383 .Xr whatis 1 , 384 .Xr environ 5 , 385 .Xr man 5 , 386 .Xr mdoc 5 387 .Sh NOTES 388 The 389 .Fl f 390 and 391 .Fl k 392 options use the 393 .Nm whatis 394 database, which is 395 created with the 396 .Fl w 397 option. 398 .Sh BUGS 399 The manual is supposed to be reproducible either on a phototypesetter or on an 400 ASCII terminal. However, on a terminal some information (indicated by 401 font changes, for instance) is lost.