1.\"- 2.\" Copyright (c) 2010 Gordon Tetlow 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 26, 2022 29.Dt MAN 1 30.Os 31.Sh NAME 32.Nm man 33.Nd display online manual documentation pages 34.Sh SYNOPSIS 35.Nm 36.Op Fl adho 37.Op Fl t | w 38.Op Fl M Ar manpath 39.Op Fl P Ar pager 40.Op Fl S Ar mansect 41.Op Fl m Ar arch Ns Op : Ns Ar machine 42.Op Fl p Op Ar eprtv 43.Op Ar mansect 44.Ar page ... 45.Nm 46.Fl K 47.Ar regexp ... 48.Nm 49.Fl f 50.Ar keyword ... 51.Nm 52.Fl k 53.Ar keyword ... 54.Sh DESCRIPTION 55The 56.Nm 57utility finds and displays online manual documentation pages. 58If 59.Ar mansect 60is provided, 61.Nm 62restricts the search to the specific section of the manual. 63.Pp 64The sections of the manual are: 65.Bl -enum -offset indent -compact 66.It 67.Fx 68General Commands Manual 69.It 70.Fx 71System Calls Manual 72.It 73.Fx 74Library Functions Manual 75.It 76.Fx 77Kernel Interfaces Manual 78.It 79.Fx 80File Formats Manual 81.It 82.Fx 83Games Manual 84.It 85.Fx 86Miscellaneous Information Manual 87.It 88.Fx 89System Manager's Manual 90.It 91.Fx 92Kernel Developer's Manual 93.El 94.Pp 95Options that 96.Nm 97understands: 98.Bl -tag -width indent 99.It Fl K Ar regexp 100Does a full text search in all manual pages. 101.Ar regexp 102is a regular expression as understood by 103.Dq Li "grep -E" . 104This option requires 105.Xr mandoc 1 . 106This is a slow operation. 107.It Fl M Ar manpath 108Forces a specific colon separated manual path instead of the default 109search path. 110See 111.Xr manpath 1 . 112Overrides the 113.Ev MANPATH 114environment variable. 115.It Fl P Ar pager 116Use specified pager. 117Defaults to 118.Dq Li "less -sR" 119if color support is enabled, or 120.Dq Li "less -s" . 121Overrides the 122.Ev MANPAGER 123environment variable, which in turn overrides the 124.Ev PAGER 125environment variable. 126.It Fl S Ar mansect 127Restricts manual sections searched to the specified colon delimited list. 128Defaults to 129.Dq Li 1:8:2:3:3lua:n:4:5:6:7:9:l . 130Overrides the 131.Ev MANSECT 132environment variable. 133.It Fl a 134Display all manual pages instead of just the first found for each 135.Ar page 136argument. 137.It Fl d 138Print extra debugging information. 139Repeat for increased verbosity. 140Does not display the manual page. 141.It Fl f 142Emulate 143.Xr whatis 1 . 144.It Fl h 145Display short help message and exit. 146.It Fl k 147Emulate 148.Xr apropos 1 . 149.It Fl m Ar arch Ns Op : Ns Ar machine 150Override the default architecture and machine settings allowing lookup of 151other platform specific manual pages. 152See 153.Sx IMPLEMENTATION NOTES 154for how this option changes the default behavior. 155Overrides the 156.Ev MACHINE_ARCH 157and 158.Ev MACHINE 159environment variables. 160.It Fl o 161Force use of non-localized manual pages. 162See 163.Sx IMPLEMENTATION NOTES 164for how locale specific searches work. 165Overrides the 166.Ev LC_ALL , LC_CTYPE , 167and 168.Ev LANG 169environment variables. 170.It Fl p Op Cm eprtv 171Use the list of given preprocessors before running 172.Xr nroff 1 173or 174.Xr troff 1 . 175Valid preprocessors arguments: 176.Pp 177.Bl -tag -width indent -compact 178.It Cm e 179.Xr eqn 1 180.It Cm p 181.Xr pic 1 182.It Cm r 183.Xr refer 1 184.It Cm t 185.Xr tbl 1 186.It Cm v 187.Xr vgrind 1 188.El 189.Pp 190Overrides the 191.Ev MANROFFSEQ 192environment variable. 193.It Fl t 194Send manual page source through 195.Xr troff 1 196allowing transformation of the manual pages to other formats. 197.It Fl w 198Display the location of the manual page instead of the contents of 199the manual page. 200.El 201.Sh IMPLEMENTATION NOTES 202.Ss Locale Specific Searches 203The 204.Nm 205utility supports manual pages in different locales. 206The search behavior is dictated by the first of three 207environment variables with a nonempty string: 208.Ev LC_ALL , LC_CTYPE , 209or 210.Ev LANG . 211If set, 212.Nm 213will search for locale specific manual pages using the following logic: 214.Pp 215.Bl -item -offset indent -compact 216.It 217.Va lang Ns _ Ns Va country Ns . Ns Va charset 218.It 219.Va lang Ns . Ns Va charset 220.It 221.Li en Ns . Ns Va charset 222.El 223.Pp 224For example, if 225.Ev LC_ALL 226is set to 227.Dq Li ja_JP.eucJP , 228.Nm 229will search the following paths when considering section 1 manual pages in 230.Pa /usr/share/man : 231.Pp 232.Bl -item -offset indent -compact 233.It 234.Pa /usr/share/man/ja_JP.eucJP/man1 235.It 236.Pa /usr/share/man/ja.eucJP/man1 237.It 238.Pa /usr/share/man/en.eucJP/man1 239.It 240.Pa /usr/share/man/man1 241.El 242.Ss Platform Specific Searches 243The 244.Nm 245utility supports platform specific manual pages. 246The search behavior is dictated by the 247.Fl m 248option or the 249.Ev MACHINE_ARCH 250and 251.Ev MACHINE 252environment variables. 253For example, if 254.Ev MACHINE_ARCH 255is set to 256.Dq Li aarch64 257and 258.Ev MACHINE 259is set to 260.Dq Li arm64 , 261.Nm 262will search the following paths when considering section 4 manual pages in 263.Pa /usr/share/man : 264.Pp 265.Bl -item -offset indent -compact 266.It 267.Pa /usr/share/man/man4/aarch64 268.It 269.Pa /usr/share/man/man4/arm64 270.It 271.Pa /usr/share/man/man4 272.El 273.Ss Displaying Specific Manual Files 274The 275.Nm 276utility also supports displaying a specific manual page if passed a path 277to the file as long as it contains a 278.Ql / 279character. 280.Sh ENVIRONMENT 281The following environment variables affect the execution of 282.Nm : 283.Bl -tag -width ".Ev MANROFFSEQ" 284.It Ev LC_ALL , LC_CTYPE , LANG 285Used to find locale specific manual pages. 286Valid values can be found by running the 287.Xr locale 1 288command. 289See 290.Sx IMPLEMENTATION NOTES 291for details. 292Influenced by the 293.Fl o 294option. 295.It Ev MACHINE_ARCH , MACHINE 296Used to find platform specific manual pages. 297If unset, the output of 298.Dq Li "sysctl hw.machine_arch" 299and 300.Dq Li "sysctl hw.machine" 301is used respectively. 302See 303.Sx IMPLEMENTATION NOTES 304for details. 305Corresponds to the 306.Fl m 307option. 308.It Ev MANPATH 309The standard search path used by 310.Xr man 1 311may be changed by specifying a path in the 312.Ev MANPATH 313environment variable. 314Invalid paths, or paths without manual databases, are ignored. 315Overridden by 316.Fl M . 317If 318.Ev MANPATH 319begins with a colon, it is appended to the default list; 320if it ends with a colon, it is prepended to the default list; 321or if it contains two adjacent colons, 322the standard search path is inserted between the colons. 323If none of these conditions are met, it overrides the 324standard search path. 325.It Ev MANROFFSEQ 326Used to determine the preprocessors for the manual source before running 327.Xr nroff 1 328or 329.Xr troff 1 . 330If unset, defaults to 331.Xr tbl 1 . 332Corresponds to the 333.Fl p 334option. 335.It Ev MANSECT 336Restricts manual sections searched to the specified colon delimited list. 337Corresponds to the 338.Fl S 339option. 340.It Ev MANWIDTH 341If set to a numeric value, used as the width manpages should be displayed. 342Otherwise, if set to a special value 343.Dq Li tty , 344and output is to a terminal, 345the pages may be displayed over the whole width of the screen. 346.It Ev MANCOLOR 347If set, enables color support. 348.It Ev MANPAGER 349Program used to display files. 350.Pp 351If unset, and color support is enabled, 352.Dq Li "less -sR" 353is used. 354.Pp 355If unset, and color support is disabled, then 356.Ev PAGER 357is used. 358If that has no value either, 359.Dq Li "less -s" 360is used. 361.El 362.Sh FILES 363.Bl -tag -width indent -compact 364.It Pa /etc/man.conf 365System configuration file. 366.It Pa /usr/local/etc/man.d/*.conf 367Local configuration files. 368.El 369.Sh EXIT STATUS 370.Ex -std 371.Sh EXAMPLES 372Show the manual page for 373.Xr stat 2 : 374.Bd -literal -offset indent 375$ man 2 stat 376.Ed 377.Pp 378Show all manual pages for 379.Ql stat . 380.Bd -literal -offset indent 381$ man -a stat 382.Ed 383.Pp 384List manual pages which match the regular expression either in the title or in 385the body: 386.Bd -literal -offset indent 387$ man -k '\e<copy\e>.*archive' 388.Ed 389.Pp 390Show the manual page for 391.Xr ls 1 392and use 393.Xr cat 1 394as pager: 395.Bd -literal -offset indent 396$ man -P cat ls 397.Ed 398.Pp 399Show the location of the 400.Xr ls 1 401manual page: 402.Bd -literal -offset indent 403$ man -w ls 404.Ed 405.Pp 406Show the location of manual pages in sections 1 and 8 which contain the word 407.Ql arm : 408.Bd -literal -offset indent 409$ ./man -w -K '\e<arm\e>' -S 1:8 410.Ed 411.Sh SEE ALSO 412.Xr apropos 1 , 413.Xr egrep 1 , 414.Xr intro 1 , 415.Xr mandoc 1 , 416.Xr manpath 1 , 417.Xr whatis 1 , 418.Xr intro 2 , 419.Xr intro 3 , 420.Xr intro 3lua , 421.Xr intro 4 , 422.Xr intro 5 , 423.Xr man.conf 5 , 424.Xr intro 6 , 425.Xr intro 7 , 426.Xr mdoc 7 , 427.Xr intro 8 , 428.Xr intro 9 429