man.1 (9833B)
- .\" $Id: man.1,v 1.40 2020/07/20 16:57:30 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-2020 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: July 20 2020 $
- .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 M Ar path
- .Op Fl m Ar path
- .Op Fl S Ar subsection
- .Op Oo Fl s Oc Ar section
- .Ar name ...
- .Sh DESCRIPTION
- The
- .Nm
- utility
- displays the
- manual page 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 matching manual pages.
- .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 less 1
- to paginate it.
- 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
- 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.
- .It Fl h
- Display only the SYNOPSIS lines of the requested manual pages.
- Implies
- .Fl a
- and
- .Fl c .
- .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.
- .It Fl l
- A synonym for
- .Xr mandoc 1 .
- The
- .Ar name
- arguments are interpreted as filenames.
- No search is done and
- .Ar file ,
- .Ar path ,
- .Ar section ,
- .Ar subsection ,
- and
- .Fl w
- are ignored.
- This option implies
- .Fl a .
- .It Fl M Ar path
- Override the list of directories to search for manual pages.
- The supplied
- .Ar path
- must be a colon
- .Pq Ql \&:
- separated list of directories.
- This option also overrides the environment variable
- .Ev MANPATH
- and any directories specified in the
- .Xr man.conf 5
- file.
- .It Fl m Ar path
- Augment the list of directories to search for manual pages.
- The supplied
- .Ar path
- must be a colon
- .Pq Ql \&:
- separated list of directories.
- These directories will be searched before those specified using the
- .Fl M
- option, the
- .Ev MANPATH
- environment variable, the
- .Xr man.conf 5
- file, or the default directories.
- .It Fl S Ar subsection
- Only show pages for the specified
- .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.
- .Tg s
- .It Oo Fl s Oc Ar section
- Only select manuals from the specified
- .Ar 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
- Library functions.
- .It 3p
- .Xr perl 1
- programmer's reference guide.
- .It 4
- Device drivers.
- .It 5
- File formats.
- .It 6
- Games.
- .It 7
- Miscellaneous information.
- .It 8
- System maintenance and operation commands.
- .It 9
- Kernel internals.
- .El
- .It Fl w
- List the pathnames of all matching manual pages instead of displaying
- any of them.
- If no
- .Ar name
- is given, list the directories that would be searched.
- .El
- .Pp
- The options
- .Fl IKOTW
- are also supported and are documented in
- .Xr mandoc 1 .
- The options
- .Fl fkl
- are mutually exclusive and override each other.
- .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,
- for example
- .Pa cat1/foo.0
- and
- .Pa man1/foo.1 ,
- exist in the same directory, only the unformatted version is used.
- The database is kept up to date with
- .Xr makewhatis 8 ,
- which is run by the
- .Xr weekly 8
- maintenance script.
- .Pp
- Guidelines for writing
- man pages can be found in
- .Xr mdoc 7 .
- .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
- is used instead of the standard pagination program,
- .Xr less 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
- Override the standard search path which is either specified in
- .Xr man.conf 5
- or the default path.
- The format of
- .Ev MANPATH
- is a colon
- .Pq Ql \&:
- separated list of directories.
- Invalid directories are ignored.
- Overridden by
- .Fl M ,
- ignored if
- .Fl l
- 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
- Specifies the pagination program to use when
- .Ev MANPAGER
- is not defined.
- If neither PAGER nor MANPAGER is defined,
- .Xr less 1
- is used.
- .El
- .Sh FILES
- .Bl -tag -width /etc/man.conf -compact
- .It Pa /etc/man.conf
- default
- .Nm
- configuration file
- .El
- .Sh EXIT STATUS
- .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
- .Xr apropos 1 ,
- .Xr col 1 ,
- .Xr mandoc 1 ,
- .Xr ul 1 ,
- .Xr whereis 1 ,
- .Xr man.conf 5 ,
- .Xr mdoc 7
- .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 v2 .
- .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 ;
- .Fl s
- and
- .Fl S
- in
- .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 .