1.\" $Id: man.1,v 1.29 2017/05/17 23:23:00 schwarze Exp $ 2.\" 3.\" Copyright (c) 1989, 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org> 6.\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze <schwarze@openbsd.org> 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)man.1 8.2 (Berkeley) 1/2/94 33.\" 34.Dd $Mdocdate: May 17 2017 $ 35.Dt MAN 1 36.Os 37.Sh NAME 38.Nm man 39.Nd display manual pages 40.Sh SYNOPSIS 41.Nm man 42.Op Fl acfhklw 43.Op Fl C Ar file 44.Op Fl M Ar path 45.Op Fl m Ar path 46.Op Fl S Ar subsection 47.Op Oo Fl s Oc Ar section 48.Ar name ... 49.Sh DESCRIPTION 50The 51.Nm 52utility 53displays the 54manual pages entitled 55.Ar name . 56Pages may be selected according to 57a specific category 58.Pq Ar section 59or 60machine architecture 61.Pq Ar subsection . 62.Pp 63The options are as follows: 64.Bl -tag -width Ds 65.It Fl a 66Display all matching manual pages. 67Normally, only the first page found is displayed. 68.It Fl C Ar file 69Use the specified 70.Ar file 71instead of the default configuration file. 72This permits users to configure their own manual environment. 73See 74.Xr man.conf 5 75for a description of the contents of this file. 76.It Fl c 77Copy the manual page to the standard output instead of using 78.Xr more 1 79to paginate it. 80This is done by default if the standard output is not a terminal device. 81.It Fl f 82A synonym for 83.Xr whatis 1 . 84It searches for 85.Ar name 86in manual page names and displays the header lines from all matching pages. 87The search is case insensitive and matches whole words only. 88.It Fl h 89Display only the SYNOPSIS lines of the requested manual pages. 90Implies 91.Fl a 92and 93.Fl c . 94.It Fl k 95A synonym for 96.Xr apropos 1 . 97Instead of 98.Ar name , 99an expression can be provided using the syntax described in the 100.Xr apropos 1 101manual. 102By default, it displays the header lines of all matching pages. 103.It Fl l 104A synonym for 105.Xr mandoc 1 106.Fl a . 107The 108.Ar name 109arguments are interpreted as filenames. 110No search is done and 111.Ar file , 112.Ar path , 113.Ar section , 114.Ar subsection , 115and 116.Fl w 117are ignored. 118.It Fl M Ar path 119Override the list of standard directories which 120.Nm 121searches for manual pages. 122The supplied 123.Ar path 124must be a colon 125.Pq Ql \&: 126separated list of directories. 127This search path may also be set using the environment variable 128.Ev MANPATH . 129.It Fl m Ar path 130Augment the list of standard directories which 131.Nm 132searches for manual pages. 133The supplied 134.Ar path 135must be a colon 136.Pq Ql \&: 137separated list of directories. 138These directories will be searched before the standard directories or 139the directories specified using the 140.Fl M 141option or the 142.Ev MANPATH 143environment variable. 144.It Fl S Ar subsection 145Only show pages for the specified 146.Xr machine 1 147architecture. 148.Ar subsection 149is case insensitive. 150.Pp 151By default manual pages for all architectures are installed. 152Therefore this option can be used to view pages for one 153architecture whilst using another. 154.Pp 155This option overrides the 156.Ev MACHINE 157environment variable. 158.It Oo Fl s Oc Ar section 159Only select manuals from the specified 160.Ar section . 161The currently available sections are: 162.Pp 163.Bl -tag -width "localXXX" -offset indent -compact 164.It 1 165General commands 166.Pq tools and utilities . 167.It 2 168System calls and error numbers. 169.It 3 170Library functions. 171.It 3p 172.Xr perl 1 173programmer's reference guide. 174.It 4 175Device drivers. 176.It 5 177File formats. 178.It 6 179Games. 180.It 7 181Miscellaneous information. 182.It 8 183System maintenance and operation commands. 184.It 9 185Kernel internals. 186.El 187.Pp 188If not specified and a match is found in more than one section, 189the first match is selected from the following list: 1901, 8, 6, 2, 3, 5, 7, 4, 9, 3p. 191.It Fl w 192List the pathnames of all matching manual pages instead of displaying 193any of them. 194.El 195.Pp 196The options 197.Fl IKOTW 198are also supported and are documented in 199.Xr mandoc 1 . 200The options 201.Fl fkl 202are mutually exclusive and override each other. 203.Pp 204Guidelines for writing 205man pages can be found in 206.Xr mdoc 7 . 207.Pp 208If both a formatted and an unformatted version of the same manual page, 209for example 210.Pa cat1/foo.0 211and 212.Pa man1/foo.1 , 213exist in the same directory, only the unformatted version is used. 214.Sh ENVIRONMENT 215.Bl -tag -width MANPATHX 216.It Ev MACHINE 217As some manual pages are intended only for specific architectures, 218.Nm 219searches any subdirectories, 220with the same name as the current architecture, 221in every directory which it searches. 222Machine specific areas are checked before general areas. 223The current machine type may be overridden by setting the environment 224variable 225.Ev MACHINE 226to the name of a specific architecture, 227or with the 228.Fl S 229option. 230.Ev MACHINE 231is case insensitive. 232.It Ev MANPAGER 233Any non-empty value of the environment variable 234.Ev MANPAGER 235is used instead of the standard pagination program, 236.Xr more 1 . 237If 238.Xr less 1 239is used, the interactive 240.Ic :t 241command can be used to go to the definitions of various terms, for 242example command line options, command modifiers, internal commands, 243environment variables, function names, preprocessor macros, 244.Xr errno 2 245values, and some other emphasized words. 246Some terms may have defining text at more than one place. 247In that case, the 248.Xr less 1 249interactive commands 250.Ic t 251and 252.Ic T 253can be used to move to the next and to the previous place providing 254information about the term last searched for with 255.Ic :t . 256.It Ev MANPATH 257The standard search path used by 258.Nm 259may be changed by specifying a path in the 260.Ev MANPATH 261environment variable. 262The format of the path is a colon 263.Pq Ql \&: 264separated list of directories. 265Invalid paths are ignored. 266Overridden by 267.Fl M , 268ignored if 269.Fl l 270is specified. 271.Pp 272If 273.Ev MANPATH 274begins with a colon, it is appended to the default list; 275if it ends with a colon, it is prepended to the default list; 276or if it contains two adjacent colons, 277the standard search path is inserted between the colons. 278If none of these conditions are met, it overrides the 279standard search path. 280.It Ev PAGER 281Specifies the pagination program to use when 282.Ev MANPAGER 283is not defined. 284If neither PAGER nor MANPAGER is defined, 285.Xr more 1 286.Fl s 287is used. 288Only used if 289.Fl a 290or 291.Fl l 292is specified. 293.El 294.Sh FILES 295.Bl -tag -width /etc/man.conf -compact 296.It Pa /etc/man.conf 297default man configuration file 298.El 299.Sh EXIT STATUS 300.Ex -std man 301See 302.Xr mandoc 1 303for details. 304.Sh SEE ALSO 305.Xr apropos 1 , 306.Xr intro 1 , 307.Xr whereis 1 , 308.Xr intro 2 , 309.Xr intro 3 , 310.Xr intro 4 , 311.Xr intro 5 , 312.Xr man.conf 5 , 313.Xr intro 6 , 314.Xr intro 7 , 315.Xr mdoc 7 , 316.Xr intro 8 , 317.Xr intro 9 318.Sh STANDARDS 319The 320.Nm 321utility is compliant with the 322.St -p1003.1-2008 323specification. 324.Pp 325The flags 326.Op Fl aCcfhIKlMmOSsTWw , 327as well as the environment variables 328.Ev MACHINE , 329.Ev MANPAGER , 330and 331.Ev MANPATH , 332are extensions to that specification. 333.Sh HISTORY 334A 335.Nm 336command first appeared in 337.At v3 . 338.Pp 339The 340.Fl w 341option first appeared in 342.At v7 ; 343.Fl f 344and 345.Fl k 346in 347.Bx 4 ; 348.Fl M 349in 350.Bx 4.3 ; 351.Fl a 352in 353.Bx 4.3 Tahoe ; 354.Fl c 355and 356.Fl m 357in 358.Bx 4.3 Reno ; 359.Fl h 360in 361.Bx 4.3 Net/2 ; 362.Fl C 363in 364.Nx 1.0 ; 365.Fl s 366and 367.Fl S 368in 369.Ox 2.3 ; 370and 371.Fl I , 372.Fl K , 373.Fl l , 374.Fl O , 375and 376.Fl W 377in 378.Ox 5.7 . 379The 380.Fl T 381option first appeared in 382.At III 383and was also added in 384.Ox 5.7 . 385