contrib/mdocml/man.1

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