man.1

   1 .\"     $Id: man.1,v 1.15 2015/07/17 22:38:29 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, 2015 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: July 17 2015 $
  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 I Cm os Ns = Ns Ar name
  45 .Op Fl K Ar encoding
  46 .Op Fl M Ar path
  47 .Op Fl m Ar path
  48 .Op Fl O Ar option Ns = Ns Ar value
  49 .Op Fl S Ar subsection
  50 .Op Fl s Ar section
  51 .Op Fl T Ar output
  52 .Op Fl W Ar level
  53 .Op Ar section
  54 .Ar name ...
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility
  59 displays the
  60 manual pages entitled
  61 .Ar name .
  62 Pages may be selected according to
  63 a specific category
  64 .Pq Ar section
  65 or
  66 machine architecture
  67 .Pq Ar subsection .
  68 .Pp
  69 The options are as follows:
  70 .Bl -tag -width Ds
  71 .It Fl a
  72 Display all of the manual pages for a specified
  73 .Ar section
  74 and
  75 .Ar name
  76 combination.
  77 Normally, only the first manual page found is displayed.
  78 .It Fl C Ar file
  79 Use the specified
  80 .Ar file
  81 instead of the default configuration file.
  82 This permits users to configure their own manual environment.
  83 See
  84 .Xr man.conf 5
  85 for a description of the contents of this file.
  86 .It Fl c
  87 Copy the manual page to the standard output instead of using
  88 .Xr more 1
  89 to paginate it.
  90 This is done by default if the standard output is not a terminal device.
  91 .It Fl f
  92 A synonym for
  93 .Xr whatis 1 .
  94 It searches for
  95 .Ar name
  96 in manual page names and displays the header lines from all matching pages.
  97 The search is case insensitive and matches whole words only.
  98 This overrides any earlier
  99 .Fl k
 100 and
 101 .Fl l
 102 options.
 103 .It Fl I Cm os Ns = Ns Ar name
 104 Override the default operating system
 105 .Ar name
 106 for the
 107 .Xr mdoc 7
 108 .Ic \&Os
 109 and for the
 110 .Xr man 7
 111 .Ic \&TH
 112 macro.
 113 .It Fl h
 114 Display only the SYNOPSIS lines of the requested manual pages.
 115 Implies
 116 .Fl a
 117 and
 118 .Fl c .
 119 .It Fl K Ar encoding
 120 Specify the input encoding.
 121 The supported
 122 .Ar encoding
 123 arguments are
 124 .Cm us-ascii ,
 125 .Cm iso-8859-1 ,
 126 and
 127 .Cm utf-8 .
 128 By default, the encoding is automatically detected as described in the
 129 .Xr mandoc 1
 130 manual.
 131 .It Fl k
 132 A synonym for
 133 .Xr apropos 1 .
 134 Instead of
 135 .Ar name ,
 136 an expression can be provided using the syntax described in the
 137 .Xr apropos 1
 138 manual.
 139 By default, it displays the header lines of all matching pages.
 140 This overrides any earlier
 141 .Fl f
 142 and
 143 .Fl l
 144 options.
 145 .It Fl l
 146 A synonym for
 147 .Xr mandoc 1
 148 .Fl a .
 149 The
 150 .Ar name
 151 arguments are interpreted as filenames.
 152 No search is done and
 153 .Ar file ,
 154 .Ar path ,
 155 .Ar section ,
 156 and
 157 .Ar subsection
 158 are ignored.
 159 This overrides any earlier
 160 .Fl f ,
 161 .Fl k ,
 162 and
 163 .Fl w
 164 options.
 165 .It Fl M Ar path
 166 Override the list of standard directories which
 167 .Nm
 168 searches for manual pages.
 169 The supplied
 170 .Ar path
 171 must be a colon
 172 .Pq Ql \&:
 173 separated list of directories.
 174 This search path may also be set using the environment variable
 175 .Ev MANPATH .
 176 The subdirectories to be searched, and their search order,
 177 are specified by the
 178 .Dq _subdir
 179 line in the
 180 .Nm
 181 configuration file.
 182 .It Fl m Ar path
 183 Augment the list of standard directories which
 184 .Nm
 185 searches for manual pages.
 186 The supplied
 187 .Ar path
 188 must be a colon
 189 .Pq Ql \&:
 190 separated list of directories.
 191 These directories will be searched before the standard directories or
 192 the directories specified using the
 193 .Fl M
 194 option or the
 195 .Ev MANPATH
 196 environment variable.
 197 The subdirectories to be searched, and their search order,
 198 are specified by the
 199 .Dq _subdir
 200 line in the
 201 .Nm
 202 configuration file.
 203 .It Fl O Ar option Ns = Ns Ar value
 204 Comma-separated output options.
 205 For each output format, the available options are described in the
 206 .Xr mandoc 1
 207 manual.
 208 .It Fl S Ar subsection
 209 Restricts the directories that
 210 .Nm
 211 will search to those of a specific
 212 .Xr machine 1
 213 architecture.
 214 .Ar subsection
 215 is case insensitive.
 216 .Pp
 217 By default manual pages for all architectures are installed.
 218 Therefore this option can be used to view pages for one
 219 architecture whilst using another.
 220 .Pp
 221 This option overrides the
 222 .Ev MACHINE
 223 environment variable.
 224 .It Xo
 225 .Op Fl s
 226 .Ar section
 227 .Xc
 228 Restricts the directories that
 229 .Nm
 230 will search to a specific section.
 231 The currently available sections are:
 232 .Pp
 233 .Bl -tag -width "localXXX" -offset indent -compact
 234 .It 1
 235 General commands
 236 .Pq tools and utilities .
 237 .It 2
 238 System calls and error numbers.
 239 .It 3
 240 Libraries.
 241 .It 3f
 242 Fortran programmer's reference guide.
 243 .It 3p
 244 .Xr perl 1
 245 programmer's reference guide.
 246 .It 4
 247 Device drivers.
 248 .It 5
 249 File formats.
 250 .It 6
 251 Games.
 252 .It 7
 253 Miscellaneous.
 254 .It 8
 255 System maintenance and operation commands.
 256 .It 9
 257 Kernel internals.
 258 .It X11
 259 An alias for X11R6.
 260 .It X11R6
 261 X Window System.
 262 .It local
 263 Pages located in
 264 .Pa /usr/local .
 265 .It n
 266 Tcl/Tk commands.
 267 .El
 268 .Pp
 269 The
 270 .Nm
 271 configuration file,
 272 .Xr man.conf 5 ,
 273 specifies the possible
 274 .Ar section
 275 values, and their search order.
 276 Additional sections may be specified.
 277 .It Fl T Ar output
 278 Select the output format.
 279 The default is
 280 .Cm locale .
 281 The other output modes
 282 .Cm ascii ,
 283 .Cm html ,
 284 .Cm lint ,
 285 .Cm man ,
 286 .Cm pdf ,
 287 .Cm ps ,
 288 .Cm tree ,
 289 and
 290 .Cm utf8
 291 are described in the
 292 .Xr mandoc 1
 293 manual.
 294 .It Fl W Ar level
 295 Specify the minimum message
 296 .Ar level
 297 to be reported on the standard error output and to affect the exit status.
 298 The
 299 .Ar level
 300 can be
 301 .Cm warning ,
 302 .Cm error ,
 303 or
 304 .Cm unsupp ;
 305 .Cm all
 306 is an alias for
 307 .Cm warning .
 308 By default,
 309 .Nm
 310 is silent.
 311 See the
 312 .Xr mandoc 1
 313 manual for details.
 314 .It Fl w
 315 List the pathnames of the manual pages which
 316 .Nm
 317 would display for the specified
 318 .Ar section
 319 and
 320 .Ar name
 321 combination.
 322 .El
 323 .Pp
 324 Guidelines for writing
 325 man pages can be found in
 326 .Xr mdoc 7 .
 327 .Pp
 328 If both a formatted and an unformatted version of the same manual page,
 329 for example
 330 .Pa cat1/foo.0
 331 and
 332 .Pa man1/foo.1 ,
 333 exist in the same directory, and at least one of them is selected,
 334 only the newer one is used.
 335 However, if both the
 336 .Fl a
 337 and the
 338 .Fl w
 339 options are specified, both file names are printed.
 340 .Sh ENVIRONMENT
 341 .Bl -tag -width MANPATHX
 342 .It Ev MACHINE
 343 As some manual pages are intended only for specific architectures,
 344 .Nm
 345 searches any subdirectories,
 346 with the same name as the current architecture,
 347 in every directory which it searches.
 348 Machine specific areas are checked before general areas.
 349 The current machine type may be overridden by setting the environment
 350 variable
 351 .Ev MACHINE
 352 to the name of a specific architecture,
 353 or with the
 354 .Fl S
 355 option.
 356 .Ev MACHINE
 357 is case insensitive.
 358 .It Ev MANPAGER
 359 Any non-empty value of the environment variable
 360 .Ev MANPAGER
 361 will be used instead of the standard pagination program,
 362 .Xr more 1 .
 363 If
 364 .Xr less 1
 365 is used, the interactive
 366 .Ic :t
 367 command can be used to go to the definitions of various terms, for
 368 example command line options, command modifiers, internal commands,
 369 and environment variables.
 370 .It Ev MANPATH
 371 The standard search path used by
 372 .Nm
 373 may be overridden by specifying a path in the
 374 .Ev MANPATH
 375 environment
 376 variable.
 377 The format of the path is a colon
 378 .Pq Ql \&:
 379 separated list of directories.
 380 The subdirectories to be searched, as well as their search order,
 381 are specified by the
 382 .Dq _subdir
 383 line in the
 384 .Nm
 385 configuration file.
 386 .It Ev PAGER
 387 Specifies the pagination program to use when
 388 .Ev MANPAGER
 389 is not defined.
 390 If neither PAGER nor MANPAGER is defined,
 391 .Xr more 1
 392 .Fl s
 393 will be used.
 394 .El
 395 .Sh FILES
 396 .Bl -tag -width /etc/man.conf -compact
 397 .It Pa /etc/man.conf
 398 default man configuration file
 399 .El
 400 .Sh EXIT STATUS
 401 .Ex -std man
 402 .Sh SEE ALSO
 403 .Xr apropos 1 ,
 404 .Xr intro 1 ,
 405 .Xr whatis 1 ,
 406 .Xr whereis 1 ,
 407 .Xr intro 2 ,
 408 .Xr intro 3 ,
 409 .Xr intro 4 ,
 410 .Xr intro 5 ,
 411 .Xr man.conf 5 ,
 412 .Xr intro 6 ,
 413 .Xr intro 7 ,
 414 .Xr mdoc 7 ,
 415 .Xr intro 8 ,
 416 .Xr intro 9
 417 .Sh STANDARDS
 418 The
 419 .Nm
 420 utility is compliant with the
 421 .St -p1003.1-2008
 422 specification.
 423 .Pp
 424 The flags
 425 .Op Fl aCcfhIKlMmOSsTWw ,
 426 as well as the environment variables
 427 .Ev MACHINE ,
 428 .Ev MANPAGER ,
 429 and
 430 .Ev MANPATH ,
 431 are extensions to that specification.
 432 .Sh HISTORY
 433 A
 434 .Nm
 435 command first appeared in
 436 .At v3 .
 437 .Pp
 438 The
 439 .Fl w
 440 option first appeared in
 441 .At v7 ;
 442 .Fl f
 443 and
 444 .Fl k
 445 in
 446 .Bx 4 ;
 447 .Fl M
 448 in
 449 .Bx 4.3 ;
 450 .Fl a
 451 in
 452 .Bx 4.3 Tahoe ;
 453 .Fl c
 454 and
 455 .Fl m
 456 in
 457 .Bx 4.3 Reno ;
 458 .Fl h
 459 in
 460 .Bx 4.3 Net/2 ;
 461 .Fl C
 462 in
 463 .Nx 1.0 ;
 464 and
 465 .Fl s
 466 and
 467 .Fl S
 468 in
 469 .Ox 2.3 .