man.1

   1 .\"     $Id: man.1,v 1.40 2020/07/20 16:57:30 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: July 20 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 less 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 .Tg s
 171 .It Oo Fl s Oc Ar section
 172 Only select manuals from the specified
 173 .Ar section .
 174 The currently available sections are:
 175 .Pp
 176 .Bl -tag -width "localXXX" -offset indent -compact
 177 .It 1
 178 General commands
 179 .Pq tools and utilities .
 180 .It 2
 181 System calls and error numbers.
 182 .It 3
 183 Library functions.
 184 .It 3p
 185 .Xr perl 1
 186 programmer's reference guide.
 187 .It 4
 188 Device drivers.
 189 .It 5
 190 File formats.
 191 .It 6
 192 Games.
 193 .It 7
 194 Miscellaneous information.
 195 .It 8
 196 System maintenance and operation commands.
 197 .It 9
 198 Kernel internals.
 199 .El
 200 .It Fl w
 201 List the pathnames of all matching manual pages instead of displaying
 202 any of them.
 203 If no
 204 .Ar name
 205 is given, list the directories that would be searched.
 206 .El
 207 .Pp
 208 The options
 209 .Fl IKOTW
 210 are also supported and are documented in
 211 .Xr mandoc 1 .
 212 The options
 213 .Fl fkl
 214 are mutually exclusive and override each other.
 215 .Pp
 216 The search starts with the
 217 .Fl m
 218 argument if provided, then continues with the
 219 .Fl M
 220 argument, the
 221 .Ev MANPATH
 222 variable, the
 223 .Ic manpath
 224 entries in the
 225 .Xr man.conf 5
 226 file, or with
 227 .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
 228 by default.
 229 Within each of these, directories are searched in the order provided.
 230 Within each directory, the search proceeds according to the following
 231 list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
 232 The first match found is shown.
 233 .Pp
 234 The
 235 .Xr mandoc.db 5
 236 database is used for looking up manual page entries.
 237 In cases where the database is absent, outdated, or corrupt,
 238 .Nm
 239 falls back to looking for files called
 240 .Ar name . Ns Ar section .
 241 If both a formatted and an unformatted version of the same manual page,
 242 for example
 243 .Pa cat1/foo.0
 244 and
 245 .Pa man1/foo.1 ,
 246 exist in the same directory, only the unformatted version is used.
 247 The database is kept up to date with
 248 .Xr makewhatis 8 ,
 249 which is run by the
 250 .Xr weekly 8
 251 maintenance script.
 252 .Pp
 253 Guidelines for writing
 254 man pages can be found in
 255 .Xr mdoc 7 .
 256 .Sh ENVIRONMENT
 257 .Bl -tag -width MANPATHX
 258 .It Ev MACHINE
 259 As some manual pages are intended only for specific architectures,
 260 .Nm
 261 searches any subdirectories,
 262 with the same name as the current architecture,
 263 in every directory which it searches.
 264 Machine specific areas are checked before general areas.
 265 The current machine type may be overridden by setting the environment
 266 variable
 267 .Ev MACHINE
 268 to the name of a specific architecture,
 269 or with the
 270 .Fl S
 271 option.
 272 .Ev MACHINE
 273 is case insensitive.
 274 .It Ev MANPAGER
 275 Any non-empty value of the environment variable
 276 .Ev MANPAGER
 277 is used instead of the standard pagination program,
 278 .Xr less 1 .
 279 If
 280 .Xr less 1
 281 is used, the interactive
 282 .Ic :t
 283 command can be used to go to the definitions of various terms, for
 284 example command line options, command modifiers, internal commands,
 285 environment variables, function names, preprocessor macros,
 286 .Xr errno 2
 287 values, and some other emphasized words.
 288 Some terms may have defining text at more than one place.
 289 In that case, the
 290 .Xr less 1
 291 interactive commands
 292 .Ic t
 293 and
 294 .Ic T
 295 can be used to move to the next and to the previous place providing
 296 information about the term last searched for with
 297 .Ic :t .
 298 The
 299 .Fl O Cm tag Ns Op = Ns Ar term
 300 option documented in the
 301 .Xr mandoc 1
 302 manual opens a manual page at the definition of a specific
 303 .Ar term
 304 rather than at the beginning.
 305 .It Ev MANPATH
 306 Override the standard search path which is either specified in
 307 .Xr man.conf 5
 308 or the default path.
 309 The format of
 310 .Ev MANPATH
 311 is a colon
 312 .Pq Ql \&:
 313 separated list of directories.
 314 Invalid directories are ignored.
 315 Overridden by
 316 .Fl M ,
 317 ignored if
 318 .Fl l
 319 is specified.
 320 .Pp
 321 If
 322 .Ev MANPATH
 323 begins with a colon, it is appended to the standard path;
 324 if it ends with a colon, it is prepended to the standard path;
 325 or if it contains two adjacent colons,
 326 the standard path is inserted between the colons.
 327 .It Ev PAGER
 328 Specifies the pagination program to use when
 329 .Ev MANPAGER
 330 is not defined.
 331 If neither PAGER nor MANPAGER is defined,
 332 .Xr less 1
 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 .