man.1

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