Re: locate(1) man page hard to understand, please rewrite

[Paul D. Smith]

%% address@hidden (Dan Jacobson) writes:

  dj> DESCRIPTION
  dj>        This manual page documents the GNU version of locate.  For
  dj>        each  given pattern, locate searches one or more databases
  dj>        of file names and displays the file names that contain the
  dj>        pattern.  Patterns can contain shell-style metacharacters:
  dj>        `*', `?', and `[]'.  The metacharacters do not  treat  `/'
  dj>        or  `.'   specially.   Therefore,  a pattern `foo*bar' can
  dj>        match a file name that contains `foo3/bar', and a  pattern
  dj>        `*duck*'   can   match   a   file   name   that   contains
  dj>        `lake/.ducky'.   Patterns  that   contain   metacharacters
  dj>        should  be  quoted  to  protect them from expansion by the
  dj>        shell.

  dj> I think it is trying to say that it does an fgrep style search on
  dj> its database.

Why would you think that?  fgrep searches for static strings with no
special characters.

The above paragraph _clearly_ states that "Patterns can contain
shell-style metacharacters".

What this paragraph is trying to say is that locate uses _shell_
filename matching metacharacters ("globbing") rather than full regular
expression metacharacters, like grep or sed or whatever.

  dj>        If a pattern is a plain string -- it contains no metachar-
  dj>        acters  --  locate displays all file names in the database
  dj>        that contain that string anywhere.  If a pattern does con-
  dj>        tain  metacharacters, locate only displays file names that
  dj>        match the pattern exactly.  

  dj> I think it is trying to say that it does an fgrep style search on
  dj> its database.

Again, I can't see how you would think that as it directly contradicts
what's written there.

  dj>                                    As  a  result,  patterns  that
  dj>        contain  metacharacters  should  usually begin with a `*',
  dj>        and will most often end with one as well.  The  exceptions
  dj>        are  patterns  that  are  intended to explicitly match the
  dj>        beginning or end of a file name.

  dj> You got my head spinning.  Can someone please rewrite this page with
  dj> the babytalk I need, or maybe I got too much...  Or maybe it should
  dj> have two explanations, one for pros: we do an fgrep style search on
  dj> the database, etc. and then also an elaboration for beginners.

Maybe you can give it a shot, because it seems fairly straightforward to
me.  It may be overly verbose, and thus confusing, but I certainly don't
see where you obtained the conclusions you did from the text.

  dj> Anyway, I wanted to search for any directories called tmp, so I did
  dj> $ locate /tmp$ #no good
  dj> $ locate /tmp|grep /tmp$ #best I can do I suppose

Neither of these will work.

First, it's safest to quote uses of "$" on a shell command line.

Second, the astute reader will note that "$" is not listed among the
"shell-style metacharacters" in the man page, so your use of it here
simply means you are looking for the file literally named '/tmp$'.  Of
which you apparently don't have one.

As mentioned above, locate takes shell pattern matching expressions,
_NOT_ regular expressions like grep.  There is no "$" in shell pattern
matching.

In fact, in shell pattern matching, unlike most regular expressions, the
pattern must match the _entire_ filename.  So:

  $ locate /tmp

will match _only_ the exact path '/tmp'.  It will _NOT_ match anything
containing '/tmp'; for the latter you need:

  $ locate '*/tmp*'

  dj> Anyway, I think the man page is trying to say that it doesn't have
  dj> any wildcard matching ability at all?

Again, I don't see how you get that from the above text.  If that were
true, why would it discuss the special metacharacters, and talk about
patterns matching filenames?

-- 
-------------------------------------------------------------------------------
 Paul D. Smith <address@hidden>          Find some GNU make tips at:
 http://www.gnu.org                      http://www.paulandlesley.org/gmake/
 "Please remain calm...I may be mad, but I am a professional." --Mad Scientist