man.1

   1 .\"     $Id: man.1,v 1.4 2014/08/30 18:08:10 schwarze Exp $
   2 .\"     $OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc Exp $
   3 .\"
   4 .\" Copyright (c) 1989, 1990, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
   7 .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)man.1       8.2 (Berkeley) 1/2/94
  34 .\"
  35 .Dd $Mdocdate: August 30 2014 $
  36 .Dt MAN 1
  37 .Os
  38 .Sh NAME
  39 .Nm man
  40 .Nd display manual pages
  41 .Sh SYNOPSIS
  42 .Nm man
  43 .Op Fl acfhklVw
  44 .Op Fl C Ar file
  45 .Op Fl M Ar path
  46 .Op Fl m Ar path
  47 .Op Fl S Ar subsection
  48 .Op Fl s Ar section
  49 .Op Ar section
  50 .Ar name ...
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility
  55 displays the
  56 manual pages entitled
  57 .Ar name .
  58 Pages may be selected according to
  59 a specific category
  60 .Pq Ar section
  61 or
  62 machine architecture
  63 .Pq Ar subsection .
  64 .Pp
  65 The options are as follows:
  66 .Bl -tag -width Ds
  67 .It Fl a
  68 Display all of the manual pages for a specified
  69 .Ar section
  70 and
  71 .Ar name
  72 combination.
  73 Normally, only the first manual page found is displayed.
  74 .It Fl C Ar file
  75 Use the specified
  76 .Ar file
  77 instead of the default configuration file.
  78 This permits users to configure their own manual environment.
  79 See
  80 .Xr man.conf 5
  81 for a description of the contents of this file.
  82 .It Fl c
  83 Copy the manual page to the standard output instead of using
  84 .Xr more 1
  85 to paginate it.
  86 This is done by default if the standard output is not a terminal device.
  87 .It Fl f
  88 A synonym for
  89 .Xr whatis 1 .
  90 It searches for
  91 .Ar name
  92 in manual page names and displays the header lines from all matching pages.
  93 The search is case insensitive and matches whole words only.
  94 This overrides any earlier
  95 .Fl k
  96 and
  97 .Fl l
  98 options.
  99 .It Fl h
 100 Display only the
 101 .Dq SYNOPSIS
 102 lines of the requested manual pages.
 103 .It Fl k
 104 A synonym for
 105 .Xr apropos 1 .
 106 Instead of
 107 .Ar name ,
 108 an expression can be provided using the syntax described in the
 109 .Xr apropos 1
 110 manual.
 111 By default, it displays the header lines of all matching pages.
 112 This overrides any earlier
 113 .Fl f
 114 and
 115 .Fl l
 116 options.
 117 .It Fl l
 118 A synonym for
 119 .Xr mandoc 1
 120 .Fl a .
 121 The
 122 .Ar name
 123 arguments are interpreted as filenames.
 124 No search is done and
 125 .Ar file ,
 126 .Ar path ,
 127 .Ar section ,
 128 and
 129 .Ar subsection
 130 are ignored.
 131 This overrides any earlier
 132 .Fl f ,
 133 .Fl k ,
 134 and
 135 .Fl w
 136 options.
 137 .It Fl M Ar path
 138 Override the list of standard directories which
 139 .Nm
 140 searches for manual pages.
 141 The supplied
 142 .Ar path
 143 must be a colon
 144 .Pq Ql \&:
 145 separated list of directories.
 146 This search path may also be set using the environment variable
 147 .Ev MANPATH .
 148 The subdirectories to be searched, and their search order,
 149 are specified by the
 150 .Dq _subdir
 151 line in the
 152 .Nm
 153 configuration file.
 154 .It Fl m Ar path
 155 Augment the list of standard directories which
 156 .Nm
 157 searches for manual pages.
 158 The supplied
 159 .Ar path
 160 must be a colon
 161 .Pq Ql \&:
 162 separated list of directories.
 163 These directories will be searched before the standard directories or
 164 the directories specified using the
 165 .Fl M
 166 option or the
 167 .Ev MANPATH
 168 environment variable.
 169 The subdirectories to be searched, and their search order,
 170 are specified by the
 171 .Dq _subdir
 172 line in the
 173 .Nm
 174 configuration file.
 175 .It Fl S Ar subsection
 176 Restricts the directories that
 177 .Nm
 178 will search to those of a specific
 179 .Xr machine 1
 180 architecture.
 181 .Ar subsection
 182 is case insensitive.
 183 .Pp
 184 By default manual pages for all architectures are installed.
 185 Therefore this option can be used to view pages for one
 186 architecture whilst using another.
 187 .Pp
 188 This option overrides the
 189 .Ev MACHINE
 190 environment variable.
 191 .It Xo
 192 .Op Fl s
 193 .Ar section
 194 .Xc
 195 Restricts the directories that
 196 .Nm
 197 will search to a specific section.
 198 The currently available sections are:
 199 .Pp
 200 .Bl -tag -width "localXXX" -offset indent -compact
 201 .It 1
 202 General commands
 203 .Pq tools and utilities .
 204 .It 2
 205 System calls and error numbers.
 206 .It 3
 207 Libraries.
 208 .It 3f
 209 Fortran programmer's reference guide.
 210 .It 3p
 211 .Xr perl 1
 212 programmer's reference guide.
 213 .It 4
 214 Device drivers.
 215 .It 5
 216 File formats.
 217 .It 6
 218 Games.
 219 .It 7
 220 Miscellaneous.
 221 .It 8
 222 System maintenance and operation commands.
 223 .It 9
 224 Kernel internals.
 225 .It X11
 226 An alias for X11R6.
 227 .It X11R6
 228 X Window System.
 229 .It local
 230 Pages located in
 231 .Pa /usr/local .
 232 .It n
 233 Tcl/Tk commands.
 234 .El
 235 .Pp
 236 The
 237 .Nm
 238 configuration file,
 239 .Xr man.conf 5 ,
 240 specifies the possible
 241 .Ar section
 242 values, and their search order.
 243 Additional sections may be specified.
 244 .It Fl V
 245 Print version and exit.
 246 .It Fl w
 247 List the pathnames of the manual pages which
 248 .Nm
 249 would display for the specified
 250 .Ar section
 251 and
 252 .Ar name
 253 combination.
 254 .El
 255 .Pp
 256 The
 257 .Nm
 258 utility also supports the options
 259 .Fl IOTW
 260 described in the
 261 .Xr mandoc 1
 262 manual.
 263 .Pp
 264 Guidelines for writing
 265 man pages can be found in
 266 .Xr mdoc 7 .
 267 .Pp
 268 If both a formatted and an unformatted version of the same manual page,
 269 for example
 270 .Pa cat1/foo.0
 271 and
 272 .Pa man1/foo.1 ,
 273 exist in the same directory, and at least one of them is selected,
 274 only the newer one is used.
 275 However, if both the
 276 .Fl a
 277 and the
 278 .Fl w
 279 options are specified, both file names are printed.
 280 .Sh ENVIRONMENT
 281 .Bl -tag -width MANPATHX
 282 .It Ev MACHINE
 283 As some manual pages are intended only for specific architectures,
 284 .Nm
 285 searches any subdirectories,
 286 with the same name as the current architecture,
 287 in every directory which it searches.
 288 Machine specific areas are checked before general areas.
 289 The current machine type may be overridden by setting the environment
 290 variable
 291 .Ev MACHINE
 292 to the name of a specific architecture,
 293 or with the
 294 .Fl S
 295 option.
 296 .Ev MACHINE
 297 is case insensitive.
 298 .It Ev MANPAGER
 299 Any non-empty value of the environment variable
 300 .Ev MANPAGER
 301 will be used instead of the standard pagination program,
 302 .Xr more 1 .
 303 .It Ev MANPATH
 304 The standard search path used by
 305 .Nm
 306 may be overridden by specifying a path in the
 307 .Ev MANPATH
 308 environment
 309 variable.
 310 The format of the path is a colon
 311 .Pq Ql \&:
 312 separated list of directories.
 313 The subdirectories to be searched, as well as their search order,
 314 are specified by the
 315 .Dq _subdir
 316 line in the
 317 .Nm
 318 configuration file.
 319 .It Ev PAGER
 320 Specifies the pagination program to use when
 321 .Ev MANPAGER
 322 is not defined.
 323 If neither PAGER nor MANPAGER is defined,
 324 .Pa /usr/bin/more Fl s
 325 will be used.
 326 .El
 327 .Sh FILES
 328 .Bl -tag -width /etc/man.conf -compact
 329 .It Pa /etc/man.conf
 330 default man configuration file
 331 .El
 332 .Sh EXIT STATUS
 333 .Ex -std man
 334 .Sh SEE ALSO
 335 .Xr apropos 1 ,
 336 .Xr intro 1 ,
 337 .Xr whatis 1 ,
 338 .Xr whereis 1 ,
 339 .Xr intro 2 ,
 340 .Xr intro 3 ,
 341 .Xr intro 4 ,
 342 .Xr intro 5 ,
 343 .Xr man.conf 5 ,
 344 .Xr intro 6 ,
 345 .Xr intro 7 ,
 346 .Xr mdoc 7 ,
 347 .Xr intro 8 ,
 348 .Xr intro 9
 349 .Sh STANDARDS
 350 The
 351 .Nm
 352 utility is compliant with the
 353 .St -p1003.1-2008
 354 specification.
 355 .Pp
 356 The flags
 357 .Op Fl aCcfhMmSsw ,
 358 as well as the environment variables
 359 .Ev MACHINE ,
 360 .Ev MANPAGER ,
 361 and
 362 .Ev MANPATH ,
 363 are extensions to that specification.
 364 .Sh HISTORY
 365 A
 366 .Nm
 367 command first appeared in
 368 .At v3 .
 369 .Pp
 370 The
 371 .Fl w
 372 option first appeared in
 373 .At v7 ;
 374 .Fl f
 375 and
 376 .Fl k
 377 in
 378 .Bx 4 ;
 379 .Fl M
 380 in
 381 .Bx 4.3 ;
 382 .Fl a
 383 in
 384 .Bx 4.3 Tahoe ;
 385 .Fl c
 386 and
 387 .Fl m
 388 in
 389 .Bx 4.3 Reno ;
 390 .Fl h
 391 in
 392 .Bx 4.3 Net/2 ;
 393 .Fl C
 394 in
 395 .Nx 1.0 ;
 396 and
 397 .Fl s
 398 and
 399 .Fl S
 400 in
 401 .Ox 2.3 .