mirror of
https://git.freebsd.org/src.git
synced 2026-01-12 06:54:03 +00:00
14b61b2e93
Add a -l option which causes man to interpret all arguments as paths to open directly rather than man pages to search for in MANPATH. See the PR for a detailed rationale. PR: 289245 MFC after: 1 week Reviewed by: ziaee, emaste Differential Revision: https://reviews.freebsd.org/D52385
436 lines
9.6 KiB
Groff
436 lines
9.6 KiB
Groff
.\"-
|
|
.\" SPDX-License-Identifier: BSD-2-Clause
|
|
.\"
|
|
.\" Copyright (c) 2010 Gordon Tetlow
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 24, 2025
|
|
.Dt MAN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm man
|
|
.Nd display online manual documentation pages
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl adhlo
|
|
.Op Fl t | w
|
|
.Op Fl M Ar manpath
|
|
.Op Fl P Ar pager
|
|
.Op Fl S Ar mansect
|
|
.Op Fl m Ar arch Ns Op : Ns Ar machine
|
|
.Op Fl p Op Ar eprtv
|
|
.Op Ar mansect
|
|
.Ar page | Ar
|
|
.Nm
|
|
.Fl K | f | k
|
|
.Ar expression ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility finds and displays online manual documentation pages.
|
|
If
|
|
.Ar mansect
|
|
is provided,
|
|
.Nm
|
|
restricts the search to the specific section of the manual.
|
|
.Pp
|
|
The sections of the manual are:
|
|
.Pp
|
|
.Bl -enum -offset indent -compact
|
|
.It
|
|
.Fx
|
|
General Commands Manual
|
|
.It
|
|
.Fx
|
|
System Calls Manual
|
|
.It
|
|
.Fx
|
|
Library Functions Manual
|
|
.It
|
|
.Fx
|
|
Kernel Interfaces Manual
|
|
.It
|
|
.Fx
|
|
File Formats Manual
|
|
.It
|
|
.Fx
|
|
Games Manual
|
|
.It
|
|
.Fx
|
|
Miscellaneous Information Manual
|
|
.It
|
|
.Fx
|
|
System Manager's Manual
|
|
.It
|
|
.Fx
|
|
Kernel Developer's Manual
|
|
.El
|
|
.Pp
|
|
Options that
|
|
.Nm
|
|
understands:
|
|
.Bl -tag -width indent
|
|
.It Fl K Ar expression
|
|
Search full text of all manual pages for an extended regular
|
|
.Ar expression ,
|
|
as described in
|
|
.Xr re_format 7 .
|
|
This option requires
|
|
.Xr mandoc 1 .
|
|
This is a slow operation.
|
|
.It Fl M Ar manpath
|
|
Force a specific colon separated manual path instead of the default
|
|
search path.
|
|
See
|
|
.Ev MANPATH
|
|
in
|
|
.Sx ENVIRONMENT .
|
|
.It Fl P Ar pager
|
|
Use specified pager.
|
|
Defaults to
|
|
.Ql less -sR
|
|
if color support is enabled, or
|
|
.Ql less -s .
|
|
Overrides the
|
|
.Ev MANPAGER
|
|
environment variable, which in turn overrides the
|
|
.Ev PAGER
|
|
environment variable.
|
|
.It Fl S Ar mansect
|
|
Restrict manual sections searched to the specified colon delimited list.
|
|
Defaults to
|
|
.Ql 1:8:2:3:3lua:n:4:5:6:7:9:l .
|
|
Overrides the
|
|
.Ev MANSECT
|
|
environment variable.
|
|
.It Fl a
|
|
Display all manual pages instead of just the first found for each
|
|
.Ar page
|
|
argument.
|
|
.It Fl d
|
|
Print extra debugging information.
|
|
Repeat for increased verbosity.
|
|
Does not display the manual page.
|
|
.It Fl f Ar expression
|
|
Search names of all manual pages for an extended regular
|
|
.Ar expression ,
|
|
emulating
|
|
.Xr whatis 1 .
|
|
.It Fl h
|
|
Display short help message and exit.
|
|
.It Fl k Ar expression
|
|
Search names and descriptions of all manual pages for an extended regular
|
|
.Ar expression ,
|
|
emulating basic functionality of
|
|
.Xr apropos 1 .
|
|
.It Fl l
|
|
Interpret all arguments as absolute or relative filename(s)
|
|
of the manual page(s) to display.
|
|
No search is done and the options
|
|
.Fl M ,
|
|
.Fl m ,
|
|
and
|
|
.Fl S
|
|
are ignored.
|
|
.It Fl m Ar arch Ns Op : Ns Ar machine
|
|
Override the default architecture and machine settings allowing lookup of
|
|
other platform specific manual pages.
|
|
See
|
|
.Sx IMPLEMENTATION NOTES
|
|
for how this option changes the default behavior.
|
|
Overrides the
|
|
.Ev MACHINE_ARCH
|
|
and
|
|
.Ev MACHINE
|
|
environment variables.
|
|
.It Fl o
|
|
Force use of non-localized manual pages.
|
|
See
|
|
.Sx IMPLEMENTATION NOTES
|
|
for how locale specific searches work.
|
|
Overrides the
|
|
.Ev LC_ALL , LC_CTYPE ,
|
|
and
|
|
.Ev LANG
|
|
environment variables.
|
|
.It Fl p Op Cm eprtv
|
|
Use the list of given preprocessors before running
|
|
.Xr nroff 1 Pq Pa ports/textproc/groff
|
|
or
|
|
.Xr troff 1 Pq Pa ports/textproc/groff .
|
|
Valid preprocessors arguments:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Cm e
|
|
.Xr eqn 1 Pq Pa ports/textproc/groff
|
|
.It Cm p
|
|
.Xr pic 1 Pq Pa ports/textproc/groff
|
|
.It Cm r
|
|
.Xr refer 1 Pq Pa ports/textproc/groff
|
|
.It Cm t
|
|
.Xr tbl 1 Pq Pa ports/textproc/groff
|
|
.It Cm v
|
|
.Xr vgrind 1
|
|
.El
|
|
.Pp
|
|
Overrides the
|
|
.Ev MANROFFSEQ
|
|
environment variable.
|
|
.It Fl t
|
|
Send manual page source through
|
|
.Xr troff 1 Pq Pa ports/textproc/groff
|
|
allowing transformation of the manual pages to other formats.
|
|
.It Fl w
|
|
Display the location of the manual page instead of the contents of
|
|
the manual page.
|
|
.El
|
|
.Sh IMPLEMENTATION NOTES
|
|
.Ss Locale Specific Searches
|
|
The
|
|
.Nm
|
|
utility supports manual pages in different locales.
|
|
The search behavior is dictated by the first of three
|
|
environment variables with a nonempty string:
|
|
.Ev LC_ALL , LC_CTYPE ,
|
|
or
|
|
.Ev LANG .
|
|
If set,
|
|
.Nm
|
|
will search for locale specific manual pages using the following logic:
|
|
.Pp
|
|
.Bl -item -offset indent -compact
|
|
.It
|
|
.Va lang Ns _ Ns Va country . Ns Va charset
|
|
.It
|
|
.Va lang . Ns Va charset
|
|
.It
|
|
.Li en . Ns Va charset
|
|
.El
|
|
.Pp
|
|
For example, if
|
|
.Ev LC_ALL
|
|
is set to
|
|
.Ql ja_JP.eucJP ,
|
|
.Nm
|
|
will search the following paths when considering section 1 manual pages in
|
|
.Pa /usr/share/man :
|
|
.Pp
|
|
.Bl -item -offset indent -compact
|
|
.It
|
|
.Pa /usr/share/man/ja_JP.eucJP/man1
|
|
.It
|
|
.Pa /usr/share/man/ja.eucJP/man1
|
|
.It
|
|
.Pa /usr/share/man/en.eucJP/man1
|
|
.It
|
|
.Pa /usr/share/man/man1
|
|
.El
|
|
.Ss Platform Specific Searches
|
|
The
|
|
.Nm
|
|
utility supports platform specific manual pages.
|
|
The search behavior is dictated by the
|
|
.Fl m
|
|
option or the
|
|
.Ev MACHINE_ARCH
|
|
and
|
|
.Ev MACHINE
|
|
environment variables.
|
|
For example, if
|
|
.Ev MACHINE_ARCH
|
|
is set to
|
|
.Ql aarch64
|
|
and
|
|
.Ev MACHINE
|
|
is set to
|
|
.Ql arm64 ,
|
|
.Nm
|
|
will search the following paths when considering section 4 manual pages in
|
|
.Pa /usr/share/man :
|
|
.Pp
|
|
.Bl -item -offset indent -compact
|
|
.It
|
|
.Pa /usr/share/man/man4/aarch64
|
|
.It
|
|
.Pa /usr/share/man/man4/arm64
|
|
.It
|
|
.Pa /usr/share/man/man4
|
|
.El
|
|
.Ss Displaying Specific Manual Files
|
|
For compatibility reasons,
|
|
.Nm
|
|
will interpret any argument containing at least one
|
|
.Ql /
|
|
character as an absolute or relative path to a manual page to be
|
|
displayed.
|
|
This heuristic, made redundant by the more widely supported
|
|
.Fl l
|
|
option, is now deprecated and may be removed in future releases.
|
|
.Sh ENVIRONMENT
|
|
The following environment variables affect the execution of
|
|
.Nm :
|
|
.Bl -tag -width indent
|
|
.It Ev LC_ALL , Ev LC_CTYPE , Ev LANG
|
|
Used to find locale specific manual pages.
|
|
Valid values can be found by running the
|
|
.Xr locale 1
|
|
command.
|
|
See
|
|
.Sx IMPLEMENTATION NOTES
|
|
for details.
|
|
Influenced by the
|
|
.Fl o
|
|
option.
|
|
.It Ev MACHINE_ARCH , Ev MACHINE
|
|
Used to find platform specific manual pages.
|
|
If unset, the output of
|
|
.Ql sysctl Va hw.machine_arch
|
|
and
|
|
.Ql sysctl Va hw.machine
|
|
is used respectively.
|
|
See
|
|
.Sx IMPLEMENTATION NOTES
|
|
for details.
|
|
Corresponds to the
|
|
.Fl m
|
|
option.
|
|
.It Ev MANPATH
|
|
A colon
|
|
.Pq Ql \&:
|
|
separated list of directories to check for manual pages.
|
|
Invalid paths, or paths without manual databases, are ignored.
|
|
Overridden by
|
|
.Fl M .
|
|
If
|
|
.Ev MANPATH
|
|
begins with a colon, it is appended to the default list;
|
|
if it ends with a colon, it is prepended to the default list;
|
|
or if it contains two adjacent colons,
|
|
the standard search path is inserted between the colons.
|
|
If none of these conditions are met, it overrides the
|
|
standard search path.
|
|
See
|
|
.Xr manpath 1 .
|
|
.It Ev MANROFFSEQ
|
|
Used to determine the preprocessors for the manual source before running
|
|
.Xr nroff 1 Pq Pa ports/textproc/groff
|
|
or
|
|
.Xr troff 1 Pq Pa ports/textproc/groff .
|
|
If unset, defaults to
|
|
.Xr tbl 1 Pq Pa ports/textproc/groff .
|
|
Corresponds to the
|
|
.Fl p
|
|
option.
|
|
.It Ev MANSECT
|
|
Restricts manual sections searched to the specified colon delimited list.
|
|
Corresponds to the
|
|
.Fl S
|
|
option.
|
|
.It Ev MANWIDTH
|
|
If set to a numeric value, used as the width manpages should be displayed.
|
|
Otherwise, if set to a special value
|
|
.Ql tty ,
|
|
and output is to a terminal,
|
|
the pages may be displayed over the whole width of the screen.
|
|
.It Ev MANCOLOR
|
|
If set, enables color support.
|
|
.It Ev MANPAGER
|
|
Program used to display files.
|
|
.Pp
|
|
If unset, and color support is enabled,
|
|
.Ql less -sR
|
|
is used.
|
|
.Pp
|
|
If unset, and color support is disabled, then
|
|
.Ev PAGER
|
|
is used.
|
|
If that has no value either,
|
|
.Ql less -s
|
|
is used.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/usr/local/etc/man.d/*.conf" -compact
|
|
.It Pa /etc/man.conf
|
|
System configuration file
|
|
.It Pa /usr/local/etc/man.d/*.conf
|
|
Local configuration files
|
|
.El
|
|
.Sh EXIT STATUS
|
|
.Ex -std
|
|
.Sh EXAMPLES
|
|
Show the manual page for
|
|
.Xr stat 2 :
|
|
.Pp
|
|
.Dl $ man 2 stat
|
|
.Pp
|
|
Show all manual pages for
|
|
.Ql stat :
|
|
.Pp
|
|
.Dl $ man -a stat
|
|
.Pp
|
|
List manual pages which match the regular expression either in the title or in
|
|
the body:
|
|
.Pp
|
|
.Dl $ man -k '\e<copy\e>.*archive'
|
|
.Pp
|
|
Show the manual page for
|
|
.Xr ls 1
|
|
using
|
|
.Xr cat 1
|
|
as the pager:
|
|
.Pp
|
|
.Dl $ man -P cat ls
|
|
.Pp
|
|
Show the location of the
|
|
.Xr ls 1
|
|
manual page:
|
|
.Pp
|
|
.Dl $ man -w ls
|
|
.Pp
|
|
Show a manual page in the current working directory:
|
|
.Pp
|
|
.Dl $ man -l man.1
|
|
.Pp
|
|
Show the location of manual pages in sections 1 and 8 which contain the word
|
|
.Ql arm :
|
|
.Pp
|
|
.Dl $ man -w -K '\e<arm\e>' -S 1:8
|
|
.Sh SEE ALSO
|
|
.Xr apropos 1 ,
|
|
.Xr intro 1 ,
|
|
.Xr mandoc 1 ,
|
|
.Xr manpath 1 ,
|
|
.Xr whatis 1 ,
|
|
.Xr intro 2 ,
|
|
.Xr intro 3 ,
|
|
.Xr intro 3lua ,
|
|
.Xr intro 4 ,
|
|
.Xr intro 5 ,
|
|
.Xr man.conf 5 ,
|
|
.Xr intro 6 ,
|
|
.Xr intro 7 ,
|
|
.Xr mdoc 7 ,
|
|
.Xr re_format 7 ,
|
|
.Xr intro 8 ,
|
|
.Xr intro 9
|