whatis.1

   1 .\"     $Id: whatis.1,v 1.5 2011/12/24 22:37:16 kristaps 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 24 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 modifying 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 If
 120 .Ev MANPATH
 121 begins with a
 122 .Sq \&: ,
 123 it is appended to the default list;
 124 else if it ends with
 125 .Sq \&: ,
 126 it is prepended to the default list; else if it contains
 127 .Sq \&:: ,
 128 the default list is inserted between the colons.
 129 If none of these conditions are met, it overrides the default list.
 130 .El
 131 .Sh FILES
 132 .Bl -tag -width "/etc/man.conf" -compact
 133 .It Pa mandoc.db
 134 name of the
 135 .Xr mandocdb 8
 136 keyword database
 137 .It Pa mandoc.index
 138 name of the
 139 .Xr mandocdb 8
 140 filename database
 141 .It Pa /etc/man.conf
 142 default
 143 .Xr man 1
 144 configuration file
 145 .El
 146 .Sh EXIT STATUS
 147 .Ex -std
 148 .Sh SEE ALSO
 149 .Xr apropos 1 ,
 150 .Xr man 1 ,
 151 .Xr man.conf 5 ,
 152 .Xr mandocdb 8
 153 .Sh HISTORY
 154 The
 155 .Nm
 156 utility first appeared in
 157 .Bx 2 .
 158 It was rewritten from scratch as part of the
 159 .Xr mandocdb 8
 160 project for
 161 .Ox 5.1 .
 162 .Sh AUTHORS
 163 .An -nosplit
 164 .An Bill Joy
 165 wrote the original
 166 .Bx
 167 .Nm
 168 in 1979.
 169 The current version was written by
 170 .An Kristaps Dzonsons ,
 171 .Mt kristaps@bsd.lv .