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