NetBSD/usr.bin/man/man.1

.\"	$NetBSD: man.1,v 1.29 2016/06/16 15:10:58 abhinav Exp $
.\"
.\" Copyright (c) 1989, 1990, 1993
.\"	The Regents of the University of California.  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.
.\" 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 June 16, 2016
.Dt MAN 1
.Os
.Sh NAME
.Nm man
.Nd display the on-line manual pages
.Pq aka Dq Em man pages
.Sh SYNOPSIS
.Nm
.Oo Fl acw Ns \&| Ns Fl h Oc
.Op Fl C Ar file
.Op Fl M Ar path
.Op Fl m Ar path
.Op Fl S Ar srch
.Oo
.Op Fl s
.Ar section
.Oc
.Ar name Ar ...
.Nm
.Op Fl C Ar file
.Fl f
.Ar command Ar ...
.Nm
.Op Fl C Ar file
.Fl k
.Ar keyword Ar ...
.Nm
.Fl p
.Sh DESCRIPTION
The
.Nm
utility displays the manual pages named on the command line.
Its options are as follows:
.Bl -tag -width indent
.It Fl a
Display all of the man pages for a specified
.Ar section
and
.Ar name
combination.
(Normally, only the first man page found is displayed.)
.It Fl C
Use the specified
.Ar file
instead of the default configuration file.
This permits users to configure their own man environment.
See
.Xr man.conf 5
for a description of the contents of this file.
.It Fl c
Copy the man 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
Synonym for
.Xr whatis 1 .
It searches man pages for
.Ar command
in their names and displays header lines from all matching pages.
.It Fl h
Display only the
.Dq Tn SYNOPSIS
lines of the requested man pages.
For commands, this is typically the command line usage information.
For library functions, this usually contains the required include
files and function prototypes.
.It Fl k
Search man pages for
.Ar keyword Ns Pq s ,
in the same manner as
.Xr apropos 1 .
.It Fl M
Override the list of standard directories which
.Nm
searches for man pages.
The supplied
.Ar path
must be a colon
.Pq Dq \&:
separated list of directories.
This search path may also be set using the environment variable
.Ev MANPATH .
The subdirectories to be searched, and their search order,
is specified by the
.Dq _subdir
line in the
.Nm
configuration file.
.It Fl m
Augment the list of standard directories which
.Nm
searches for man pages.
The supplied
.Ar path
must be a colon
.Pq Dq \&:
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.
The subdirectories to be searched, and their search order,
is specified by the
.Dq _subdir
line in the
.Nm
configuration file.
.It Fl p
Print the search path for the manual pages.
.It Fl s
Restrict the directories that
.Nm
will search to the specified section.
The
.Nm
configuration file (see
.Xr man.conf 5 )
specifies the possible
.Ar section
values that are currently available.
.It Fl S
Display only man pages that have the specified string in the directory
part of their filenames.
This allows the man page search process criteria to be
narrowed without having to change the MANPATH or
.Dq _default
variables.
.It Fl w
List the pathnames of the man pages which
.Nm
would display for the specified
.Ar section
and
.Ar name
combination.
.El
.Pp
If the
.Ql Fl s
option is not specified,
there is more than one argument,
the
.Ql Fl k
option is not used, and the first argument is a valid section, then that
argument will be used as if specified by the
.Ql Fl s
option.
.Pp
If
.Ar name
is given with a full path (beginning with
.Ql Pa \&/ )
or a relative path that begins with
.Ql Pa .\&/
or
.Ql Pa .\&./ ,
then
.Nm
interprets it as a file specification, so that you can do
.Nm
.Cm ./foo.5
or even
.Nm
.Cm /cd/foo/bar.1.gz .
If
.Ar name
contains
.Ql Pa /
but does not match one of the above cases, then the
search path is used; this allows you to request
machine-specific man pages, such as
.Nm Cm vax/boot .
.Sh ENVIRONMENT
.Bl -tag -width MANPATHX
.It Ev MACHINE
As some man 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.
Machine-specific man pages may also be requested by
prepending the relevant subdirectory name to the page name,
separated by
.Ql Pa \&/ .
.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 Dq \&:
separated list of directories.
The subdirectories to be searched as well as their search order
is specified by the
.Dq _subdir
line in the
.Nm
configuration file.
.It Ev PAGER
The pagination command used for writing the output.
If the
.Ev PAGER
environment variable is null or not set, the standard pagination program
.Xr more 1
will be used.
.El
.Sh FILES
.Bl -hang -width /etc/man.conf -compact
.It Pa /etc/man.conf
default man configuration file.
.El
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr whatis 1 ,
.Xr whereis 1 ,
.Xr man.conf 5 ,
.Xr mdoc 7 ,
.Xr mdoc.samples 7
.Sh STANDARDS
.Nm
conforms to
.St -xcu5 .
.\"and is expected to conform to
.\".St -p1003.2-?? .
.Sh BUGS
The on-line man pages are, by necessity, forgiving toward stupid
display devices, causing a few man pages to be not as nicely formatted
as their typeset counterparts.