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