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 June 3, 2011
  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 Options that
  62 .Nm
  63 understands:
  64 .Bl -tag -width indent
  65 .It Fl M Ar manpath
  66 Forces a specific colon separated manual path instead of the default
  67 search path.
  68 See
  69 .Xr manpath 1 .
  70 Overrides the
  71 .Ev MANPATH
  72 environment variable.
  73 .It Fl P Ar pager
  74 Use specified pager.
  75 Defaults to
  76 .Dq Li "less -sR"
  77 if color support is enabled, or
  78 .Dq Li "more -s" .
  79 Overrides the
  80 .Ev MANPAGER
  81 environment variable, which in turn overrides the
  82 .Ev PAGER
  83 environment variable.
  84 .It Fl S Ar mansect
  85 Restricts manual sections searched to the specified colon delimited list.
  86 Defaults to
  87 .Dq Li 1:8:2:3:n:4:5:6:7:9:l .
  88 Overrides the
  89 .Ev MANSECT
  90 environment variable.
  91 .It Fl a
  92 Display all manual pages instead of just the first found for each
  93 .Ar page
  94 argument.
  95 .It Fl d
  96 Print extra debugging information.
  97 Repeat for increased verbosity.
  98 Does not display the manual page.
  99 .It Fl f
 100 Emulate
 101 .Xr whatis 1 .
 102 .It Fl h
 103 Display short help message and exit.
 104 .It Fl k
 105 Emulate
 106 .Xr apropos 1 .
 107 .It Fl m Ar arch Ns Op : Ns Ar machine
 108 Override the default architecture and machine settings allowing lookup of
 109 other platform specific manual pages.
 110 See
 111 .Sx IMPLEMENTATION NOTES
 112 for how this option changes the default behavior.
 113 Overrides the
 114 .Ev MACHINE_ARCH
 115 and
 116 .Ev MACHINE
 117 environment variables.
 118 .It Fl o
 119 Force use of non-localized manual pages.
 120 See
 121 .Sx IMPLEMENTATION NOTES
 122 for how locale specific searches work.
 123 Overrides the
 124 .Ev LC_ALL , LC_CTYPE ,
 125 and
 126 .Ev LANG
 127 environment variables.
 128 .It Fl p Op Cm eprtv
 129 Use the list of given preprocessors before running
 130 .Xr nroff 1
 131 or
 132 .Xr troff 1 .
 133 Valid preprocessors arguments:
 134 .Pp
 135 .Bl -tag -width indent -compact
 136 .It Cm e
 137 .Xr eqn 1
 138 .It Cm p
 139 .Xr pic 1
 140 .It Cm r
 141 .Xr refer 1
 142 .It Cm t
 143 .Xr tbl 1
 144 .It Cm v
 145 .Xr vgrind 1
 146 .El
 147 .Pp
 148 Overrides the
 149 .Ev MANROFFSEQ
 150 environment variable.
 151 .It Fl t
 152 Send manual page source through
 153 .Xr troff 1
 154 allowing transformation of the manual pages to other formats.
 155 .It Fl w
 156 Display the location of the manual page instead of the contents of
 157 the manual page.
 158 .El
 159 .Sh IMPLEMENTATION NOTES
 160 .Ss Locale Specific Searches
 161 The
 162 .Nm
 163 utility supports manual pages in different locales.
 164 The search behavior is dictated by the first of three
 165 environment variables with a nonempty string:
 166 .Ev LC_ALL , LC_CTYPE ,
 167 or
 168 .Ev LANG .
 169 If set,
 170 .Nm
 171 will search for locale specific manual pages using the following logic:
 172 .Pp
 173 .Bl -item -offset indent -compact
 174 .It
 175 .Va lang Ns _ Ns Va country Ns . Ns Va charset
 176 .It
 177 .Va lang Ns . Ns Va charset
 178 .It
 179 .Li en Ns . Ns Va charset
 180 .El
 181 .Pp
 182 For example, if
 183 .Ev LC_ALL
 184 is set to
 185 .Dq Li ja_JP.eucJP ,
 186 .Nm
 187 will search the following paths when considering section 1 manual pages in
 188 .Pa /usr/share/man :
 189 .Pp
 190 .Bl -item -offset indent -compact
 191 .It
 192 .Pa /usr/share/man/ja_JP.eucJP/man1
 193 .It
 194 .Pa /usr/share/man/ja.eucJP/man1
 195 .It
 196 .Pa /usr/share/man/en.eucJP/man1
 197 .It
 198 .Pa /usr/share/man/man1
 199 .El
 200 .Ss Platform Specific Searches
 201 The
 202 .Nm
 203 utility supports platform specific manual pages.
 204 The search behavior is dictated by the
 205 .Fl m
 206 option or the
 207 .Ev MACHINE_ARCH
 208 and
 209 .Ev MACHINE
 210 environment variables.
 211 For example, if
 212 .Ev MACHINE_ARCH
 213 is set to
 214 .Dq Li i386
 215 and
 216 .Ev MACHINE
 217 is set to
 218 .Dq Li pc98 ,
 219 .Nm
 220 will search the following paths when considering section 4 manual pages in
 221 .Pa /usr/share/man :
 222 .Pp
 223 .Bl -item -offset indent -compact
 224 .It
 225 .Pa /usr/share/man/man4/pc98
 226 .It
 227 .Pa /usr/share/man/man4/i386
 228 .It
 229 .Pa /usr/share/man/man4
 230 .El
 231 .Ss Displaying Specific Manual Files
 232 The
 233 .Nm
 234 utility also supports displaying a specific manual page if passed a path
 235 to the file as long as it contains a
 236 .Ql /
 237 character.
 238 .Sh ENVIRONMENT
 239 The following environment variables affect the execution of
 240 .Nm :
 241 .Bl -tag -width ".Ev MANROFFSEQ"
 242 .It Ev LC_ALL , LC_CTYPE , LANG
 243 Used to find locale specific manual pages.
 244 Valid values can be found by running the
 245 .Xr locale 1
 246 command.
 247 See
 248 .Sx IMPLEMENTATION NOTES
 249 for details.
 250 Influenced by the
 251 .Fl o
 252 option.
 253 .It Ev MACHINE_ARCH , MACHINE
 254 Used to find platform specific manual pages.
 255 If unset, the output of
 256 .Dq Li "sysctl hw.machine_arch"
 257 and
 258 .Dq Li "sysctl hw.machine"
 259 is used respectively.
 260 See
 261 .Sx IMPLEMENTATION NOTES
 262 for details.
 263 Corresponds to the
 264 .Fl m
 265 option.
 266 .It Ev MANPATH
 267 Used to find the location of the manual files.
 268 See
 269 .Xr manpath 1
 270 for additional information.
 271 Corresponds to the
 272 .Fl M
 273 option.
 274 .It Ev MANROFFSEQ
 275 Used to determine the preprocessors for the manual source before running
 276 .Xr nroff 1
 277 or
 278 .Xr troff 1 .
 279 If unset, defaults to
 280 .Xr tbl 1 .
 281 Corresponds to the
 282 .Fl p
 283 option.
 284 .It Ev MANSECT
 285 Restricts manual sections searched to the specified colon delimited list.
 286 Corresponds to the
 287 .Fl S
 288 option.
 289 .It Ev MANWIDTH
 290 If set to a numeric value, used as the width manpages should be displayed.
 291 Otherwise, if set to a special value
 292 .Dq Li tty ,
 293 and output is to a terminal,
 294 the pages may be displayed over the whole width of the screen.
 295 .It Ev MANCOLOR
 296 If set, enables color support.
 297 .It Ev MANPAGER
 298 Program used to display files.
 299 .Pp
 300 If unset, and color support is enabled,
 301 .Dq Li "less -sR"
 302 is used.
 303 .Pp
 304 If unset, and color support is disabled, then
 305 .Ev PAGER
 306 is used.
 307 If that has no value either,
 308 .Dq Li "more -s"
 309 is used.
 310 .El
 311 .Sh FILES
 312 .Bl -tag -width indent -compact
 313 .It Pa /etc/man.conf
 314 System configuration file.
 315 .It Pa /usr/local/etc/man.d/*.conf
 316 Local configuration files.
 317 .El
 318 .Sh SEE ALSO
 319 .Xr apropos 1 ,
 320 .Xr intro 1 ,
 321 .Xr locale 1 ,
 322 .Xr manpath 1 ,
 323 .Xr nroff 1 ,
 324 .Xr troff 1 ,
 325 .Xr whatis 1 ,
 326 .Xr man.conf 5