contrib/mdocml/man.1

   1 .\"     $Id: man.1,v 1.21 2017/01/31 19:44:04 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, 2015 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 31 2017 $
  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 I Cm os Ns = Ns Ar name
  45 .Op Fl K Ar encoding
  46 .Op Fl M Ar path
  47 .Op Fl m Ar path
  48 .Op Fl O Ar option Ns = Ns Ar value
  49 .Op Fl S Ar subsection
  50 .Op Fl s Ar section
  51 .Op Fl T Ar output
  52 .Op Fl W Ar level
  53 .Op Ar section
  54 .Ar name ...
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility
  59 displays the
  60 manual pages entitled
  61 .Ar name .
  62 Pages may be selected according to
  63 a specific category
  64 .Pq Ar section
  65 or
  66 machine architecture
  67 .Pq Ar subsection .
  68 .Pp
  69 The options are as follows:
  70 .Bl -tag -width Ds
  71 .It Fl a
  72 Display all matching manual pages.
  73 Normally, only the first page found is displayed.
  74 .It Fl C Ar file
  75 Use the specified
  76 .Ar file
  77 instead of the default configuration file.
  78 This permits users to configure their own manual environment.
  79 See
  80 .Xr man.conf 5
  81 for a description of the contents of this file.
  82 .It Fl c
  83 Copy the manual page to the standard output instead of using
  84 .Xr more 1
  85 to paginate it.
  86 This is done by default if the standard output is not a terminal device.
  87 .It Fl f
  88 A synonym for
  89 .Xr whatis 1 .
  90 It searches for
  91 .Ar name
  92 in manual page names and displays the header lines from all matching pages.
  93 The search is case insensitive and matches whole words only.
  94 This overrides any earlier
  95 .Fl k
  96 and
  97 .Fl l
  98 options.
  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 I Cm os Ns = Ns Ar name
 106 Override the default operating system
 107 .Ar name
 108 for the
 109 .Xr mdoc 7
 110 .Ic \&Os
 111 and for the
 112 .Xr man 7
 113 .Ic \&TH
 114 macro.
 115 .It Fl K Ar encoding
 116 Specify the input encoding.
 117 The supported
 118 .Ar encoding
 119 arguments are
 120 .Cm us-ascii ,
 121 .Cm iso-8859-1 ,
 122 and
 123 .Cm utf-8 .
 124 By default, the encoding is automatically detected as described in the
 125 .Xr mandoc 1
 126 manual.
 127 .It Fl k
 128 A synonym for
 129 .Xr apropos 1 .
 130 Instead of
 131 .Ar name ,
 132 an expression can be provided using the syntax described in the
 133 .Xr apropos 1
 134 manual.
 135 By default, it displays the header lines of all matching pages.
 136 This overrides any earlier
 137 .Fl f
 138 and
 139 .Fl l
 140 options.
 141 .It Fl l
 142 A synonym for
 143 .Xr mandoc 1
 144 .Fl a .
 145 The
 146 .Ar name
 147 arguments are interpreted as filenames.
 148 No search is done and
 149 .Ar file ,
 150 .Ar path ,
 151 .Ar section ,
 152 and
 153 .Ar subsection
 154 are ignored.
 155 This overrides any earlier
 156 .Fl f ,
 157 .Fl k ,
 158 and
 159 .Fl w
 160 options.
 161 .It Fl M Ar path
 162 Override the list of standard directories which
 163 .Nm
 164 searches for manual pages.
 165 The supplied
 166 .Ar path
 167 must be a colon
 168 .Pq Ql \&:
 169 separated list of directories.
 170 This search path may also be set using the environment variable
 171 .Ev MANPATH .
 172 .It Fl m Ar path
 173 Augment the list of standard directories which
 174 .Nm
 175 searches for manual pages.
 176 The supplied
 177 .Ar path
 178 must be a colon
 179 .Pq Ql \&:
 180 separated list of directories.
 181 These directories will be searched before the standard directories or
 182 the directories specified using the
 183 .Fl M
 184 option or the
 185 .Ev MANPATH
 186 environment variable.
 187 .It Fl O Ar option Ns = Ns Ar value
 188 Comma-separated output options.
 189 For each output format, the available options are described in the
 190 .Xr mandoc 1
 191 manual.
 192 .It Fl S Ar subsection
 193 Restricts the directories that
 194 .Nm
 195 will search to those of a specific
 196 .Xr machine 1
 197 architecture.
 198 .Ar subsection
 199 is case insensitive.
 200 .Pp
 201 By default manual pages for all architectures are installed.
 202 Therefore this option can be used to view pages for one
 203 architecture whilst using another.
 204 .Pp
 205 This option overrides the
 206 .Ev MACHINE
 207 environment variable.
 208 .It Oo Fl s Oc Ar section
 209 Only select manuals from the specified
 210 .Ar section .
 211 The currently available sections are:
 212 .Pp
 213 .Bl -tag -width "localXXX" -offset indent -compact
 214 .It 1
 215 General commands
 216 .Pq tools and utilities .
 217 .It 2
 218 System calls and error numbers.
 219 .It 3
 220 Library functions.
 221 .It 3p
 222 .Xr perl 1
 223 programmer's reference guide.
 224 .It 4
 225 Device drivers.
 226 .It 5
 227 File formats.
 228 .It 6
 229 Games.
 230 .It 7
 231 Miscellaneous information.
 232 .It 8
 233 System maintenance and operation commands.
 234 .It 9
 235 Kernel internals.
 236 .El
 237 .It Fl T Ar output
 238 Select the output format.
 239 The default is
 240 .Cm locale .
 241 The other output modes
 242 .Cm ascii ,
 243 .Cm html ,
 244 .Cm lint ,
 245 .Cm man ,
 246 .Cm pdf ,
 247 .Cm ps ,
 248 .Cm tree ,
 249 and
 250 .Cm utf8
 251 are described in the
 252 .Xr mandoc 1
 253 manual.
 254 .It Fl W Ar level
 255 Specify the minimum message
 256 .Ar level
 257 to be reported on the standard error output and to affect the exit status.
 258 The
 259 .Ar level
 260 can be
 261 .Cm warning ,
 262 .Cm error ,
 263 or
 264 .Cm unsupp ;
 265 .Cm all
 266 is an alias for
 267 .Cm warning .
 268 By default,
 269 .Nm
 270 is silent.
 271 See the
 272 .Xr mandoc 1
 273 manual for details.
 274 .It Fl w
 275 List the pathnames of the manual pages which
 276 .Nm
 277 would display for the specified
 278 .Ar section
 279 and
 280 .Ar name
 281 combination.
 282 .El
 283 .Pp
 284 Guidelines for writing
 285 man pages can be found in
 286 .Xr mdoc 7 .
 287 .Pp
 288 If both a formatted and an unformatted version of the same manual page,
 289 for example
 290 .Pa cat1/foo.0
 291 and
 292 .Pa man1/foo.1 ,
 293 exist in the same directory, and at least one of them is selected,
 294 only the newer one is used.
 295 However, if both the
 296 .Fl a
 297 and the
 298 .Fl w
 299 options are specified, both file names are printed.
 300 .Sh ENVIRONMENT
 301 .Bl -tag -width MANPATHX
 302 .It Ev MACHINE
 303 As some manual pages are intended only for specific architectures,
 304 .Nm
 305 searches any subdirectories,
 306 with the same name as the current architecture,
 307 in every directory which it searches.
 308 Machine specific areas are checked before general areas.
 309 The current machine type may be overridden by setting the environment
 310 variable
 311 .Ev MACHINE
 312 to the name of a specific architecture,
 313 or with the
 314 .Fl S
 315 option.
 316 .Ev MACHINE
 317 is case insensitive.
 318 .It Ev MANPAGER
 319 Any non-empty value of the environment variable
 320 .Ev MANPAGER
 321 will be used instead of the standard pagination program,
 322 .Xr more 1 .
 323 If
 324 .Xr less 1
 325 is used, the interactive
 326 .Ic :t
 327 command can be used to go to the definitions of various terms, for
 328 example command line options, command modifiers, internal commands,
 329 environment variables, function names, preprocessor macros,
 330 .Xr errno 2
 331 values, and some other emphasized words.
 332 Some terms may have defining text at more than one place.
 333 In that case, the
 334 .Xr less 1
 335 interactive commands
 336 .Ic t
 337 and
 338 .Ic T
 339 can be used to move to the next and to the previous place providing
 340 information about the term last searched for with
 341 .Ic :t .
 342 .It Ev MANPATH
 343 The standard search path used by
 344 .Nm
 345 may be overridden by specifying a path in the
 346 .Ev MANPATH
 347 environment
 348 variable.
 349 The format of the path is a colon
 350 .Pq Ql \&:
 351 separated list of directories.
 352 .It Ev PAGER
 353 Specifies the pagination program to use when
 354 .Ev MANPAGER
 355 is not defined.
 356 If neither PAGER nor MANPAGER is defined,
 357 .Xr more 1
 358 .Fl s
 359 will be used.
 360 .El
 361 .Sh FILES
 362 .Bl -tag -width /etc/man.conf -compact
 363 .It Pa /etc/man.conf
 364 default man configuration file
 365 .El
 366 .Sh EXIT STATUS
 367 .Ex -std man
 368 .Sh SEE ALSO
 369 .Xr apropos 1 ,
 370 .Xr intro 1 ,
 371 .Xr whatis 1 ,
 372 .Xr whereis 1 ,
 373 .Xr intro 2 ,
 374 .Xr intro 3 ,
 375 .Xr intro 4 ,
 376 .Xr intro 5 ,
 377 .Xr man.conf 5 ,
 378 .Xr intro 6 ,
 379 .Xr intro 7 ,
 380 .Xr mdoc 7 ,
 381 .Xr intro 8 ,
 382 .Xr intro 9
 383 .Sh STANDARDS
 384 The
 385 .Nm
 386 utility is compliant with the
 387 .St -p1003.1-2008
 388 specification.
 389 .Pp
 390 The flags
 391 .Op Fl aCcfhIKlMmOSsTWw ,
 392 as well as the environment variables
 393 .Ev MACHINE ,
 394 .Ev MANPAGER ,
 395 and
 396 .Ev MANPATH ,
 397 are extensions to that specification.
 398 .Sh HISTORY
 399 A
 400 .Nm
 401 command first appeared in
 402 .At v3 .
 403 .Pp
 404 The
 405 .Fl w
 406 option first appeared in
 407 .At v7 ;
 408 .Fl f
 409 and
 410 .Fl k
 411 in
 412 .Bx 4 ;
 413 .Fl M
 414 in
 415 .Bx 4.3 ;
 416 .Fl a
 417 in
 418 .Bx 4.3 Tahoe ;
 419 .Fl c
 420 and
 421 .Fl m
 422 in
 423 .Bx 4.3 Reno ;
 424 .Fl h
 425 in
 426 .Bx 4.3 Net/2 ;
 427 .Fl C
 428 in
 429 .Nx 1.0 ;
 430 .Fl s
 431 and
 432 .Fl S
 433 in
 434 .Ox 2.3 ;
 435 and
 436 .Fl I ,
 437 .Fl K ,
 438 .Fl l ,
 439 .Fl O ,
 440 and
 441 .Fl W
 442 in
 443 .Ox 5.7 .
 444 The
 445 .Fl T
 446 option first appeared in
 447 .At III
 448 and was also added in
 449 .Ox 5.7 .