452 lines
9.1 KiB
Groff
452 lines
9.1 KiB
Groff
.\" $Id: man.1,v 1.16 2015/09/21 09:59:02 schwarze Exp $
|
|
.\"
|
|
.\" Copyright (c) 1989, 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
|
|
.\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
|
.\"
|
|
.\" @(#)man.1 8.2 (Berkeley) 1/2/94
|
|
.\"
|
|
.Dd $Mdocdate: September 21 2015 $
|
|
.Dt MAN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm man
|
|
.Nd display manual pages
|
|
.Sh SYNOPSIS
|
|
.Nm man
|
|
.Op Fl acfhklw
|
|
.Op Fl C Ar file
|
|
.Op Fl I Cm os Ns = Ns Ar name
|
|
.Op Fl K Ar encoding
|
|
.Op Fl M Ar path
|
|
.Op Fl m Ar path
|
|
.Op Fl O Ar option Ns = Ns Ar value
|
|
.Op Fl S Ar subsection
|
|
.Op Fl s Ar section
|
|
.Op Fl T Ar output
|
|
.Op Fl W Ar level
|
|
.Op Ar section
|
|
.Ar name ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility
|
|
displays the
|
|
manual pages entitled
|
|
.Ar name .
|
|
Pages may be selected according to
|
|
a specific category
|
|
.Pq Ar section
|
|
or
|
|
machine architecture
|
|
.Pq Ar subsection .
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl a
|
|
Display all of the manual pages for a specified
|
|
.Ar section
|
|
and
|
|
.Ar name
|
|
combination.
|
|
Normally, only the first manual page found is displayed.
|
|
.It Fl C Ar file
|
|
Use the specified
|
|
.Ar file
|
|
instead of the default configuration file.
|
|
This permits users to configure their own manual environment.
|
|
See
|
|
.Xr man.conf 5
|
|
for a description of the contents of this file.
|
|
.It Fl c
|
|
Copy the manual page to the standard output instead of using
|
|
.Xr more 1
|
|
to paginate it.
|
|
This is done by default if the standard output is not a terminal device.
|
|
.It Fl f
|
|
A synonym for
|
|
.Xr whatis 1 .
|
|
It searches for
|
|
.Ar name
|
|
in manual page names and displays the header lines from all matching pages.
|
|
The search is case insensitive and matches whole words only.
|
|
This overrides any earlier
|
|
.Fl k
|
|
and
|
|
.Fl l
|
|
options.
|
|
.It Fl I Cm os Ns = Ns Ar name
|
|
Override the default operating system
|
|
.Ar name
|
|
for the
|
|
.Xr mdoc 7
|
|
.Ic \&Os
|
|
and for the
|
|
.Xr man 7
|
|
.Ic \&TH
|
|
macro.
|
|
.It Fl h
|
|
Display only the SYNOPSIS lines of the requested manual pages.
|
|
Implies
|
|
.Fl a
|
|
and
|
|
.Fl c .
|
|
.It Fl K Ar encoding
|
|
Specify the input encoding.
|
|
The supported
|
|
.Ar encoding
|
|
arguments are
|
|
.Cm us-ascii ,
|
|
.Cm iso-8859-1 ,
|
|
and
|
|
.Cm utf-8 .
|
|
By default, the encoding is automatically detected as described in the
|
|
.Xr mandoc 1
|
|
manual.
|
|
.It Fl k
|
|
A synonym for
|
|
.Xr apropos 1 .
|
|
Instead of
|
|
.Ar name ,
|
|
an expression can be provided using the syntax described in the
|
|
.Xr apropos 1
|
|
manual.
|
|
By default, it displays the header lines of all matching pages.
|
|
This overrides any earlier
|
|
.Fl f
|
|
and
|
|
.Fl l
|
|
options.
|
|
.It Fl l
|
|
A synonym for
|
|
.Xr mandoc 1
|
|
.Fl a .
|
|
The
|
|
.Ar name
|
|
arguments are interpreted as filenames.
|
|
No search is done and
|
|
.Ar file ,
|
|
.Ar path ,
|
|
.Ar section ,
|
|
and
|
|
.Ar subsection
|
|
are ignored.
|
|
This overrides any earlier
|
|
.Fl f ,
|
|
.Fl k ,
|
|
and
|
|
.Fl w
|
|
options.
|
|
.It Fl M Ar path
|
|
Override the list of standard directories which
|
|
.Nm
|
|
searches for manual pages.
|
|
The supplied
|
|
.Ar path
|
|
must be a colon
|
|
.Pq Ql \&:
|
|
separated list of directories.
|
|
This search path may also be set using the environment variable
|
|
.Ev MANPATH .
|
|
.It Fl m Ar path
|
|
Augment the list of standard directories which
|
|
.Nm
|
|
searches for manual pages.
|
|
The supplied
|
|
.Ar path
|
|
must be a colon
|
|
.Pq Ql \&:
|
|
separated list of directories.
|
|
These directories will be searched before the standard directories or
|
|
the directories specified using the
|
|
.Fl M
|
|
option or the
|
|
.Ev MANPATH
|
|
environment variable.
|
|
.It Fl O Ar option Ns = Ns Ar value
|
|
Comma-separated output options.
|
|
For each output format, the available options are described in the
|
|
.Xr mandoc 1
|
|
manual.
|
|
.It Fl S Ar subsection
|
|
Restricts the directories that
|
|
.Nm
|
|
will search to those of a specific
|
|
.Xr machine 1
|
|
architecture.
|
|
.Ar subsection
|
|
is case insensitive.
|
|
.Pp
|
|
By default manual pages for all architectures are installed.
|
|
Therefore this option can be used to view pages for one
|
|
architecture whilst using another.
|
|
.Pp
|
|
This option overrides the
|
|
.Ev MACHINE
|
|
environment variable.
|
|
.It Xo
|
|
.Op Fl s
|
|
.Ar section
|
|
.Xc
|
|
Restricts the directories that
|
|
.Nm
|
|
will search to a specific section.
|
|
The currently available sections are:
|
|
.Pp
|
|
.Bl -tag -width "localXXX" -offset indent -compact
|
|
.It 1
|
|
General commands
|
|
.Pq tools and utilities .
|
|
.It 2
|
|
System calls and error numbers.
|
|
.It 3
|
|
Libraries.
|
|
.It 3f
|
|
Fortran programmer's reference guide.
|
|
.It 3p
|
|
.Xr perl 1
|
|
programmer's reference guide.
|
|
.It 4
|
|
Device drivers.
|
|
.It 5
|
|
File formats.
|
|
.It 6
|
|
Games.
|
|
.It 7
|
|
Miscellaneous.
|
|
.It 8
|
|
System maintenance and operation commands.
|
|
.It 9
|
|
Kernel internals.
|
|
.It X11
|
|
An alias for X11R6.
|
|
.It X11R6
|
|
X Window System.
|
|
.It local
|
|
Pages located in
|
|
.Pa /usr/local .
|
|
.It n
|
|
Tcl/Tk commands.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
configuration file,
|
|
.Xr man.conf 5 ,
|
|
specifies the possible
|
|
.Ar section
|
|
values, and their search order.
|
|
Additional sections may be specified.
|
|
.It Fl T Ar output
|
|
Select the output format.
|
|
The default is
|
|
.Cm locale .
|
|
The other output modes
|
|
.Cm ascii ,
|
|
.Cm html ,
|
|
.Cm lint ,
|
|
.Cm man ,
|
|
.Cm pdf ,
|
|
.Cm ps ,
|
|
.Cm tree ,
|
|
and
|
|
.Cm utf8
|
|
are described in the
|
|
.Xr mandoc 1
|
|
manual.
|
|
.It Fl W Ar level
|
|
Specify the minimum message
|
|
.Ar level
|
|
to be reported on the standard error output and to affect the exit status.
|
|
The
|
|
.Ar level
|
|
can be
|
|
.Cm warning ,
|
|
.Cm error ,
|
|
or
|
|
.Cm unsupp ;
|
|
.Cm all
|
|
is an alias for
|
|
.Cm warning .
|
|
By default,
|
|
.Nm
|
|
is silent.
|
|
See the
|
|
.Xr mandoc 1
|
|
manual for details.
|
|
.It Fl w
|
|
List the pathnames of the manual pages which
|
|
.Nm
|
|
would display for the specified
|
|
.Ar section
|
|
and
|
|
.Ar name
|
|
combination.
|
|
.El
|
|
.Pp
|
|
Guidelines for writing
|
|
man pages can be found in
|
|
.Xr mdoc 7 .
|
|
.Pp
|
|
If both a formatted and an unformatted version of the same manual page,
|
|
for example
|
|
.Pa cat1/foo.0
|
|
and
|
|
.Pa man1/foo.1 ,
|
|
exist in the same directory, and at least one of them is selected,
|
|
only the newer one is used.
|
|
However, if both the
|
|
.Fl a
|
|
and the
|
|
.Fl w
|
|
options are specified, both file names are printed.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width MANPATHX
|
|
.It Ev MACHINE
|
|
As some manual pages are intended only for specific architectures,
|
|
.Nm
|
|
searches any subdirectories,
|
|
with the same name as the current architecture,
|
|
in every directory which it searches.
|
|
Machine specific areas are checked before general areas.
|
|
The current machine type may be overridden by setting the environment
|
|
variable
|
|
.Ev MACHINE
|
|
to the name of a specific architecture,
|
|
or with the
|
|
.Fl S
|
|
option.
|
|
.Ev MACHINE
|
|
is case insensitive.
|
|
.It Ev MANPAGER
|
|
Any non-empty value of the environment variable
|
|
.Ev MANPAGER
|
|
will be used instead of the standard pagination program,
|
|
.Xr more 1 .
|
|
If
|
|
.Xr less 1
|
|
is used, the interactive
|
|
.Ic :t
|
|
command can be used to go to the definitions of various terms, for
|
|
example command line options, command modifiers, internal commands,
|
|
and environment variables.
|
|
.It Ev MANPATH
|
|
The standard search path used by
|
|
.Nm
|
|
may be overridden by specifying a path in the
|
|
.Ev MANPATH
|
|
environment
|
|
variable.
|
|
The format of the path is a colon
|
|
.Pq Ql \&:
|
|
separated list of directories.
|
|
.It Ev PAGER
|
|
Specifies the pagination program to use when
|
|
.Ev MANPAGER
|
|
is not defined.
|
|
If neither PAGER nor MANPAGER is defined,
|
|
.Xr more 1
|
|
.Fl s
|
|
will be used.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/man.conf -compact
|
|
.It Pa /etc/man.conf
|
|
default man configuration file
|
|
.El
|
|
.Sh EXIT STATUS
|
|
.Ex -std man
|
|
.Sh SEE ALSO
|
|
.Xr apropos 1 ,
|
|
.Xr intro 1 ,
|
|
.Xr whatis 1 ,
|
|
.Xr whereis 1 ,
|
|
.Xr intro 2 ,
|
|
.Xr intro 3 ,
|
|
.Xr intro 4 ,
|
|
.Xr intro 5 ,
|
|
.Xr man.conf 5 ,
|
|
.Xr intro 6 ,
|
|
.Xr intro 7 ,
|
|
.Xr mdoc 7 ,
|
|
.Xr intro 8 ,
|
|
.Xr intro 9
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility is compliant with the
|
|
.St -p1003.1-2008
|
|
specification.
|
|
.Pp
|
|
The flags
|
|
.Op Fl aCcfhIKlMmOSsTWw ,
|
|
as well as the environment variables
|
|
.Ev MACHINE ,
|
|
.Ev MANPAGER ,
|
|
and
|
|
.Ev MANPATH ,
|
|
are extensions to that specification.
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
command first appeared in
|
|
.At v3 .
|
|
.Pp
|
|
The
|
|
.Fl w
|
|
option first appeared in
|
|
.At v7 ;
|
|
.Fl f
|
|
and
|
|
.Fl k
|
|
in
|
|
.Bx 4 ;
|
|
.Fl M
|
|
in
|
|
.Bx 4.3 ;
|
|
.Fl a
|
|
in
|
|
.Bx 4.3 Tahoe ;
|
|
.Fl c
|
|
and
|
|
.Fl m
|
|
in
|
|
.Bx 4.3 Reno ;
|
|
.Fl h
|
|
in
|
|
.Bx 4.3 Net/2 ;
|
|
.Fl C
|
|
in
|
|
.Nx 1.0 ;
|
|
and
|
|
.Fl s
|
|
and
|
|
.Fl S
|
|
in
|
|
.Ox 2.3 .
|