man.1

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