contrib/mdocml/man.1

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