usr.bin/man/man.1

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