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