man.1

   1 .\"     $Id: man.1,v 1.12 2015/01/20 21:16:51 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: January 20 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 acfhklVw
  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 V
 295 Print version and exit.
 296 .It Fl W Ar level
 297 Specify the minimum message
 298 .Ar level
 299 to be reported on the standard error output and to affect the exit status.
 300 The
 301 .Ar level
 302 can be
 303 .Cm warning ,
 304 .Cm error ,
 305 or
 306 .Cm unsupp ;
 307 .Cm all
 308 is an alias for
 309 .Cm warning .
 310 By default,
 311 .Nm
 312 is silent.
 313 See the
 314 .Xr mandoc 1
 315 manual for details.
 316 .It Fl w
 317 List the pathnames of the manual pages which
 318 .Nm
 319 would display for the specified
 320 .Ar section
 321 and
 322 .Ar name
 323 combination.
 324 .El
 325 .Pp
 326 Guidelines for writing
 327 man pages can be found in
 328 .Xr mdoc 7 .
 329 .Pp
 330 If both a formatted and an unformatted version of the same manual page,
 331 for example
 332 .Pa cat1/foo.0
 333 and
 334 .Pa man1/foo.1 ,
 335 exist in the same directory, and at least one of them is selected,
 336 only the newer one is used.
 337 However, if both the
 338 .Fl a
 339 and the
 340 .Fl w
 341 options are specified, both file names are printed.
 342 .Sh ENVIRONMENT
 343 .Bl -tag -width MANPATHX
 344 .It Ev MACHINE
 345 As some manual pages are intended only for specific architectures,
 346 .Nm
 347 searches any subdirectories,
 348 with the same name as the current architecture,
 349 in every directory which it searches.
 350 Machine specific areas are checked before general areas.
 351 The current machine type may be overridden by setting the environment
 352 variable
 353 .Ev MACHINE
 354 to the name of a specific architecture,
 355 or with the
 356 .Fl S
 357 option.
 358 .Ev MACHINE
 359 is case insensitive.
 360 .It Ev MANPAGER
 361 Any non-empty value of the environment variable
 362 .Ev MANPAGER
 363 will be used instead of the standard pagination program,
 364 .Xr more 1 .
 365 .It Ev MANPATH
 366 The standard search path used by
 367 .Nm
 368 may be overridden by specifying a path in the
 369 .Ev MANPATH
 370 environment
 371 variable.
 372 The format of the path is a colon
 373 .Pq Ql \&:
 374 separated list of directories.
 375 The subdirectories to be searched, as well as their search order,
 376 are specified by the
 377 .Dq _subdir
 378 line in the
 379 .Nm
 380 configuration file.
 381 .It Ev PAGER
 382 Specifies the pagination program to use when
 383 .Ev MANPAGER
 384 is not defined.
 385 If neither PAGER nor MANPAGER is defined,
 386 .Pa /usr/bin/more Fl s
 387 will be used.
 388 .El
 389 .Sh FILES
 390 .Bl -tag -width /etc/man.conf -compact
 391 .It Pa /etc/man.conf
 392 default man configuration file
 393 .El
 394 .Sh EXIT STATUS
 395 .Ex -std man
 396 .Sh SEE ALSO
 397 .Xr apropos 1 ,
 398 .Xr intro 1 ,
 399 .Xr whatis 1 ,
 400 .Xr whereis 1 ,
 401 .Xr intro 2 ,
 402 .Xr intro 3 ,
 403 .Xr intro 4 ,
 404 .Xr intro 5 ,
 405 .Xr man.conf 5 ,
 406 .Xr intro 6 ,
 407 .Xr intro 7 ,
 408 .Xr mdoc 7 ,
 409 .Xr intro 8 ,
 410 .Xr intro 9
 411 .Sh STANDARDS
 412 The
 413 .Nm
 414 utility is compliant with the
 415 .St -p1003.1-2008
 416 specification.
 417 .Pp
 418 The flags
 419 .Op Fl aCcfhIKlMmOSsTVWw ,
 420 as well as the environment variables
 421 .Ev MACHINE ,
 422 .Ev MANPAGER ,
 423 and
 424 .Ev MANPATH ,
 425 are extensions to that specification.
 426 .Sh HISTORY
 427 A
 428 .Nm
 429 command first appeared in
 430 .At v3 .
 431 .Pp
 432 The
 433 .Fl w
 434 option first appeared in
 435 .At v7 ;
 436 .Fl f
 437 and
 438 .Fl k
 439 in
 440 .Bx 4 ;
 441 .Fl M
 442 in
 443 .Bx 4.3 ;
 444 .Fl a
 445 in
 446 .Bx 4.3 Tahoe ;
 447 .Fl c
 448 and
 449 .Fl m
 450 in
 451 .Bx 4.3 Reno ;
 452 .Fl h
 453 in
 454 .Bx 4.3 Net/2 ;
 455 .Fl C
 456 in
 457 .Nx 1.0 ;
 458 and
 459 .Fl s
 460 and
 461 .Fl S
 462 in
 463 .Ox 2.3 .