[BACK]Return to man.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/man.1, Revision 1.29

1.29    ! schwarze    1: .\"    $Id: man.1,v 1.28 2017/03/27 18:51:36 schwarze Exp $
1.1       schwarze    2: .\"
                      3: .\" Copyright (c) 1989, 1990, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.2       schwarze    5: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
1.22      schwarze    6: .\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
1.1       schwarze    7: .\"
                      8: .\" Redistribution and use in source and binary forms, with or without
                      9: .\" modification, are permitted provided that the following conditions
                     10: .\" are met:
                     11: .\" 1. Redistributions of source code must retain the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer.
                     13: .\" 2. Redistributions in binary form must reproduce the above copyright
                     14: .\"    notice, this list of conditions and the following disclaimer in the
                     15: .\"    documentation and/or other materials provided with the distribution.
                     16: .\" 3. Neither the name of the University nor the names of its contributors
                     17: .\"    may be used to endorse or promote products derived from this software
                     18: .\"    without specific prior written permission.
                     19: .\"
                     20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     23: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     30: .\" SUCH DAMAGE.
                     31: .\"
                     32: .\"     @(#)man.1      8.2 (Berkeley) 1/2/94
                     33: .\"
1.28      schwarze   34: .Dd $Mdocdate: March 27 2017 $
1.1       schwarze   35: .Dt MAN 1
                     36: .Os
                     37: .Sh NAME
                     38: .Nm man
                     39: .Nd display manual pages
                     40: .Sh SYNOPSIS
                     41: .Nm man
1.13      schwarze   42: .Op Fl acfhklw
1.1       schwarze   43: .Op Fl C Ar file
                     44: .Op Fl M Ar path
                     45: .Op Fl m Ar path
                     46: .Op Fl S Ar subsection
1.28      schwarze   47: .Op Oo Fl s Oc Ar section
1.1       schwarze   48: .Ar name ...
                     49: .Sh DESCRIPTION
                     50: The
                     51: .Nm
                     52: utility
                     53: displays the
                     54: manual pages entitled
                     55: .Ar name .
                     56: Pages may be selected according to
                     57: a specific category
                     58: .Pq Ar section
                     59: or
                     60: machine architecture
                     61: .Pq Ar subsection .
                     62: .Pp
                     63: The options are as follows:
                     64: .Bl -tag -width Ds
                     65: .It Fl a
1.18      schwarze   66: Display all matching manual pages.
                     67: Normally, only the first page found is displayed.
1.1       schwarze   68: .It Fl C Ar file
                     69: Use the specified
                     70: .Ar file
                     71: instead of the default configuration file.
                     72: This permits users to configure their own manual environment.
                     73: See
                     74: .Xr man.conf 5
                     75: for a description of the contents of this file.
                     76: .It Fl c
                     77: Copy the manual page to the standard output instead of using
                     78: .Xr more 1
                     79: to paginate it.
                     80: This is done by default if the standard output is not a terminal device.
1.2       schwarze   81: .It Fl f
1.1       schwarze   82: A synonym for
                     83: .Xr whatis 1 .
1.2       schwarze   84: It searches for
                     85: .Ar name
                     86: in manual page names and displays the header lines from all matching pages.
                     87: The search is case insensitive and matches whole words only.
1.20      schwarze   88: .It Fl h
                     89: Display only the SYNOPSIS lines of the requested manual pages.
                     90: Implies
                     91: .Fl a
                     92: and
                     93: .Fl c .
1.2       schwarze   94: .It Fl k
1.1       schwarze   95: A synonym for
                     96: .Xr apropos 1 .
1.2       schwarze   97: Instead of
                     98: .Ar name ,
                     99: an expression can be provided using the syntax described in the
                    100: .Xr apropos 1
                    101: manual.
                    102: By default, it displays the header lines of all matching pages.
1.4       schwarze  103: .It Fl l
                    104: A synonym for
                    105: .Xr mandoc 1
                    106: .Fl a .
                    107: The
                    108: .Ar name
                    109: arguments are interpreted as filenames.
                    110: No search is done and
                    111: .Ar file ,
                    112: .Ar path ,
                    113: .Ar section ,
