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