man.1

   1 .\"     $Id: man.1,v 1.38 2020/02/10 14:04:11 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-2020 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: February 10 2020 $
  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 M Ar path
  45 .Op Fl m Ar path
  46 .Op Fl S Ar subsection
  47 .Op Oo Fl s Oc Ar section
  48 .Ar name ...
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility
  53 displays the
  54 manual page entitled
  55 .Ar name .
  56 Pages may be selected according to
  57 a specific category
  58 .Pq Ar section
  59 or
  60 machine architecture
  61 .Pq Ar subsection .
  62 .Pp
  63 The options are as follows:
  64 .Bl -tag -width Ds
  65 .It Fl a
  66 Display all matching manual pages.
  67 .It Fl C Ar file
  68 Use the specified
  69 .Ar file
  70 instead of the default configuration file.
  71 This permits users to configure their own manual environment.
  72 See
  73 .Xr man.conf 5
  74 for a description of the contents of this file.
  75 .It Fl c
  76 Copy the manual page to the standard output instead of using
  77 .Xr more 1
  78 to paginate it.
  79 This is done by default if the standard output is not a terminal device.
  80 .Pp
  81 When using
  82 .Fl c ,
  83 most terminal devices are unable to show the markup.
  84 To print the output of
  85 .Nm
  86 to the terminal with markup but without using a pager, pipe it to
  87 .Xr ul 1 .
  88 To remove the markup, pipe the output to
  89 .Xr col 1
  90 .Fl b
  91 instead.
  92 .It Fl f
  93 A synonym for
  94 .Xr whatis 1 .
  95 It searches for
  96 .Ar name
  97 in manual page names and displays the header lines from all matching pages.
  98 The search is case insensitive and matches whole words only.
  99 .It Fl h
 100 Display only the SYNOPSIS lines of the requested manual pages.
 101 Implies
 102 .Fl a
 103 and
 104 .Fl c .
 105 .It Fl k
 106 A synonym for
 107 .Xr apropos 1 .
 108 Instead of
 109 .Ar name ,
 110 an expression can be provided using the syntax described in the
 111 .Xr apropos 1
 112 manual.
 113 By default, it displays the header lines of all matching pages.
 114 .It Fl l
 115 A synonym for
 116 .Xr mandoc 1 .
 117 The
 118 .Ar name
 119 arguments are interpreted as filenames.
 120 No search is done and
 121 .Ar file ,
 122 .Ar path ,
 123 .Ar section ,
 124 .Ar subsection ,
 125 and
 126 .Fl w
 127 are ignored.
 128 This option implies
 129 .Fl a .
 130 .It Fl M Ar path
 131 Override the list of directories to search for manual pages.
 132 The supplied
 133 .Ar path
 134 must be a colon
 135 .Pq Ql \&:
 136 separated list of directories.
 137 This option also overrides the environment variable
 138 .Ev MANPATH
 139 and any directories specified in the
 140 .Xr man.conf 5
 141 file.
 142 .It Fl m Ar path
 143 Augment the list of directories to search for manual pages.
 144 The supplied
 145 .Ar path
 146 must be a colon
 147 .Pq Ql \&:
 148 separated list of directories.
 149 These directories will be searched before those specified using the
 150 .Fl M
 151 option, the
 152 .Ev MANPATH
 153 environment variable, the
 154 .Xr man.conf 5
 155 file, or the default directories.
 156 .It Fl S Ar subsection
 157 Only show pages for the specified
 158 .Xr machine 1
 159 architecture.
 160 .Ar subsection
 161 is case insensitive.
 162 .Pp
 163 By default manual pages for all architectures are installed.
 164 Therefore this option can be used to view pages for one
 165 architecture whilst using another.
 166 .Pp
 167 This option overrides the
 168 .Ev MACHINE
 169 environment variable.
 170 .It Oo Fl s Oc Ar section
 171 Only select manuals from the specified
 172 .Ar section .
 173 The currently available sections are:
 174 .Pp
 175 .Bl -tag -width "localXXX" -offset indent -compact
 176 .It 1
 177 General commands
 178 .Pq tools and utilities .
 179 .It 2
 180 System calls and error numbers.
 181 .It 3
 182 Library functions.
 183 .It 3p
 184 .Xr perl 1
 185 programmer's reference guide.
 186 .It 4
 187 Device drivers.
 188 .It 5
 189 File formats.
 190 .It 6
 191 Games.
 192 .It 7
 193 Miscellaneous information.
 194 .It 8
 195 System maintenance and operation commands.
 196 .It 9
 197 Kernel internals.
 198 .El
 199 .It Fl w
 200 List the pathnames of all matching manual pages instead of displaying
 201 any of them.
 202 If no
 203 .Ar name
 204 is given, list the directories that would be searched.
 205 .El
 206 .Pp
 207 The options
 208 .Fl IKOTW
 209 are also supported and are documented in
 210 .Xr mandoc 1 .
 211 The options
 212 .Fl fkl
 213 are mutually exclusive and override each other.
 214 .Pp
 215 The search starts with the
 216 .Fl m
 217 argument if provided, then continues with the
 218 .Fl M
 219 argument, the
 220 .Ev MANPATH
 221 variable, the
 222 .Ic manpath
 223 entries in the
 224 .Xr man.conf 5
 225 file, or with
 226 .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
 227 by default.
 228 Within each of these, directories are searched in the order provided.
 229 Within each directory, the search proceeds according to the following
 230 list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
 231 The first match found is shown.
 232 .Pp
 233 The
 234 .Xr mandoc.db 5
 235 database is used for looking up manual page entries.
 236 In cases where the database is absent, outdated, or corrupt,
 237 .Nm
 238 falls back to looking for files called
 239 .Ar name . Ns Ar section .
 240 If both a formatted and an unformatted version of the same manual page,
 241 for example
 242 .Pa cat1/foo.0
 243 and
 244 .Pa man1/foo.1 ,
 245 exist in the same directory, only the unformatted version is used.
 246 The database is kept up to date with
 247 .Xr makewhatis 8 ,
 248 which is run by the
 249 .Xr weekly 8
 250 maintenance script.
 251 .Pp
 252 Guidelines for writing
 253 man pages can be found in
 254 .Xr mdoc 7 .
 255 .Sh ENVIRONMENT
 256 .Bl -tag -width MANPATHX
 257 .It Ev MACHINE
 258 As some manual pages are intended only for specific architectures,
 259 .Nm
 260 searches any subdirectories,
 261 with the same name as the current architecture,
 262 in every directory which it searches.
 263 Machine specific areas are checked before general areas.
 264 The current machine type may be overridden by setting the environment
 265 variable
 266 .Ev MACHINE
 267 to the name of a specific architecture,
 268 or with the
 269 .Fl S
 270 option.
 271 .Ev MACHINE
 272 is case insensitive.
 273 .It Ev MANPAGER
 274 Any non-empty value of the environment variable
 275 .Ev MANPAGER
 276 is used instead of the standard pagination program,
 277 .Xr more 1 .
 278 If
 279 .Xr less 1
 280 is used, the interactive
 281 .Ic :t
 282 command can be used to go to the definitions of various terms, for
 283 example command line options, command modifiers, internal commands,
 284 environment variables, function names, preprocessor macros,
 285 .Xr errno 2
 286 values, and some other emphasized words.
 287 Some terms may have defining text at more than one place.
 288 In that case, the
 289 .Xr less 1
 290 interactive commands
 291 .Ic t
 292 and
 293 .Ic T
 294 can be used to move to the next and to the previous place providing
 295 information about the term last searched for with
 296 .Ic :t .
 297 The
 298 .Fl O Cm tag Ns Op = Ns Ar term
 299 option documented in the
 300 .Xr mandoc 1
 301 manual opens a manual page at the definition of a specific
 302 .Ar term
 303 rather than at the beginning.
 304 .It Ev MANPATH
 305 Override the standard search path which is either specified in
 306 .Xr man.conf 5
 307 or the default path.
 308 The format of
 309 .Ev MANPATH
 310 is a colon
 311 .Pq Ql \&:
 312 separated list of directories.
 313 Invalid directories are ignored.
 314 Overridden by
 315 .Fl M ,
 316 ignored if
 317 .Fl l
 318 is specified.
 319 .Pp
 320 If
 321 .Ev MANPATH
 322 begins with a colon, it is appended to the standard path;
 323 if it ends with a colon, it is prepended to the standard path;
 324 or if it contains two adjacent colons,
 325 the standard path is inserted between the colons.
 326 .It Ev PAGER
 327 Specifies the pagination program to use when
 328 .Ev MANPAGER
 329 is not defined.
 330 If neither PAGER nor MANPAGER is defined,
 331 .Xr more 1
 332 .Fl s
 333 is used.
 334 .El
 335 .Sh FILES
 336 .Bl -tag -width /etc/man.conf -compact
 337 .It Pa /etc/man.conf
 338 default
 339 .Nm
 340 configuration file
 341 .El
 342 .Sh EXIT STATUS
 343 .Ex -std man
 344 See
 345 .Xr mandoc 1
 346 for details.
 347 .Sh EXAMPLES
 348 Format a page for pasting extracts into an email message \(em
 349 avoid printing any UTF-8 characters, reduce the width to ease
 350 quoting in replies, and remove markup:
 351 .Pp
 352 .Dl $ man -T ascii -O width=65 pledge | col -b
 353 .Pp
 354 Read a typeset page in a PDF viewer:
 355 .Pp
 356 .Dl $ MANPAGER=mupdf man -T pdf lpd
 357 .Sh SEE ALSO
 358 .Xr apropos 1 ,
 359 .Xr col 1 ,
 360 .Xr mandoc 1 ,
 361 .Xr ul 1 ,
 362 .Xr whereis 1 ,
 363 .Xr man.conf 5 ,
 364 .Xr mdoc 7
 365 .Sh STANDARDS
 366 The
 367 .Nm
 368 utility is compliant with the
 369 .St -p1003.1-2008
 370 specification.
 371 .Pp
 372 The flags
 373 .Op Fl aCcfhIKlMmOSsTWw ,
 374 as well as the environment variables
 375 .Ev MACHINE ,
 376 .Ev MANPAGER ,
 377 and
 378 .Ev MANPATH ,
 379 are extensions to that specification.
 380 .Sh HISTORY
 381 A
 382 .Nm
 383 command first appeared in
 384 .At v2 .
 385 .Pp
 386 The
 387 .Fl w
 388 option first appeared in
 389 .At v7 ;
 390 .Fl f
 391 and
 392 .Fl k
 393 in
 394 .Bx 4 ;
 395 .Fl M
 396 in
 397 .Bx 4.3 ;
 398 .Fl a
 399 in
 400 .Bx 4.3 Tahoe ;
 401 .Fl c
 402 and
 403 .Fl m
 404 in
 405 .Bx 4.3 Reno ;
 406 .Fl h
 407 in
 408 .Bx 4.3 Net/2 ;
 409 .Fl C
 410 in
 411 .Nx 1.0 ;
 412 .Fl s
 413 and
 414 .Fl S
 415 in
 416 .Ox 2.3 ;
 417 and
 418 .Fl I ,
 419 .Fl K ,
 420 .Fl l ,
 421 .Fl O ,
 422 and
 423 .Fl W
 424 in
 425 .Ox 5.7 .
 426 The
 427 .Fl T
 428 option first appeared in
 429 .At III
 430 and was also added in
 431 .Ox 5.7 .