version 1.15, 2015/07/17 22:38:29 |
version 1.41, 2022/08/04 11:32:23 |
|
|
.\" 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 |
|
|
.Nm man |
.Nm man |
.Op Fl acfhklw |
.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 |
Line 69 machine architecture |
|
Line 63 machine architecture |
|
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 |
|
|
for a description of the contents of this file. |
for a description of the contents of this file. |
.It Fl c |
.It Fl c |
Copy the manual page to the standard output instead of using |
Copy the manual page to the standard output instead of using |
.Xr more 1 |
.Xr less 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 . |
Line 137 an expression can be provided using the syntax describ |
|
Line 111 an expression can be provided using the syntax describ |
|
.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. |
Line 153 No search is done and |
|
Line 121 No search is done and |
|
.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 |
Line 221 architecture whilst using another. |
|
Line 167 architecture whilst using another. |
|
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 |
Line 237 General commands |
|
Line 180 General commands |
|
.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 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 |
Line 358 is case insensitive. |
|
Line 274 is case insensitive. |
|
.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 less 1 . |
If |
If |
.Xr less 1 |
.Xr less 1 |
is used, the interactive |
is used, the interactive |
.Ic :t |
.Ic :t |
command can be used to go to the definitions of various terms, for |
command can be used to go to the definitions of various terms, for |
example command line options, command modifiers, internal commands, |
example command line options, command modifiers, internal commands, |
and environment variables. |
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, |
.Xr more 1 |
.Xr less 1 |
.Fl s |
is used. |
will be 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 |
Line 433 are extensions to that specification. |
|
Line 381 are extensions to that specification. |
|
A |
A |
.Nm |
.Nm |
command first appeared in |
command first appeared in |
.At v3 . |
.At v2 . |
.Pp |
.Pp |
The |
The |
.Fl w |
.Fl w |
Line 443 option first appeared in |
|
Line 391 option first appeared in |
|
and |
and |
.Fl k |
.Fl k |
in |
in |
.Bx 4 ; |
.Pa /usr/usb/man |
|
in |
|
.Bx 4.0 ; |
.Fl M |
.Fl M |
in |
in |
.Bx 4.3 ; |
.Bx 4.3 ; |
|
|
.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 . |