whatis.1

   1 .\"     $Id: whatis.1,v 1.4 2011/12/12 02:00:49 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: December 12 2011 $
  18 .Dt WHATIS 1
  19 .Os
  20 .Sh NAME
  21 .Nm whatis
  22 .Nd search for manual pages by page names
  23 .Sh SYNOPSIS
  24 .Nm
  25 .Op Fl C Ar file
  26 .Op Fl M Ar manpath
  27 .Op Fl m Ar manpath
  28 .Op Fl S Ar arch
  29 .Op Fl s Ar section
  30 .Ar name ...
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 utility searches databases generated by
  35 .Xr mandocdb 8
  36 for manuals containing the word
  37 .Ar name
  38 in their page name, ignoring case.
  39 It returns the header lines from all matching pages.
  40 You can then use the
  41 .Xr man 1
  42 command to get more information.
  43 .Pp
  44 The options are as follows:
  45 .Bl -tag -width Ds
  46 .It Fl C Ar file
  47 Specify an alternative configuration
  48 .Ar file
  49 in
  50 .Xr man.conf 5
  51 format.
  52 .It Fl M Ar manpath
  53 Use the colon-separated
  54 .Ar manpath
  55 instead of the default list of paths searched for
  56 .Xr mandocdb 8
  57 databases.
  58 Invalid paths, or paths without manual databases, are ignored.
  59 .It Fl m Ar manpath
  60 Prepend the colon-separated
  61 .Ar manpath
  62 to the list of paths searched for
  63 .Xr mandocdb 8
  64 databases.
  65 Invalid paths, or paths without manual databases, are ignored.
  66 .It Fl S Ar arch
  67 Search only for a particular architecture.
  68 .It Fl s Ar cat
  69 Search only for a manual section.
  70 See
  71 .Xr man 1
  72 for a listing of manual sections.
  73 .El
  74 .Pp
  75 By default,
  76 .Nm
  77 searches for
  78 .Xr mandocdb 8
  79 databases in the default paths stipulated by
  80 .Xr man 1 .
  81 Results are sorted by manual title, with output formatted as
  82 .Pp
  83 .D1 title(sec) \- description
  84 .Pp
  85 Where
  86 .Qq title
  87 is the manual's title (note multiple manual names may exist for one
  88 title),
  89 .Qq sec
  90 is the manual section, and
  91 .Qq description
  92 is the manual's short description.
  93 If an architecture is specified for the manual, it is displayed as
  94 .Pp
  95 .D1 title(cat/arch) \- description
  96 .Pp
  97 Resulting manuals may be accessed as
  98 .Pp
  99 .Dl $ man \-s sec title
 100 .Pp
 101 If an architecture is specified in the output, use
 102 .Pp
 103 .Dl $ man \-s sec \-S arch title
 104 .Pp
 105 .Nm
 106 is identical to running
 107 .Xr apropos 1
 108 as follows:
 109 .Pp
 110 .Dl $ apropos -- -i 'Nm~[[:<:]]term[[:>:]]'
 111 .Sh ENVIRONMENT
 112 .Bl -tag -width Ds
 113 .It Ev MANPATH
 114 Colon-separated paths overriding the default list of paths searched for
 115 manual databases.
 116 Invalid paths, or paths without manual databases, are ignored.
 117 Overridden by
 118 .Fl M .
 119 .El
 120 .Sh FILES
 121 .Bl -tag -width "/etc/man.conf" -compact
 122 .It Pa mandoc.db
 123 name of the
 124 .Xr mandocdb 8
 125 keyword database
 126 .It Pa mandoc.index
 127 name of the
 128 .Xr mandocdb 8
 129 filename database
 130 .It Pa /etc/man.conf
 131 default
 132 .Xr man 1
 133 configuration file
 134 .El
 135 .Sh EXIT STATUS
 136 .Ex -std
 137 .Sh SEE ALSO
 138 .Xr apropos 1 ,
 139 .Xr man 1 ,
 140 .Xr man.conf 5 ,
 141 .Xr mandocdb 8
 142 .Sh HISTORY
 143 The
 144 .Nm
 145 utility first appeared in
 146 .Bx 2 .
 147 It was rewritten from scratch as part of the
 148 .Xr mandocdb 8
 149 project for
 150 .Ox 5.1 .
 151 .Sh AUTHORS
 152 .An -nosplit
 153 .An Bill Joy
 154 wrote the original
 155 .Bx
 156 .Nm
 157 in 1979.
 158 The current version was written by
 159 .An Kristaps Dzonsons ,
 160 .Mt kristaps@bsd.lv .