man.1

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