man.1

   1 .\"     $Id: man.1,v 1.13 2015/02/16 16:23:54 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: February 16 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 .It Ev MANPATH
 364 The standard search path used by
 365 .Nm
 366 may be overridden by specifying a path in the
 367 .Ev MANPATH
 368 environment
 369 variable.
 370 The format of the path is a colon
 371 .Pq Ql \&:
 372 separated list of directories.
 373 The subdirectories to be searched, as well as their search order,
 374 are specified by the
 375 .Dq _subdir
 376 line in the
 377 .Nm
 378 configuration file.
 379 .It Ev PAGER
 380 Specifies the pagination program to use when
 381 .Ev MANPAGER
 382 is not defined.
 383 If neither PAGER nor MANPAGER is defined,
 384 .Pa /usr/bin/more Fl s
 385 will be used.
 386 .El
 387 .Sh FILES
 388 .Bl -tag -width /etc/man.conf -compact
 389 .It Pa /etc/man.conf
 390 default man configuration file
 391 .El
 392 .Sh EXIT STATUS
 393 .Ex -std man
 394 .Sh SEE ALSO
 395 .Xr apropos 1 ,
 396 .Xr intro 1 ,
 397 .Xr whatis 1 ,
 398 .Xr whereis 1 ,
 399 .Xr intro 2 ,
 400 .Xr intro 3 ,
 401 .Xr intro 4 ,
 402 .Xr intro 5 ,
 403 .Xr man.conf 5 ,
 404 .Xr intro 6 ,
 405 .Xr intro 7 ,
 406 .Xr mdoc 7 ,
 407 .Xr intro 8 ,
 408 .Xr intro 9
 409 .Sh STANDARDS
 410 The
 411 .Nm
 412 utility is compliant with the
 413 .St -p1003.1-2008
 414 specification.
 415 .Pp
 416 The flags
 417 .Op Fl aCcfhIKlMmOSsTWw ,
 418 as well as the environment variables
 419 .Ev MACHINE ,
 420 .Ev MANPAGER ,
 421 and
 422 .Ev MANPATH ,
 423 are extensions to that specification.
 424 .Sh HISTORY
 425 A
 426 .Nm
 427 command first appeared in
 428 .At v3 .
 429 .Pp
 430 The
 431 .Fl w
 432 option first appeared in
 433 .At v7 ;
 434 .Fl f
 435 and
 436 .Fl k
 437 in
 438 .Bx 4 ;
 439 .Fl M
 440 in
 441 .Bx 4.3 ;
 442 .Fl a
 443 in
 444 .Bx 4.3 Tahoe ;
 445 .Fl c
 446 and
 447 .Fl m
 448 in
 449 .Bx 4.3 Reno ;
 450 .Fl h
 451 in
 452 .Bx 4.3 Net/2 ;
 453 .Fl C
 454 in
 455 .Nx 1.0 ;
 456 and
 457 .Fl s
 458 and
 459 .Fl S
 460 in
 461 .Ox 2.3 .