man.1

   1 .\"     $Id: man.1,v 1.36 2020/01/07 11:16:33 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-2018 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: January 7 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 .El
 203 .Pp
 204 The options
 205 .Fl IKOTW
 206 are also supported and are documented in
 207 .Xr mandoc 1 .
 208 The options
 209 .Fl fkl
 210 are mutually exclusive and override each other.
 211 .Pp
 212 The search starts with the
 213 .Fl m
 214 argument if provided, then continues with the
 215 .Fl M
 216 argument, the
 217 .Ev MANPATH
 218 variable, the
 219 .Ic manpath
 220 entries in the
 221 .Xr man.conf 5
 222 file, or with
 223 .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
 224 by default.
 225 Within each of these, directories are searched in the order provided.
 226 Within each directory, the search proceeds according to the following
 227 list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
 228 The first match found is shown.
 229 .Pp
 230 The
 231 .Xr mandoc.db 5
 232 database is used for looking up manual page entries.
 233 In cases where the database is absent, outdated, or corrupt,
 234 .Nm
 235 falls back to looking for files called
 236 .Ar name . Ns Ar section .
 237 If both a formatted and an unformatted version of the same manual page,
 238 for example
 239 .Pa cat1/foo.0
 240 and
 241 .Pa man1/foo.1 ,
 242 exist in the same directory, only the unformatted version is used.
 243 The database is kept up to date with
 244 .Xr makewhatis 8 ,
 245 which is run by the
 246 .Xr weekly 8
 247 maintenance script.
 248 .Pp
 249 Guidelines for writing
 250 man pages can be found in
 251 .Xr mdoc 7 .
 252 .Sh ENVIRONMENT
 253 .Bl -tag -width MANPATHX
 254 .It Ev MACHINE
 255 As some manual pages are intended only for specific architectures,
 256 .Nm
 257 searches any subdirectories,
 258 with the same name as the current architecture,
 259 in every directory which it searches.
 260 Machine specific areas are checked before general areas.
 261 The current machine type may be overridden by setting the environment
 262 variable
 263 .Ev MACHINE
 264 to the name of a specific architecture,
 265 or with the
 266 .Fl S
 267 option.
 268 .Ev MACHINE
 269 is case insensitive.
 270 .It Ev MANPAGER
 271 Any non-empty value of the environment variable
 272 .Ev MANPAGER
 273 is used instead of the standard pagination program,
 274 .Xr more 1 .
 275 If
 276 .Xr less 1
 277 is used, the interactive
 278 .Ic :t
 279 command can be used to go to the definitions of various terms, for
 280 example command line options, command modifiers, internal commands,
 281 environment variables, function names, preprocessor macros,
 282 .Xr errno 2
 283 values, and some other emphasized words.
 284 Some terms may have defining text at more than one place.
 285 In that case, the
 286 .Xr less 1
 287 interactive commands
 288 .Ic t
 289 and
 290 .Ic T
 291 can be used to move to the next and to the previous place providing
 292 information about the term last searched for with
 293 .Ic :t .
 294 The
 295 .Fl O Cm tag Ns Op = Ns Ar term
 296 option documented in the
 297 .Xr mandoc 1
 298 manual opens a manual page at the definition of a specific
 299 .Ar term
 300 rather than at the beginning.
 301 .It Ev MANPATH
 302 Override the standard search path which is either specified in
 303 .Xr man.conf 5
 304 or the default path.
 305 The format of
 306 .Ev MANPATH
 307 is a colon
 308 .Pq Ql \&:
 309 separated list of directories.
 310 Invalid directories are ignored.
 311 Overridden by
 312 .Fl M ,
 313 ignored if
 314 .Fl l
 315 is specified.
 316 .Pp
 317 If
 318 .Ev MANPATH
 319 begins with a colon, it is appended to the standard path;
 320 if it ends with a colon, it is prepended to the standard path;
 321 or if it contains two adjacent colons,
 322 the standard path is inserted between the colons.
 323 .It Ev PAGER
 324 Specifies the pagination program to use when
 325 .Ev MANPAGER
 326 is not defined.
 327 If neither PAGER nor MANPAGER is defined,
 328 .Xr more 1
 329 .Fl s
 330 is used.
 331 .El
 332 .Sh FILES
 333 .Bl -tag -width /etc/man.conf -compact
 334 .It Pa /etc/man.conf
 335 default
 336 .Nm
 337 configuration file
 338 .El
 339 .Sh EXIT STATUS
 340 .Ex -std man
 341 See
 342 .Xr mandoc 1
 343 for details.
 344 .Sh EXAMPLES
 345 Format a page for pasting extracts into an email message \(em
 346 avoid printing any UTF-8 characters, reduce the width to ease
 347 quoting in replies, and remove markup:
 348 .Pp
 349 .Dl $ man -T ascii -O width=65 pledge | col -b
 350 .Pp
 351 Read a typeset page in a PDF viewer:
 352 .Pp
 353 .Dl $ MANPAGER=mupdf man -T pdf lpd
 354 .Sh SEE ALSO
 355 .Xr apropos 1 ,
 356 .Xr col 1 ,
 357 .Xr mandoc 1 ,
 358 .Xr ul 1 ,
 359 .Xr whereis 1 ,
 360 .Xr man.conf 5 ,
 361 .Xr mdoc 7
 362 .Sh STANDARDS
 363 The
 364 .Nm
 365 utility is compliant with the
 366 .St -p1003.1-2008
 367 specification.
 368 .Pp
 369 The flags
 370 .Op Fl aCcfhIKlMmOSsTWw ,
 371 as well as the environment variables
 372 .Ev MACHINE ,
 373 .Ev MANPAGER ,
 374 and
 375 .Ev MANPATH ,
 376 are extensions to that specification.
 377 .Sh HISTORY
 378 A
 379 .Nm
 380 command first appeared in
 381 .At v3 .
 382 .Pp
 383 The
 384 .Fl w
 385 option first appeared in
 386 .At v7 ;
 387 .Fl f
 388 and
 389 .Fl k
 390 in
 391 .Bx 4 ;
 392 .Fl M
 393 in
 394 .Bx 4.3 ;
 395 .Fl a
 396 in
 397 .Bx 4.3 Tahoe ;
 398 .Fl c
 399 and
 400 .Fl m
 401 in
 402 .Bx 4.3 Reno ;
 403 .Fl h
 404 in
 405 .Bx 4.3 Net/2 ;
 406 .Fl C
 407 in
 408 .Nx 1.0 ;
 409 .Fl s
 410 and
 411 .Fl S
 412 in
 413 .Ox 2.3 ;
 414 and
 415 .Fl I ,
 416 .Fl K ,
 417 .Fl l ,
 418 .Fl O ,
 419 and
 420 .Fl W
 421 in
 422 .Ox 5.7 .
 423 The
 424 .Fl T
 425 option first appeared in
 426 .At III
 427 and was also added in
 428 .Ox 5.7 .