![]() ![]() | ![]() |
version 1.12, 2015/01/20 21:16:51 | version 1.39, 2020/06/17 19:42:32 | ||
---|---|---|---|
|
|
||
.\" Copyright (c) 1989, 1990, 1993 | .\" Copyright (c) 1989, 1990, 1993 | ||
.\" The Regents of the University of California. All rights reserved. | .\" The Regents of the University of California. All rights reserved. | ||
.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org> | .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org> | ||
.\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> | .\" Copyright (c) 2010, 2011, 2014-2020 Ingo Schwarze <schwarze@openbsd.org> | ||
.\" | .\" | ||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||
|
|
||
.Nd display manual pages | .Nd display manual pages | ||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.Nm man | .Nm man | ||
.Op Fl acfhklVw | .Op Fl acfhklw | ||
.Op Fl C Ar file | .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 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 subsection | ||
.Op Fl s Ar section | .Op Oo Fl s Oc Ar section | ||
.Op Fl T Ar output | |||
.Op Fl W Ar level | |||
.Op Ar section | |||
.Ar name ... | .Ar name ... | ||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
.Nm | .Nm | ||
utility | utility | ||
displays the | displays the | ||
manual pages entitled | manual page entitled | ||
.Ar name . | .Ar name . | ||
Pages may be selected according to | Pages may be selected according to | ||
a specific category | a specific category | ||
|
|
||
The options are as follows: | The options are as follows: | ||
.Bl -tag -width Ds | .Bl -tag -width Ds | ||
.It Fl a | .It Fl a | ||
Display all of the manual pages for a specified | Display all matching manual pages. | ||
.Ar section | |||
and | |||
.Ar name | |||
combination. | |||
Normally, only the first manual page found is displayed. | |||
.It Fl C Ar file | .It Fl C Ar file | ||
Use the specified | Use the specified | ||
.Ar file | .Ar file | ||
|
|
||
.Xr more 1 | .Xr more 1 | ||
to paginate it. | to paginate it. | ||
This is done by default if the standard output is not a terminal device. | This is done by default if the standard output is not a terminal device. | ||
.Pp | |||
When using | |||
.Fl c , | |||
most terminal devices are unable to show the markup. | |||
To print the output of | |||
.Nm | |||
to the terminal with markup but without using a pager, pipe it to | |||
.Xr ul 1 . | |||
To remove the markup, pipe the output to | |||
.Xr col 1 | |||
.Fl b | |||
instead. | |||
.It Fl f | .It Fl f | ||
A synonym for | A synonym for | ||
.Xr whatis 1 . | .Xr whatis 1 . | ||
|
|
||
.Ar name | .Ar name | ||
in manual page names and displays the header lines from all matching pages. | in manual page names and displays the header lines from all matching pages. | ||
The search is case insensitive and matches whole words only. | 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 | .It Fl h | ||
Display only the SYNOPSIS lines of the requested manual pages. | Display only the SYNOPSIS lines of the requested manual pages. | ||
Implies | Implies | ||
.Fl a | .Fl a | ||
and | and | ||
.Fl c . | .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 | .It Fl k | ||
A synonym for | A synonym for | ||
.Xr apropos 1 . | .Xr apropos 1 . | ||
|
|
||
.Xr apropos 1 | .Xr apropos 1 | ||
manual. | manual. | ||
By default, it displays the header lines of all matching pages. | By default, it displays the header lines of all matching pages. | ||
This overrides any earlier | |||
.Fl f | |||
and | |||
.Fl l | |||
options. | |||
.It Fl l | .It Fl l | ||
A synonym for | A synonym for | ||
.Xr mandoc 1 | .Xr mandoc 1 . | ||
.Fl a . | |||
The | The | ||
.Ar name | .Ar name | ||
arguments are interpreted as filenames. | arguments are interpreted as filenames. | ||
|
|
||
.Ar file , | .Ar file , | ||
.Ar path , | .Ar path , | ||
.Ar section , | .Ar section , | ||
.Ar subsection , | |||
and | and | ||
.Ar subsection | |||
are ignored. | |||
This overrides any earlier | |||
.Fl f , | |||
.Fl k , | |||
and | |||
.Fl w | .Fl w | ||
options. | are ignored. | ||
This option implies | |||
.Fl a . | |||
.It Fl M Ar path | .It Fl M Ar path | ||
Override the list of standard directories which | Override the list of directories to search for manual pages. | ||
.Nm | |||
searches for manual pages. | |||
The supplied | The supplied | ||
.Ar path | .Ar path | ||
must be a colon | must be a colon | ||
.Pq Ql \&: | .Pq Ql \&: | ||
separated list of directories. | separated list of directories. | ||
This search path may also be set using the environment variable | This option also overrides the environment variable | ||
.Ev MANPATH . | .Ev MANPATH | ||
The subdirectories to be searched, and their search order, | and any directories specified in the | ||
are specified by the | .Xr man.conf 5 | ||
.Dq _subdir | file. | ||
line in the | |||
.Nm | |||
configuration file. | |||
.It Fl m Ar path | .It Fl m Ar path | ||
Augment the list of standard directories which | Augment the list of directories to search for manual pages. | ||
.Nm | |||
searches for manual pages. | |||
The supplied | The supplied | ||
.Ar path | .Ar path | ||
must be a colon | must be a colon | ||
.Pq Ql \&: | .Pq Ql \&: | ||
separated list of directories. | separated list of directories. | ||
These directories will be searched before the standard directories or | These directories will be searched before those specified using the | ||
the directories specified using the | |||
.Fl M | .Fl M | ||
option or the | option, the | ||
.Ev MANPATH | .Ev MANPATH | ||
environment variable. | environment variable, the | ||
The subdirectories to be searched, and their search order, | .Xr man.conf 5 | ||
are specified by the | file, or the default directories. | ||
.Dq _subdir | |||
line in the | |||
.Nm | |||
configuration file. | |||
.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 | .It Fl S Ar subsection | ||
Restricts the directories that | Only show pages for the specified | ||
.Nm | |||
will search to those of a specific | |||
.Xr machine 1 | .Xr machine 1 | ||
architecture. | architecture. | ||
.Ar subsection | .Ar subsection | ||
|
|
||
This option overrides the | This option overrides the | ||
.Ev MACHINE | .Ev MACHINE | ||
environment variable. | environment variable. | ||
.It Xo | .Tg s | ||
.Op Fl s | .It Oo Fl s Oc Ar section | ||
.Ar section | Only select manuals from the specified | ||
.Xc | .Ar section . | ||
Restricts the directories that | |||
.Nm | |||
will search to a specific section. | |||
The currently available sections are: | The currently available sections are: | ||
.Pp | .Pp | ||
.Bl -tag -width "localXXX" -offset indent -compact | .Bl -tag -width "localXXX" -offset indent -compact | ||
|
|
||
.It 2 | .It 2 | ||
System calls and error numbers. | System calls and error numbers. | ||
.It 3 | .It 3 | ||
Libraries. | Library functions. | ||
.It 3f | |||
Fortran programmer's reference guide. | |||
.It 3p | .It 3p | ||
.Xr perl 1 | .Xr perl 1 | ||
programmer's reference guide. | programmer's reference guide. | ||
|
|
||
.It 6 | .It 6 | ||
Games. | Games. | ||
.It 7 | .It 7 | ||
Miscellaneous. | Miscellaneous information. | ||
.It 8 | .It 8 | ||
System maintenance and operation commands. | System maintenance and operation commands. | ||
.It 9 | .It 9 | ||
Kernel internals. | 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 | .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 V | |||
Print version and exit. | |||
.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 | .It Fl w | ||
List the pathnames of the manual pages which | List the pathnames of all matching manual pages instead of displaying | ||
.Nm | any of them. | ||
would display for the specified | If no | ||
.Ar section | |||
and | |||
.Ar name | .Ar name | ||
combination. | is given, list the directories that would be searched. | ||
.El | .El | ||
.Pp | .Pp | ||
Guidelines for writing | The options | ||
man pages can be found in | .Fl IKOTW | ||
.Xr mdoc 7 . | are also supported and are documented in | ||
.Xr mandoc 1 . | |||
The options | |||
.Fl fkl | |||
are mutually exclusive and override each other. | |||
.Pp | .Pp | ||
The search starts with the | |||
.Fl m | |||
argument if provided, then continues with the | |||
.Fl M | |||
argument, the | |||
.Ev MANPATH | |||
variable, the | |||
.Ic manpath | |||
entries in the | |||
.Xr man.conf 5 | |||
file, or with | |||
.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man | |||
by default. | |||
Within each of these, directories are searched in the order provided. | |||
Within each directory, the search proceeds according to the following | |||
list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p. | |||
The first match found is shown. | |||
.Pp | |||
The | |||
.Xr mandoc.db 5 | |||
database is used for looking up manual page entries. | |||
In cases where the database is absent, outdated, or corrupt, | |||
.Nm | |||
falls back to looking for files called | |||
.Ar name . Ns Ar section . | |||
If both a formatted and an unformatted version of the same manual page, | If both a formatted and an unformatted version of the same manual page, | ||
for example | for example | ||
.Pa cat1/foo.0 | .Pa cat1/foo.0 | ||
and | and | ||
.Pa man1/foo.1 , | .Pa man1/foo.1 , | ||
exist in the same directory, and at least one of them is selected, | exist in the same directory, only the unformatted version is used. | ||
only the newer one is used. | The database is kept up to date with | ||
However, if both the | .Xr makewhatis 8 , | ||
.Fl a | which is run by the | ||
and the | .Xr weekly 8 | ||
.Fl w | maintenance script. | ||
options are specified, both file names are printed. | .Pp | ||
Guidelines for writing | |||
man pages can be found in | |||
.Xr mdoc 7 . | |||
.Sh ENVIRONMENT | .Sh ENVIRONMENT | ||
.Bl -tag -width MANPATHX | .Bl -tag -width MANPATHX | ||
.It Ev MACHINE | .It Ev MACHINE | ||
|
|
||
.It Ev MANPAGER | .It Ev MANPAGER | ||
Any non-empty value of the environment variable | Any non-empty value of the environment variable | ||
.Ev MANPAGER | .Ev MANPAGER | ||
will be used instead of the standard pagination program, | is used instead of the standard pagination program, | ||
.Xr more 1 . | .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, | |||
environment variables, function names, preprocessor macros, | |||
.Xr errno 2 | |||
values, and some other emphasized words. | |||
Some terms may have defining text at more than one place. | |||
In that case, the | |||
.Xr less 1 | |||
interactive commands | |||
.Ic t | |||
and | |||
.Ic T | |||
can be used to move to the next and to the previous place providing | |||
information about the term last searched for with | |||
.Ic :t . | |||
The | |||
.Fl O Cm tag Ns Op = Ns Ar term | |||
option documented in the | |||
.Xr mandoc 1 | |||
manual opens a manual page at the definition of a specific | |||
.Ar term | |||
rather than at the beginning. | |||
.It Ev MANPATH | .It Ev MANPATH | ||
The standard search path used by | Override the standard search path which is either specified in | ||
.Nm | .Xr man.conf 5 | ||
may be overridden by specifying a path in the | or the default path. | ||
The format of | |||
.Ev MANPATH | .Ev MANPATH | ||
environment | is a colon | ||
variable. | |||
The format of the path is a colon | |||
.Pq Ql \&: | .Pq Ql \&: | ||
separated list of directories. | separated list of directories. | ||
The subdirectories to be searched, as well as their search order, | Invalid directories are ignored. | ||
are specified by the | Overridden by | ||
.Dq _subdir | .Fl M , | ||
line in the | ignored if | ||
.Nm | .Fl l | ||
configuration file. | is specified. | ||
.Pp | |||
If | |||
.Ev MANPATH | |||
begins with a colon, it is appended to the standard path; | |||
if it ends with a colon, it is prepended to the standard path; | |||
or if it contains two adjacent colons, | |||
the standard path is inserted between the colons. | |||
.It Ev PAGER | .It Ev PAGER | ||
Specifies the pagination program to use when | Specifies the pagination program to use when | ||
.Ev MANPAGER | .Ev MANPAGER | ||
is not defined. | is not defined. | ||
If neither PAGER nor MANPAGER is defined, | If neither PAGER nor MANPAGER is defined, | ||
.Pa /usr/bin/more Fl s | .Xr more 1 | ||
will be used. | .Fl s | ||
is used. | |||
.El | .El | ||
.Sh FILES | .Sh FILES | ||
.Bl -tag -width /etc/man.conf -compact | .Bl -tag -width /etc/man.conf -compact | ||
.It Pa /etc/man.conf | .It Pa /etc/man.conf | ||
default man configuration file | default | ||
.Nm | |||
configuration file | |||
.El | .El | ||
.Sh EXIT STATUS | .Sh EXIT STATUS | ||
.Ex -std man | .Ex -std man | ||
See | |||
.Xr mandoc 1 | |||
for details. | |||
.Sh EXAMPLES | |||
Format a page for pasting extracts into an email message \(em | |||
avoid printing any UTF-8 characters, reduce the width to ease | |||
quoting in replies, and remove markup: | |||
.Pp | |||
.Dl $ man -T ascii -O width=65 pledge | col -b | |||
.Pp | |||
Read a typeset page in a PDF viewer: | |||
.Pp | |||
.Dl $ MANPAGER=mupdf man -T pdf lpd | |||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr apropos 1 , | .Xr apropos 1 , | ||
.Xr intro 1 , | .Xr col 1 , | ||
.Xr whatis 1 , | .Xr mandoc 1 , | ||
.Xr ul 1 , | |||
.Xr whereis 1 , | .Xr whereis 1 , | ||
.Xr intro 2 , | |||
.Xr intro 3 , | |||
.Xr intro 4 , | |||
.Xr intro 5 , | |||
.Xr man.conf 5 , | .Xr man.conf 5 , | ||
.Xr intro 6 , | .Xr mdoc 7 | ||
.Xr intro 7 , | |||
.Xr mdoc 7 , | |||
.Xr intro 8 , | |||
.Xr intro 9 | |||
.Sh STANDARDS | .Sh STANDARDS | ||
The | The | ||
.Nm | .Nm | ||
|
|
||
specification. | specification. | ||
.Pp | .Pp | ||
The flags | The flags | ||
.Op Fl aCcfhIKlMmOSsTVWw , | .Op Fl aCcfhIKlMmOSsTWw , | ||
as well as the environment variables | as well as the environment variables | ||
.Ev MACHINE , | .Ev MACHINE , | ||
.Ev MANPAGER , | .Ev MANPAGER , | ||
|
|
||
A | A | ||
.Nm | .Nm | ||
command first appeared in | command first appeared in | ||
.At v3 . | .At v2 . | ||
.Pp | .Pp | ||
The | The | ||
.Fl w | .Fl w | ||
|
|
||
.Fl C | .Fl C | ||
in | in | ||
.Nx 1.0 ; | .Nx 1.0 ; | ||
and | |||
.Fl s | .Fl s | ||
and | and | ||
.Fl S | .Fl S | ||
in | in | ||
.Ox 2.3 . | .Ox 2.3 ; | ||
and | |||
.Fl I , | |||
.Fl K , | |||
.Fl l , | |||
.Fl O , | |||
and | |||
.Fl W | |||
in | |||
.Ox 5.7 . | |||
The | |||
.Fl T | |||
option first appeared in | |||
.At III | |||
and was also added in | |||
.Ox 5.7 . |