bin/mandoc/man.1

   1 .\"     $Id: man.1,v 1.35 2019/03/09 15:55:01 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: March 9 2019 $
  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 pages 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 Normally, only the first page found is displayed.
  68 .It Fl C Ar file
  69 Use the specified
  70 .Ar file
  71 instead of the default configuration file.
  72 This permits users to configure their own manual environment.
  73 See
  74 .Xr man.conf 5
  75 for a description of the contents of this file.
  76 .It Fl c
  77 Copy the manual page to the standard output instead of using
  78 .Xr more 1
  79 to paginate it.
  80 This is done by default if the standard output is not a terminal device.
  81 .Pp
  82 When using
  83 .Fl c ,
  84 most terminal devices are unable to show the markup.
  85 To print the output of
  86 .Nm
  87 to the terminal with markup but without using a pager, pipe it to
  88 .Xr ul 1 .
  89 To remove the markup, pipe the output to
  90 .Xr col 1
  91 .Fl b
  92 instead.
  93 .It Fl f
  94 A synonym for
  95 .Xr whatis 1 .
  96 It searches for
  97 .Ar name
  98 in manual page names and displays the header lines from all matching pages.
  99 The search is case insensitive and matches whole words only.
 100 .It Fl h
 101 Display only the SYNOPSIS lines of the requested manual pages.
 102 Implies
 103 .Fl a
 104 and
 105 .Fl c .
 106 .It Fl k
 107 A synonym for
 108 .Xr apropos 1 .
 109 Instead of
 110 .Ar name ,
 111 an expression can be provided using the syntax described in the
 112 .Xr apropos 1
 113 manual.
 114 By default, it displays the header lines of all matching pages.
 115 .It Fl l
 116 A synonym for
 117 .Xr mandoc 1 .
 118 The
 119 .Ar name
 120 arguments are interpreted as filenames.
 121 No search is done and
 122 .Ar file ,
 123 .Ar path ,
 124 .Ar section ,
 125 .Ar subsection ,
 126 and
 127 .Fl w
 128 are ignored.
 129 This option implies
 130 .Fl a .
 131 .It Fl M Ar path
 132 Override the list of standard directories which
 133 .Nm
 134 searches for manual pages.
 135 The supplied
 136 .Ar path
 137 must be a colon
 138 .Pq Ql \&:
 139 separated list of directories.
 140 This search path may also be set using the environment variable
 141 .Ev MANPATH .
 142 .It Fl m Ar path
 143 Augment the list of standard directories which
 144 .Nm
 145 searches for manual pages.
 146 The supplied
 147 .Ar path
 148 must be a colon
 149 .Pq Ql \&:
 150 separated list of directories.
 151 These directories will be searched before the standard directories or
 152 the directories specified using the
 153 .Fl M
 154 option or the
 155 .Ev MANPATH
 156 environment variable.
 157 .It Fl S Ar subsection
 158 Only show pages for the specified
 159 .Xr machine 1
 160 architecture.
 161 .Ar subsection
 162 is case insensitive.
 163 .Pp
 164 By default manual pages for all architectures are installed.
 165 Therefore this option can be used to view pages for one
 166 architecture whilst using another.
 167 .Pp
 168 This option overrides the
 169 .Ev MACHINE
 170 environment variable.
 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 .Pp
 201 If not specified and a match is found in more than one section,
 202 the first match is selected from the following list:
 203 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
 204 .It Fl w
 205 List the pathnames of all matching manual pages instead of displaying
 206 any of them.
 207 .El
 208 .Pp
 209 The options
 210 .Fl IKOTW
 211 are also supported and are documented in
 212 .Xr mandoc 1 .
 213 The options
 214 .Fl fkl
 215 are mutually exclusive and override each other.
 216 .Pp
 217 Guidelines for writing
 218 man pages can be found in
 219 .Xr mdoc 7 .
 220 .Pp
 221 The
 222 .Xr mandoc.db 5
 223 database is used for looking up manual page entries.
 224 In cases where the database is absent, outdated, or corrupt,
 225 .Nm
 226 falls back to looking for files called
 227 .Ar name . Ns Ar section .
 228 If both a formatted and an unformatted version of the same manual page,
 229 for example
 230 .Pa cat1/foo.0
 231 and
 232 .Pa man1/foo.1 ,
 233 exist in the same directory, only the unformatted version is used.
 234 The database is kept up to date with
 235 .Xr makewhatis 8 ,
 236 which is run by the
 237 .Xr weekly 8
 238 maintenance script.
 239 .Sh ENVIRONMENT
 240 .Bl -tag -width MANPATHX
 241 .It Ev MACHINE
 242 As some manual pages are intended only for specific architectures,
 243 .Nm
 244 searches any subdirectories,
 245 with the same name as the current architecture,
 246 in every directory which it searches.
 247 Machine specific areas are checked before general areas.
 248 The current machine type may be overridden by setting the environment
 249 variable
 250 .Ev MACHINE
 251 to the name of a specific architecture,
 252 or with the
 253 .Fl S
 254 option.
 255 .Ev MACHINE
 256 is case insensitive.
 257 .It Ev MANPAGER
 258 Any non-empty value of the environment variable
 259 .Ev MANPAGER
 260 is used instead of the standard pagination program,
 261 .Xr more 1 .
 262 If
 263 .Xr less 1
 264 is used, the interactive
 265 .Ic :t
 266 command can be used to go to the definitions of various terms, for
 267 example command line options, command modifiers, internal commands,
 268 environment variables, function names, preprocessor macros,
 269 .Xr errno 2
 270 values, and some other emphasized words.
 271 Some terms may have defining text at more than one place.
 272 In that case, the
 273 .Xr less 1
 274 interactive commands
 275 .Ic t
 276 and
 277 .Ic T
 278 can be used to move to the next and to the previous place providing
 279 information about the term last searched for with
 280 .Ic :t .
 281 The
 282 .Fl O Cm tag Ns Op = Ns Ar term
 283 option documented in the
 284 .Xr mandoc 1
 285 manual opens a manual page at the definition of a specific
 286 .Ar term
 287 rather than at the beginning.
 288 .It Ev MANPATH
 289 The standard search path used by
 290 .Nm
 291 may be changed by specifying a path in the
 292 .Ev MANPATH
 293 environment variable.
 294 The format of the path is a colon
 295 .Pq Ql \&:
 296 separated list of directories.
 297 Invalid paths are ignored.
 298 Overridden by
 299 .Fl M ,
 300 ignored if
 301 .Fl l
 302 is specified.
 303 .Pp
 304 If
 305 .Ev MANPATH
 306 begins with a colon, it is appended to the default list;
 307 if it ends with a colon, it is prepended to the default list;
 308 or if it contains two adjacent colons,
 309 the standard search path is inserted between the colons.
 310 If none of these conditions are met, it overrides the
 311 standard search path.
 312 .It Ev PAGER
 313 Specifies the pagination program to use when
 314 .Ev MANPAGER
 315 is not defined.
 316 If neither PAGER nor MANPAGER is defined,
 317 .Xr more 1
 318 .Fl s
 319 is used.
 320 .El
 321 .Sh FILES
 322 .Bl -tag -width /etc/man.conf -compact
 323 .It Pa /etc/man.conf
 324 default man configuration file
 325 .El
 326 .Sh EXIT STATUS
 327 .Ex -std man
 328 See
 329 .Xr mandoc 1
 330 for details.
 331 .Sh EXAMPLES
 332 Format a page for pasting extracts into an email message \(em
 333 avoid printing any UTF-8 characters, reduce the width to ease
 334 quoting in replies, and remove markup:
 335 .Pp
 336 .Dl $ man -T ascii -O width=65 pledge | col -b
 337 .Pp
 338 Read a typeset page in a PDF viewer:
 339 .Pp
 340 .Dl $ MANPAGER=mupdf man -T pdf lpd
 341 .Sh SEE ALSO
 342 .Xr apropos 1 ,
 343 .Xr col 1 ,
 344 .Xr mandoc 1 ,
 345 .Xr ul 1 ,
 346 .Xr whereis 1 ,
 347 .Xr man.conf 5 ,
 348 .Xr mdoc 7
 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 aCcfhIKlMmOSsTWw ,
 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 .Fl s
 397 and
 398 .Fl S
 399 in
 400 .Ox 2.3 ;
 401 and
 402 .Fl I ,
 403 .Fl K ,
 404 .Fl l ,
 405 .Fl O ,
 406 and
 407 .Fl W
 408 in
 409 .Ox 5.7 .
 410 The
 411 .Fl T
 412 option first appeared in
 413 .At III
 414 and was also added in
 415 .Ox 5.7 .