man.1

   1 .\"     $Id: man.1,v 1.7 2014/11/11 02:43:41 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: November 11 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 M Ar path
  45 .Op Fl m Ar path
  46 .Op Fl S Ar subsection
  47 .Op Fl s Ar section
  48 .Op Ar section
  49 .Ar name ...
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility
  54 displays the
  55 manual pages entitled
  56 .Ar name .
  57 Pages may be selected according to
  58 a specific category
  59 .Pq Ar section
  60 or
  61 machine architecture
  62 .Pq Ar subsection .
  63 .Pp
  64 The options are as follows:
  65 .Bl -tag -width Ds
  66 .It Fl a
  67 Display all of the manual pages for a specified
  68 .Ar section
  69 and
  70 .Ar name
  71 combination.
  72 Normally, only the first manual page found is displayed.
  73 .It Fl C Ar file
  74 Use the specified
  75 .Ar file
  76 instead of the default configuration file.
  77 This permits users to configure their own manual environment.
  78 See
  79 .Xr man.conf 5
  80 for a description of the contents of this file.
  81 .It Fl c
  82 Copy the manual page to the standard output instead of using
  83 .Xr more 1
  84 to paginate it.
  85 This is done by default if the standard output is not a terminal device.
  86 .It Fl f
  87 A synonym for
  88 .Xr whatis 1 .
  89 It searches for
  90 .Ar name
  91 in manual page names and displays the header lines from all matching pages.
  92 The search is case insensitive and matches whole words only.
  93 This overrides any earlier
  94 .Fl k
  95 and
  96 .Fl l
  97 options.
  98 .It Fl h
  99 Display only the SYNOPSIS lines of the requested manual pages.
 100 Implies
 101 .Fl a
 102 and
 103 .Fl c .
 104 .It Fl k
 105 A synonym for
 106 .Xr apropos 1 .
 107 Instead of
 108 .Ar name ,
 109 an expression can be provided using the syntax described in the
 110 .Xr apropos 1
 111 manual.
 112 By default, it displays the header lines of all matching pages.
 113 This overrides any earlier
 114 .Fl f
 115 and
 116 .Fl l
 117 options.
 118 .It Fl l
 119 A synonym for
 120 .Xr mandoc 1
 121 .Fl a .
 122 The
 123 .Ar name
 124 arguments are interpreted as filenames.
 125 No search is done and
 126 .Ar file ,
 127 .Ar path ,
 128 .Ar section ,
 129 and
 130 .Ar subsection
 131 are ignored.
 132 This overrides any earlier
 133 .Fl f ,
 134 .Fl k ,
 135 and
 136 .Fl w
 137 options.
 138 .It Fl M Ar path
 139 Override the list of standard directories which
 140 .Nm
 141 searches for manual pages.
 142 The supplied
 143 .Ar path
 144 must be a colon
 145 .Pq Ql \&:
 146 separated list of directories.
 147 This search path may also be set using the environment variable
 148 .Ev MANPATH .
 149 The subdirectories to be searched, and their search order,
 150 are specified by the
 151 .Dq _subdir
 152 line in the
 153 .Nm
 154 configuration file.
 155 .It Fl m Ar path
 156 Augment the list of standard directories which
 157 .Nm
 158 searches for manual pages.
 159 The supplied
 160 .Ar path
 161 must be a colon
 162 .Pq Ql \&:
 163 separated list of directories.
 164 These directories will be searched before the standard directories or
 165 the directories specified using the
 166 .Fl M
 167 option or the
 168 .Ev MANPATH
 169 environment variable.
 170 The subdirectories to be searched, and their search order,
 171 are specified by the
 172 .Dq _subdir
 173 line in the
 174 .Nm
 175 configuration file.
 176 .It Fl S Ar subsection
 177 Restricts the directories that
 178 .Nm
 179 will search to those of a specific
 180 .Xr machine 1
 181 architecture.
 182 .Ar subsection
 183 is case insensitive.
 184 .Pp
 185 By default manual pages for all architectures are installed.
 186 Therefore this option can be used to view pages for one
 187 architecture whilst using another.
 188 .Pp
 189 This option overrides the
 190 .Ev MACHINE
 191 environment variable.
 192 .It Xo
 193 .Op Fl s
 194 .Ar section
 195 .Xc
 196 Restricts the directories that
 197 .Nm
 198 will search to a specific section.
 199 The currently available sections are:
 200 .Pp
 201 .Bl -tag -width "localXXX" -offset indent -compact
 202 .It 1
 203 General commands
 204 .Pq tools and utilities .
 205 .It 2
 206 System calls and error numbers.
 207 .It 3
 208 Libraries.
 209 .It 3f
 210 Fortran programmer's reference guide.
 211 .It 3p
 212 .Xr perl 1
 213 programmer's reference guide.
 214 .It 4
 215 Device drivers.
 216 .It 5
 217 File formats.
 218 .It 6
 219 Games.
 220 .It 7
 221 Miscellaneous.
 222 .It 8
 223 System maintenance and operation commands.
 224 .It 9
 225 Kernel internals.
 226 .It X11
 227 An alias for X11R6.
 228 .It X11R6
 229 X Window System.
 230 .It local
 231 Pages located in
 232 .Pa /usr/local .
 233 .It n
 234 Tcl/Tk commands.
 235 .El
 236 .Pp
 237 The
 238 .Nm
 239 configuration file,
 240 .Xr man.conf 5 ,
 241 specifies the possible
 242 .Ar section
 243 values, and their search order.
 244 Additional sections may be specified.
 245 .It Fl V
 246 Print version and exit.
 247 .It Fl w
 248 List the pathnames of the manual pages which
 249 .Nm
 250 would display for the specified
 251 .Ar section
 252 and
 253 .Ar name
 254 combination.
 255 .El
 256 .Pp
 257 The
 258 .Nm
 259 utility also supports the options
 260 .Fl IKOTW
 261 described in the
 262 .Xr mandoc 1
 263 manual.
 264 .Pp
 265 Guidelines for writing
 266 man pages can be found in
 267 .Xr mdoc 7 .
 268 .Pp
 269 If both a formatted and an unformatted version of the same manual page,
 270 for example
 271 .Pa cat1/foo.0
 272 and
 273 .Pa man1/foo.1 ,
 274 exist in the same directory, and at least one of them is selected,
 275 only the newer one is used.
 276 However, if both the
 277 .Fl a
 278 and the
 279 .Fl w
 280 options are specified, both file names are printed.
 281 .Sh ENVIRONMENT
 282 .Bl -tag -width MANPATHX
 283 .It Ev MACHINE
 284 As some manual pages are intended only for specific architectures,
 285 .Nm
 286 searches any subdirectories,
 287 with the same name as the current architecture,
 288 in every directory which it searches.
 289 Machine specific areas are checked before general areas.
 290 The current machine type may be overridden by setting the environment
 291 variable
 292 .Ev MACHINE
 293 to the name of a specific architecture,
 294 or with the
 295 .Fl S
 296 option.
 297 .Ev MACHINE
 298 is case insensitive.
 299 .It Ev MANPAGER
 300 Any non-empty value of the environment variable
 301 .Ev MANPAGER
 302 will be used instead of the standard pagination program,
 303 .Xr more 1 .
 304 .It Ev MANPATH
 305 The standard search path used by
 306 .Nm
 307 may be overridden by specifying a path in the
 308 .Ev MANPATH
 309 environment
 310 variable.
 311 The format of the path is a colon
 312 .Pq Ql \&:
 313 separated list of directories.
 314 The subdirectories to be searched, as well as their search order,
 315 are specified by the
 316 .Dq _subdir
 317 line in the
 318 .Nm
 319 configuration file.
 320 .It Ev PAGER
 321 Specifies the pagination program to use when
 322 .Ev MANPAGER
 323 is not defined.
 324 If neither PAGER nor MANPAGER is defined,
 325 .Pa /usr/bin/more Fl s
 326 will be used.
 327 .El
 328 .Sh FILES
 329 .Bl -tag -width /etc/man.conf -compact
 330 .It Pa /etc/man.conf
 331 default man configuration file
 332 .El
 333 .Sh EXIT STATUS
 334 .Ex -std man
 335 .Sh SEE ALSO
 336 .Xr apropos 1 ,
 337 .Xr intro 1 ,
 338 .Xr whatis 1 ,
 339 .Xr whereis 1 ,
 340 .Xr intro 2 ,
 341 .Xr intro 3 ,
 342 .Xr intro 4 ,
 343 .Xr intro 5 ,
 344 .Xr man.conf 5 ,
 345 .Xr intro 6 ,
 346 .Xr intro 7 ,
 347 .Xr mdoc 7 ,
 348 .Xr intro 8 ,
 349 .Xr intro 9
 350 .Sh STANDARDS
 351 The
 352 .Nm
 353 utility is compliant with the
 354 .St -p1003.1-2008
 355 specification.
 356 .Pp
 357 The flags
 358 .Op Fl aCcfhMmSsw ,
 359 as well as the environment variables
 360 .Ev MACHINE ,
 361 .Ev MANPAGER ,
 362 and
 363 .Ev MANPATH ,
 364 are extensions to that specification.
 365 .Sh HISTORY
 366 A
 367 .Nm
 368 command first appeared in
 369 .At v3 .
 370 .Pp
 371 The
 372 .Fl w
 373 option first appeared in
 374 .At v7 ;
 375 .Fl f
 376 and
 377 .Fl k
 378 in
 379 .Bx 4 ;
 380 .Fl M
 381 in
 382 .Bx 4.3 ;
 383 .Fl a
 384 in
 385 .Bx 4.3 Tahoe ;
 386 .Fl c
 387 and
 388 .Fl m
 389 in
 390 .Bx 4.3 Reno ;
 391 .Fl h
 392 in
 393 .Bx 4.3 Net/2 ;
 394 .Fl C
 395 in
 396 .Nx 1.0 ;
 397 and
 398 .Fl s
 399 and
 400 .Fl S
 401 in
 402 .Ox 2.3 .