1.27      schwarze  114: .Ar subsection ,
1.4       schwarze  115: and
1.27      schwarze  116: .Fl w
1.4       schwarze  117: are ignored.
1.1       schwarze  118: .It Fl M Ar path
                    119: Override the list of standard directories which
                    120: .Nm
                    121: searches for manual pages.
                    122: The supplied
                    123: .Ar path
                    124: must be a colon
                    125: .Pq Ql \&:
                    126: separated list of directories.
                    127: This search path may also be set using the environment variable
                    128: .Ev MANPATH .
                    129: .It Fl m Ar path
                    130: Augment the list of standard directories which
                    131: .Nm
                    132: searches for manual pages.
                    133: The supplied
                    134: .Ar path
                    135: must be a colon
                    136: .Pq Ql \&:
                    137: separated list of directories.
                    138: These directories will be searched before the standard directories or
                    139: the directories specified using the
                    140: .Fl M
                    141: option or the
                    142: .Ev MANPATH
                    143: environment variable.
                    144: .It Fl S Ar subsection
1.25      schwarze  145: Only show pages for the specified
1.1       schwarze  146: .Xr machine 1
                    147: architecture.
                    148: .Ar subsection
                    149: is case insensitive.
                    150: .Pp
                    151: By default manual pages for all architectures are installed.
                    152: Therefore this option can be used to view pages for one
                    153: architecture whilst using another.
                    154: .Pp
                    155: This option overrides the
                    156: .Ev MACHINE
                    157: environment variable.
1.17      schwarze  158: .It Oo Fl s Oc Ar section
                    159: Only select manuals from the specified
                    160: .Ar section .
1.1       schwarze  161: The currently available sections are:
                    162: .Pp
                    163: .Bl -tag -width "localXXX" -offset indent -compact
                    164: .It 1
                    165: General commands
                    166: .Pq tools and utilities .
                    167: .It 2
                    168: System calls and error numbers.
                    169: .It 3
1.17      schwarze  170: Library functions.
1.1       schwarze  171: .It 3p
                    172: .Xr perl 1
                    173: programmer's reference guide.
                    174: .It 4
                    175: Device drivers.
                    176: .It 5
                    177: File formats.
                    178: .It 6
                    179: Games.
                    180: .It 7
1.17      schwarze  181: Miscellaneous information.
1.1       schwarze  182: .It 8
                    183: System maintenance and operation commands.
                    184: .It 9
                    185: Kernel internals.
                    186: .El
1.22      schwarze  187: .Pp
                    188: If not specified and a match is found in more than one section,
                    189: the first match is selected from the following list:
                    190: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
1.1       schwarze  191: .It Fl w
1.25      schwarze  192: List the pathnames of all matching manual pages instead of displaying
                    193: any of them.
1.1       schwarze  194: .El
1.26      schwarze  195: .Pp
                    196: The options
                    197: .Fl IKOTW
                    198: are also supported and are documented in
                    199: .Xr mandoc 1 .
1.27      schwarze  200: The options
                    201: .Fl fkl
                    202: are mutually exclusive and override each other.
1.1       schwarze  203: .Pp
1.2       schwarze  204: Guidelines for writing
1.1       schwarze  205: man pages can be found in
                    206: .Xr mdoc 7 .
                    207: .Pp
                    208: If both a formatted and an unformatted version of the same manual page,
                    209: for example
                    210: .Pa cat1/foo.0
                    211: and
                    212: .Pa man1/foo.1 ,
1.24      schwarze  213: exist in the same directory, only the unformatted version is used.
1.1       schwarze  214: .Sh ENVIRONMENT
                    215: .Bl -tag -width MANPATHX
                    216: .It Ev MACHINE
                    217: As some manual pages are intended only for specific architectures,
                    218: .Nm
                    219: searches any subdirectories,
                    220: with the same name as the current architecture,
                    221: in every directory which it searches.
                    222: Machine specific areas are checked before general areas.
                    223: The current machine type may be overridden by setting the environment
                    224: variable
                    225: .Ev MACHINE
                    226: to the name of a specific architecture,
                    227: or with the
                    228: .Fl S
                    229: option.
                    230: .Ev MACHINE
                    231: is case insensitive.
                    232: .It Ev MANPAGER
                    233: Any non-empty value of the environment variable
                    234: .Ev MANPAGER
1.23      schwarze  235: is used instead of the standard pagination program,
1.1       schwarze  236: .Xr more 1 .
1.15      schwarze  237: If
                    238: .Xr less 1
                    239: is used, the interactive
                    240: .Ic :t
                    241: command can be used to go to the definitions of various terms, for
                    242: example command line options, command modifiers, internal commands,
