What does apropos and whatis index?

[scotia]

Hi,

On a 14.3-RELEASE FreeBSD when I type apropos hostcache.list or whatis hostcache.list I get

nothing appropriate

and when I run man tcp | grep "hostcache.list" I get no result.
When I open the man page with man tcp as search for hostcache.list I get:

     hostcache.list         Provide a complete list of all current entries in
                            the host cache.

I'm guessing grep is getting confused by some encoding that makes the entry in the man page a list/table. Maybe.
But shouldn't apropos find that text in the man page?
Thanks

 

[kent_dorfman766]

do the following google search "freebsd makewhatis"

 

[ShelLuser]

In situations like these you can always "go to the source", aka the man command itself. Try this: man -K hostcache. Will take longer, but it'll also find what you need.

I don't have an explanation just yet, but whenever a search fails I always resort to -K.

 

[T-Daemon]

But shouldn't apropos find that text in the man page?

The makewhatis(8) database searched by apropos(1) (whatis(1)) contains only the "NAME" section from each manual page, not the full page (see bold highlighted) :

TCP(4)                 FreeBSD Kernel Interfaces Manual                 TCP(4)

NAME
     tcp – Internet Transmission Control Protocol

This means, a apropos(1) (whatis(1)) search can search only for the name and short description in "tcp – Internet Transmission Control Protocol":

This is described (not so obvious) in the apropos(1) (whatis(1)) manual:

DESCRIPTION

     By default, apropos searches for makewhatis(8) databases in the default
     paths stipulated by man(1) and uses case-insensitive extended regular
     expression matching over manual names and descriptions (the Nm and Nd
     macro keys).  Multiple terms imply pairwise -o.

Note Nm and Nd macro keys above and below in the raw man page:

% zless /usr/share/man/man4/tcp.4.gz
...
.Nm tcp
.Nd Internet Transmission Control Protocol

The mentioned man -K <pattern> by ShelLuser is a way to search, but it is excruciatingly slow. Here an example on a system installed on a NVMe:

$   \time -h man -K 'Internet Transmission'
/usr/share/man/man4/tcp.4.gz:     tcp – Internet Transmission Control Protocol
    1m4.91s real        41.93s user        51.15s sys

I use textproc/ugrep to search for patterns in all man pages. It's extremely fast, and has a nice visualization of the result::

$ \time -h ug -rIz hostcache.list /usr/share/man
/usr/share/man/man4/tcp.4.gz
   693:    .It Va hostcache.list

    0.13s real        0.57s user        0.85s sys

0.13s seconds, a fraction of 1m4.91s, in this example.

Search for pattern in multiple manpath(1):

ug -rIz <pattern> /usr/share/man /usr/local/share/man