contrib/mandoc/man.1

   1 .\"     $Id: man.1,v 1.33 2018/04/19 23:41:16 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-2017 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: April 19 2018 $
  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 If both a formatted and an unformatted version of the same manual page,
 222 for example
 223 .Pa cat1/foo.0
 224 and
 225 .Pa man1/foo.1 ,
 226 exist in the same directory, only the unformatted version is used.
 227 .Sh ENVIRONMENT
 228 .Bl -tag -width MANPATHX
 229 .It Ev MACHINE
 230 As some manual pages are intended only for specific architectures,
 231 .Nm
 232 searches any subdirectories,
 233 with the same name as the current architecture,
 234 in every directory which it searches.
 235 Machine specific areas are checked before general areas.
 236 The current machine type may be overridden by setting the environment
 237 variable
 238 .Ev MACHINE
 239 to the name of a specific architecture,
 240 or with the
 241 .Fl S
 242 option.
 243 .Ev MACHINE
 244 is case insensitive.
 245 .It Ev MANPAGER
 246 Any non-empty value of the environment variable
 247 .Ev MANPAGER
 248 is used instead of the standard pagination program,
 249 .Xr more 1 .
 250 If
 251 .Xr less 1
 252 is used, the interactive
 253 .Ic :t
 254 command can be used to go to the definitions of various terms, for
 255 example command line options, command modifiers, internal commands,
 256 environment variables, function names, preprocessor macros,
 257 .Xr errno 2
 258 values, and some other emphasized words.
 259 Some terms may have defining text at more than one place.
 260 In that case, the
 261 .Xr less 1
 262 interactive commands
 263 .Ic t
 264 and
 265 .Ic T
 266 can be used to move to the next and to the previous place providing
 267 information about the term last searched for with
 268 .Ic :t .
 269 .It Ev MANPATH
 270 The standard search path used by
 271 .Nm
 272 may be changed by specifying a path in the
 273 .Ev MANPATH
 274 environment variable.
 275 The format of the path is a colon
 276 .Pq Ql \&:
 277 separated list of directories.
 278 Invalid paths are ignored.
 279 Overridden by
 280 .Fl M ,
 281 ignored if
 282 .Fl l
 283 is specified.
 284 .Pp
 285 If
 286 .Ev MANPATH
 287 begins with a colon, it is appended to the default list;
 288 if it ends with a colon, it is prepended to the default list;
 289 or if it contains two adjacent colons,
 290 the standard search path is inserted between the colons.
 291 If none of these conditions are met, it overrides the
 292 standard search path.
 293 .It Ev PAGER
 294 Specifies the pagination program to use when
 295 .Ev MANPAGER
 296 is not defined.
 297 If neither PAGER nor MANPAGER is defined,
 298 .Xr more 1
 299 .Fl s
 300 is used.
 301 .El
 302 .Sh FILES
 303 .Bl -tag -width /etc/man.conf -compact
 304 .It Pa /etc/man.conf
 305 default man configuration file
 306 .El
 307 .Sh EXIT STATUS
 308 .Ex -std man
 309 See
 310 .Xr mandoc 1
 311 for details.
 312 .Sh EXAMPLES
 313 Format a page for pasting extracts into an email message \(em
 314 avoid printing any UTF-8 characters, reduce the width to ease
 315 quoting in replies, and remove markup:
 316 .Pp
 317 .Dl $ man -T ascii -O width=65 pledge | col -b
 318 .Pp
 319 Read a typeset page in a PDF viewer:
 320 .Pp
 321 .Dl $ MANPAGER=mupdf man -T pdf lpd
 322 .Sh SEE ALSO
 323 .Xr apropos 1 ,
 324 .Xr col 1 ,
 325 .Xr mandoc 1 ,
 326 .Xr ul 1 ,
 327 .Xr whereis 1 ,
 328 .Xr man.conf 5 ,
 329 .Xr mdoc 7
 330 .Sh STANDARDS
 331 The
 332 .Nm
 333 utility is compliant with the
 334 .St -p1003.1-2008
 335 specification.
 336 .Pp
 337 The flags
 338 .Op Fl aCcfhIKlMmOSsTWw ,
 339 as well as the environment variables
 340 .Ev MACHINE ,
 341 .Ev MANPAGER ,
 342 and
 343 .Ev MANPATH ,
 344 are extensions to that specification.
 345 .Sh HISTORY
 346 A
 347 .Nm
 348 command first appeared in
 349 .At v3 .
 350 .Pp
 351 The
 352 .Fl w
 353 option first appeared in
 354 .At v7 ;
 355 .Fl f
 356 and
 357 .Fl k
 358 in
 359 .Bx 4 ;
 360 .Fl M
 361 in
 362 .Bx 4.3 ;
 363 .Fl a
 364 in
 365 .Bx 4.3 Tahoe ;
 366 .Fl c
 367 and
 368 .Fl m
 369 in
 370 .Bx 4.3 Reno ;
 371 .Fl h
 372 in
 373 .Bx 4.3 Net/2 ;
 374 .Fl C
 375 in
 376 .Nx 1.0 ;
 377 .Fl s
 378 and
 379 .Fl S
 380 in
 381 .Ox 2.3 ;
 382 and
 383 .Fl I ,
 384 .Fl K ,
 385 .Fl l ,
 386 .Fl O ,
 387 and
 388 .Fl W
 389 in
 390 .Ox 5.7 .
 391 The
 392 .Fl T
 393 option first appeared in
 394 .At III
 395 and was also added in
 396 .Ox 5.7 .