1.19      schwarze  243: environment variables, function names, preprocessor macros,
                    244: .Xr errno 2
                    245: values, and some other emphasized words.
                    246: Some terms may have defining text at more than one place.
                    247: In that case, the
                    248: .Xr less 1
                    249: interactive commands
                    250: .Ic t
                    251: and
                    252: .Ic T
                    253: can be used to move to the next and to the previous place providing
                    254: information about the term last searched for with
                    255: .Ic :t .
1.1       schwarze  256: .It Ev MANPATH
                    257: The standard search path used by
                    258: .Nm
1.23      schwarze  259: may be changed by specifying a path in the
1.1       schwarze  260: .Ev MANPATH
1.23      schwarze  261: environment variable.
1.1       schwarze  262: The format of the path is a colon
                    263: .Pq Ql \&:
                    264: separated list of directories.
1.29    ! schwarze  265: Invalid paths are ignored.
1.23      schwarze  266: Overridden by
                    267: .Fl M ,
                    268: ignored if
                    269: .Fl l
                    270: is specified.
                    271: .Pp
                    272: If
                    273: .Ev MANPATH
                    274: begins with a colon, it is appended to the default list;
                    275: if it ends with a colon, it is prepended to the default list;
                    276: or if it contains two adjacent colons,
                    277: the standard search path is inserted between the colons.
                    278: If none of these conditions are met, it overrides the
                    279: standard search path.
1.1       schwarze  280: .It Ev PAGER
                    281: Specifies the pagination program to use when
                    282: .Ev MANPAGER
                    283: is not defined.
                    284: If neither PAGER nor MANPAGER is defined,
1.14      schwarze  285: .Xr more 1
                    286: .Fl s
1.23      schwarze  287: is used.
                    288: Only used if
                    289: .Fl a
                    290: or
                    291: .Fl l
                    292: is specified.
1.1       schwarze  293: .El
                    294: .Sh FILES
                    295: .Bl -tag -width /etc/man.conf -compact
                    296: .It Pa /etc/man.conf
                    297: default man configuration file
                    298: .El
                    299: .Sh EXIT STATUS
                    300: .Ex -std man
1.25      schwarze  301: See
                    302: .Xr mandoc 1
                    303: for details.
1.1       schwarze  304: .Sh SEE ALSO
                    305: .Xr apropos 1 ,
                    306: .Xr intro 1 ,
                    307: .Xr whereis 1 ,
                    308: .Xr intro 2 ,
                    309: .Xr intro 3 ,
                    310: .Xr intro 4 ,
                    311: .Xr intro 5 ,
                    312: .Xr man.conf 5 ,
                    313: .Xr intro 6 ,
                    314: .Xr intro 7 ,
                    315: .Xr mdoc 7 ,
                    316: .Xr intro 8 ,
                    317: .Xr intro 9
                    318: .Sh STANDARDS
                    319: The
                    320: .Nm
                    321: utility is compliant with the
                    322: .St -p1003.1-2008
                    323: specification.
                    324: .Pp
                    325: The flags
1.13      schwarze  326: .Op Fl aCcfhIKlMmOSsTWw ,
1.1       schwarze  327: as well as the environment variables
                    328: .Ev MACHINE ,
                    329: .Ev MANPAGER ,
                    330: and
                    331: .Ev MANPATH ,
                    332: are extensions to that specification.
                    333: .Sh HISTORY
                    334: A
                    335: .Nm
                    336: command first appeared in
                    337: .At v3 .
                    338: .Pp
                    339: The
                    340: .Fl w
                    341: option first appeared in
                    342: .At v7 ;
                    343: .Fl f
                    344: and
                    345: .Fl k
                    346: in
                    347: .Bx 4 ;
                    348: .Fl M
                    349: in
                    350: .Bx 4.3 ;
                    351: .Fl a
                    352: in
                    353: .Bx 4.3 Tahoe ;
                    354: .Fl c
                    355: and
                    356: .Fl m
                    357: in
                    358: .Bx 4.3 Reno ;
                    359: .Fl h
                    360: in
                    361: .Bx 4.3 Net/2 ;
                    362: .Fl C
                    363: in
                    364: .Nx 1.0 ;
                    365: .Fl s
                    366: and
                    367: .Fl S
                    368: in
1.21      schwarze  369: .Ox 2.3 ;
                    370: and
                    371: .Fl I ,
                    372: .Fl K ,
                    373: .Fl l ,
                    374: .Fl O ,
                    375: and
                    376: .Fl W
                    377: in
                    378: .Ox 5.7 .
                    379: The
                    380: .Fl T
                    381: option first appeared in
                    382: .At III
                    383: and was also added in
                    384: .Ox 5.7 .

CVSweb