man.1

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