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