man.1

   1 .\"     $Id: man.1,v 1.29 2017/05/17 23:23:00 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
   6 .\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
   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 .\"
  34 .Dd $Mdocdate: May 17 2017 $
  35 .Dt MAN 1
  36 .Os
  37 .Sh NAME
  38 .Nm man
  39 .Nd display manual pages
  40 .Sh SYNOPSIS
  41 .Nm man
  42 .Op Fl acfhklw
  43 .Op Fl C Ar file
  44 .Op Fl M Ar path
  45 .Op Fl m Ar path
  46 .Op Fl S Ar subsection
  47 .Op Oo Fl s Oc Ar section
  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
  66 Display all matching manual pages.
  67 Normally, only the first page found is displayed.
  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.
  81 .It Fl f
  82 A synonym for
  83 .Xr whatis 1 .
  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.
  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 .
  94 .It Fl k
  95 A synonym for
  96 .Xr apropos 1 .
  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.
 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 ,
 114 .Ar subsection ,
 115 and
 116 .Fl w
 117 are ignored.
 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
 145 Only show pages for the specified
 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.
 158 .It Oo Fl s Oc Ar section
 159 Only select manuals from the specified
 160 .Ar section .
 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
 170 Library functions.
 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
 181 Miscellaneous information.
 182 .It 8
 183 System maintenance and operation commands.
 184 .It 9
 185 Kernel internals.
 186 .El
 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.
 191 .It Fl w
 192 List the pathnames of all matching manual pages instead of displaying
 193 any of them.
 194 .El
 195 .Pp
 196 The options
 197 .Fl IKOTW
 198 are also supported and are documented in
 199 .Xr mandoc 1 .
 200 The options
 201 .Fl fkl
 202 are mutually exclusive and override each other.
 203 .Pp
 204 Guidelines for writing
 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 ,
 213 exist in the same directory, only the unformatted version is used.
 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
 235 is used instead of the standard pagination program,
 236 .Xr more 1 .
 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,
 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 .
 256 .It Ev MANPATH
 257 The standard search path used by
 258 .Nm
 259 may be changed by specifying a path in the
 260 .Ev MANPATH
 261 environment variable.
 262 The format of the path is a colon
 263 .Pq Ql \&:
 264 separated list of directories.
 265 Invalid paths are ignored.
 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.
 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,
 285 .Xr more 1
 286 .Fl s
 287 is used.
 288 Only used if
 289 .Fl a
 290 or
 291 .Fl l
 292 is specified.
 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
 301 See
 302 .Xr mandoc 1
 303 for details.
 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
 326 .Op Fl aCcfhIKlMmOSsTWw ,
 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
 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 .