usr.bin/man/man.1

   1 .\"-
   2 .\"  Copyright (c) 2010 Gordon Tetlow
   3 .\"  All rights reserved.
   4 .\"
   5 .\"  Redistribution and use in source and binary forms, with or without
   6 .\"  modification, are permitted provided that the following conditions
   7 .\"  are met:
   8 .\"  1. Redistributions of source code must retain the above copyright
   9 .\"     notice, this list of conditions and the following disclaimer.
  10 .\"  2. Redistributions in binary form must reproduce the above copyright
  11 .\"     notice, this list of conditions and the following disclaimer in the
  12 .\"     documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\"  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\"  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\"  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\"  ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\"  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\"  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\"  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\"  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\"  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\"  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\"  SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 26, 2014
  29 .Dt MAN 1
  30 .Os
  31 .Sh NAME
  32 .Nm man
  33 .Nd display online manual documentation pages
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl adho
  37 .Op Fl t | w
  38 .Op Fl M Ar manpath
  39 .Op Fl P Ar pager
  40 .Op Fl S Ar mansect
  41 .Op Fl m Ar arch Ns Op : Ns Ar machine
  42 .Op Fl p Op Ar eprtv
  43 .Op Ar mansect
  44 .Ar page ...
  45 .Nm
  46 .Fl f
  47 .Ar keyword ...
  48 .Nm
  49 .Fl k
  50 .Ar keyword ...
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility finds and displays online manual documentation pages.
  55 If
  56 .Ar mansect
  57 is provided,
  58 .Nm
  59 restricts the search to the specific section of the manual.
  60 .Pp
  61 The sections of the manual are:
  62 .Bl -enum -offset indent -compact
  63 .It
  64 .Fx
  65 General Commands Manual
  66 .It
  67 .Fx
  68 System Calls Manual
  69 .It
  70 .Fx
  71 Library Functions Manual
  72 .It
  73 .Fx
  74 Kernel Interfaces Manual
  75 .It
  76 .Fx
  77 File Formats Manual
  78 .It
  79 .Fx
  80 Games Manual
  81 .It
  82 .Fx
  83 Miscellaneous Information Manual
  84 .It
  85 .Fx
  86 System Manager's Manual
  87 .It
  88 .Fx
  89 Kernel Developer's Manual
  90 .El
  91 .Pp
  92 Options that
  93 .Nm
  94 understands:
  95 .Bl -tag -width indent
  96 .It Fl M Ar manpath
  97 Forces a specific colon separated manual path instead of the default
  98 search path.
  99 See
 100 .Xr manpath 1 .
 101 Overrides the
 102 .Ev MANPATH
 103 environment variable.
 104 .It Fl P Ar pager
 105 Use specified pager.
 106 Defaults to
 107 .Dq Li "less -sR"
 108 if color support is enabled, or
 109 .Dq Li "more -s" .
 110 Overrides the
 111 .Ev MANPAGER
 112 environment variable, which in turn overrides the
 113 .Ev PAGER
 114 environment variable.
 115 .It Fl S Ar mansect
 116 Restricts manual sections searched to the specified colon delimited list.
 117 Defaults to
 118 .Dq Li 1:8:2:3:n:4:5:6:7:9:l .
 119 Overrides the
 120 .Ev MANSECT
 121 environment variable.
 122 .It Fl a
 123 Display all manual pages instead of just the first found for each
 124 .Ar page
 125 argument.
 126 .It Fl d
 127 Print extra debugging information.
 128 Repeat for increased verbosity.
 129 Does not display the manual page.
 130 .It Fl f
 131 Emulate
 132 .Xr whatis 1 .
 133 .It Fl h
 134 Display short help message and exit.
 135 .It Fl k
 136 Emulate
 137 .Xr apropos 1 .
 138 .It Fl m Ar arch Ns Op : Ns Ar machine
 139 Override the default architecture and machine settings allowing lookup of
 140 other platform specific manual pages.
 141 See
 142 .Sx IMPLEMENTATION NOTES
 143 for how this option changes the default behavior.
 144 Overrides the
 145 .Ev MACHINE_ARCH
 146 and
 147 .Ev MACHINE
 148 environment variables.
 149 .It Fl o
 150 Force use of non-localized manual pages.
 151 See
 152 .Sx IMPLEMENTATION NOTES
 153 for how locale specific searches work.
 154 Overrides the
 155 .Ev LC_ALL , LC_CTYPE ,
 156 and
 157 .Ev LANG
 158 environment variables.
 159 .It Fl p Op Cm eprtv
 160 Use the list of given preprocessors before running
 161 .Xr nroff 1
 162 or
 163 .Xr troff 1 .
 164 Valid preprocessors arguments:
 165 .Pp
 166 .Bl -tag -width indent -compact
 167 .It Cm e
 168 .Xr eqn 1
 169 .It Cm p
 170 .Xr pic 1
 171 .It Cm r
 172 .Xr refer 1
 173 .It Cm t
 174 .Xr tbl 1
 175 .It Cm v
 176 .Xr vgrind 1
 177 .El
 178 .Pp
 179 Overrides the
 180 .Ev MANROFFSEQ
 181 environment variable.
 182 .It Fl t
 183 Send manual page source through
 184 .Xr troff 1
 185 allowing transformation of the manual pages to other formats.
 186 .It Fl w
 187 Display the location of the manual page instead of the contents of
 188 the manual page.
 189 .El
 190 .Sh IMPLEMENTATION NOTES
 191 .Ss Locale Specific Searches
 192 The
 193 .Nm
 194 utility supports manual pages in different locales.
 195 The search behavior is dictated by the first of three
 196 environment variables with a nonempty string:
 197 .Ev LC_ALL , LC_CTYPE ,
 198 or
 199 .Ev LANG .
 200 If set,
 201 .Nm
 202 will search for locale specific manual pages using the following logic:
 203 .Pp
 204 .Bl -item -offset indent -compact
 205 .It
 206 .Va lang Ns _ Ns Va country Ns . Ns Va charset
 207 .It
 208 .Va lang Ns . Ns Va charset
 209 .It
 210 .Li en Ns . Ns Va charset
 211 .El
 212 .Pp
 213 For example, if
 214 .Ev LC_ALL
 215 is set to
 216 .Dq Li ja_JP.eucJP ,
 217 .Nm
 218 will search the following paths when considering section 1 manual pages in
 219 .Pa /usr/share/man :
 220 .Pp
 221 .Bl -item -offset indent -compact
 222 .It
 223 .Pa /usr/share/man/ja_JP.eucJP/man1
 224 .It
 225 .Pa /usr/share/man/ja.eucJP/man1
 226 .It
 227 .Pa /usr/share/man/en.eucJP/man1
 228 .It
 229 .Pa /usr/share/man/man1
 230 .El
 231 .Ss Platform Specific Searches
 232 The
 233 .Nm
 234 utility supports platform specific manual pages.
 235 The search behavior is dictated by the
 236 .Fl m
 237 option or the
 238 .Ev MACHINE_ARCH
 239 and
 240 .Ev MACHINE
 241 environment variables.
 242 For example, if
 243 .Ev MACHINE_ARCH
 244 is set to
 245 .Dq Li i386
 246 and
 247 .Ev MACHINE
 248 is set to
 249 .Dq Li pc98 ,
 250 .Nm
 251 will search the following paths when considering section 4 manual pages in
 252 .Pa /usr/share/man :
 253 .Pp
 254 .Bl -item -offset indent -compact
 255 .It
 256 .Pa /usr/share/man/man4/pc98
 257 .It
 258 .Pa /usr/share/man/man4/i386
 259 .It
 260 .Pa /usr/share/man/man4
 261 .El
 262 .Ss Displaying Specific Manual Files
 263 The
 264 .Nm
 265 utility also supports displaying a specific manual page if passed a path
 266 to the file as long as it contains a
 267 .Ql /
 268 character.
 269 .Sh ENVIRONMENT
 270 The following environment variables affect the execution of
 271 .Nm :
 272 .Bl -tag -width ".Ev MANROFFSEQ"
 273 .It Ev LC_ALL , LC_CTYPE , LANG
 274 Used to find locale specific manual pages.
 275 Valid values can be found by running the
 276 .Xr locale 1
 277 command.
 278 See
 279 .Sx IMPLEMENTATION NOTES
 280 for details.
 281 Influenced by the
 282 .Fl o
 283 option.
 284 .It Ev MACHINE_ARCH , MACHINE
 285 Used to find platform specific manual pages.
 286 If unset, the output of
 287 .Dq Li "sysctl hw.machine_arch"
 288 and
 289 .Dq Li "sysctl hw.machine"
 290 is used respectively.
 291 See
 292 .Sx IMPLEMENTATION NOTES
 293 for details.
 294 Corresponds to the
 295 .Fl m
 296 option.
 297 .It Ev MANPATH
 298 Used to find the location of the manual files.
 299 See
 300 .Xr manpath 1
 301 for additional information.
 302 Corresponds to the
 303 .Fl M
 304 option.
 305 .It Ev MANROFFSEQ
 306 Used to determine the preprocessors for the manual source before running
 307 .Xr nroff 1
 308 or
 309 .Xr troff 1 .
 310 If unset, defaults to
 311 .Xr tbl 1 .
 312 Corresponds to the
 313 .Fl p
 314 option.
 315 .It Ev MANSECT
 316 Restricts manual sections searched to the specified colon delimited list.
 317 Corresponds to the
 318 .Fl S
 319 option.
 320 .It Ev MANWIDTH
 321 If set to a numeric value, used as the width manpages should be displayed.
 322 Otherwise, if set to a special value
 323 .Dq Li tty ,
 324 and output is to a terminal,
 325 the pages may be displayed over the whole width of the screen.
 326 .It Ev MANCOLOR
 327 If set, enables color support.
 328 .It Ev MANPAGER
 329 Program used to display files.
 330 .Pp
 331 If unset, and color support is enabled,
 332 .Dq Li "less -sR"
 333 is used.
 334 .Pp
 335 If unset, and color support is disabled, then
 336 .Ev PAGER
 337 is used.
 338 If that has no value either,
 339 .Dq Li "more -s"
 340 is used.
 341 .El
 342 .Sh FILES
 343 .Bl -tag -width indent -compact
 344 .It Pa /etc/man.conf
 345 System configuration file.
 346 .It Pa /usr/local/etc/man.d/*.conf
 347 Local configuration files.
 348 .El
 349 .Sh SEE ALSO
 350 .Xr apropos 1 ,
 351 .Xr intro 1 ,
 352 .Xr intro 2 ,
 353 .Xr intro 3 ,
 354 .Xr intro 4 ,
 355 .Xr intro 5 ,
 356 .Xr intro 6 ,
 357 .Xr intro 7 ,
 358 .Xr intro 8 ,
 359 .Xr intro 9 ,
 360 .Xr locale 1 ,
 361 .Xr manpath 1 ,
 362 .Xr nroff 1 ,
 363 .Xr troff 1 ,
 364 .Xr whatis 1 ,
 365 .Xr man.conf 5