-.\" $OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc Exp $
+.\" $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
.\"
.\" @(#)man.1 8.2 (Berkeley) 1/2/94
.\"
-.Dd $Mdocdate: August 21 2014 $
+.Dd $Mdocdate: July 20 2020 $
.Dt MAN 1
.Os
.Sh NAME
.Nd display manual pages
.Sh SYNOPSIS
.Nm man
-.Op Fl achw
+.Op Fl acfhklw
.Op Fl C Ar file
.Op Fl M Ar path
.Op Fl m Ar path
.Op Fl S Ar subsection
-.Op Fl s Ar section
-.Op Ar section
+.Op Oo Fl s Oc Ar section
.Ar name ...
-.Nm man
-.Fl f Ar command ...
-.Nm man
-.Fl k Ar keyword ...
.Sh DESCRIPTION
The
.Nm
utility
displays the
-.Bx
-manual pages entitled
+manual page entitled
.Ar name .
Pages may be selected according to
a specific category
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.
+Display all matching manual pages.
.It Fl C Ar file
Use the specified
.Ar file
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
+.Xr less 1
to paginate it.
This is done by default if the standard output is not a terminal device.
-.It Fl f Ar command
+.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 looks up a given command and
-gives the header line from the manual page.
-.Ar command
-is case insensitive.
+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
-.Dq SYNOPSIS
-lines of the requested manual pages.
-.It Fl k Ar keyword
+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 .
-It shows which manual pages contain instances of any of the given
-keywords in their title line.
-.Ar keyword
-is case insensitive.
-.Pp
-For instance,
-to list all man pages which contain
-.Dq mount
-in the
-.Dq NAME
-line of the man page:
-.Pp
-.Dl $ man -k mount
-.Pp
-Which would produce a list much like this:
-.Bd -literal
-amd (8) \(en automatically mount file systems
-amq (8) \(en automounter query tool
-domountroothooks (9) \(en run all mountroot hooks
-exports (5) \(en define remote mount points for NFS mount requests
-getfsstat (2) \(en get list of all mounted file systems
-getmntinfo (3) \(en get information about mounted file systems
-mount (8) \(en mount file systems
-mount, unmount (2) \(en mount or dismount a filesystem
-mount_cd9660 (8) \(en mount an ISO-9660 filesystem
-mount_ext2fs (8) \(en mount an ext2fs file system
-mount_ffs (8) \(en mount a Berkeley Fast File System
-mount_msdos (8) \(en mount an MS-DOS file system
-mount_nfs (8) \(en mount NFS file systems
-mount_ntfs (8) \(en mount an NTFS file system
-mount_procfs (8) \(en mount the process file system
-mount_udf (8) \(en mount a UDF filesystem
-mount_vnd, vnconfig (8) \(en configure vnode disks
-mountd (8) \(en service remote NFS mount requests
-\&...
-.Ed
+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 standard directories which
-.Nm
-searches for manual pages.
+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 search path may also be set using the environment variable
-.Ev MANPATH .
-The subdirectories to be searched, and their search order,
-are specified by the
-.Dq _subdir
-line in the
-.Nm
-configuration file.
+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 standard directories which
-.Nm
-searches for manual pages.
+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 the standard directories or
-the directories specified using the
+These directories will be searched before those specified using the
.Fl M
-option or the
+option, the
.Ev MANPATH
-environment variable.
-The subdirectories to be searched, and their search order,
-are specified by the
-.Dq _subdir
-line in the
-.Nm
-configuration file.
+environment variable, the
+.Xr man.conf 5
+file, or the default directories.
.It Fl S Ar subsection
-Restricts the directories that
-.Nm
-will search to those of a specific
+Only show pages for the specified
.Xr machine 1
architecture.
.Ar subsection
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.
+.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 2
System calls and error numbers.
.It 3
-Libraries.
-.It 3f
-Fortran programmer's reference guide.
+Library functions.
.It 3p
.Xr perl 1
programmer's reference guide.
.It 6
Games.
.It 7
-Miscellaneous.
+Miscellaneous information.
.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 w
-List the pathnames of the manual pages which
-.Nm
-would display for the specified
-.Ar section
-and
+List the pathnames of all matching manual pages instead of displaying
+any of them.
+If no
.Ar name
-combination.
+is given, list the directories that would be searched.
.El
.Pp
-Guidelines for
-.Ox
-man pages can be found in
-.Xr mdoc 7 .
+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, 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.
+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
.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 .
+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
-The standard search path used by
-.Nm
-may be overridden by specifying a path in the
+Override the standard search path which is either specified in
+.Xr man.conf 5
+or the default path.
+The format of
.Ev MANPATH
-environment
-variable.
-The format of the path is a colon
+is a colon
.Pq Ql \&:
separated list of directories.
-The subdirectories to be searched, as well as their search order,
-are specified by the
-.Dq _subdir
-line in the
-.Nm
-configuration file.
+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,
-.Pa /usr/bin/more Fl s
-will be used.
+.Xr less 1
+is used.
.El
.Sh FILES
.Bl -tag -width /etc/man.conf -compact
.It Pa /etc/man.conf
-default man configuration file
+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 intro 1 ,
-.Xr whatis 1 ,
+.Xr col 1 ,
+.Xr mandoc 1 ,
+.Xr ul 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
+.Xr mdoc 7
.Sh STANDARDS
The
.Nm
specification.
.Pp
The flags
-.Op Fl aCcfhMmSsw ,
+.Op Fl aCcfhIKlMmOSsTWw ,
as well as the environment variables
.Ev MACHINE ,
.Ev MANPAGER ,
A
.Nm
command first appeared in
-.At v3 .
+.At v2 .
.Pp
The
.Fl w
.Fl C
in
.Nx 1.0 ;
-and
.Fl s
and
.Fl S
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 .
git.ckatri.com / mandoc.git / blobdiff