.\" 
'\"macro stdmacro
.TH tgrep 1 "Apr 12 1995"
.\" 
.\" 
.SH NAME
tgrep \- A multi-threaded version of grep with new features.
.SH SYNOPSIS
.B tgrep <options> pattern <{file/dir}>...

.SH DESCRIPTION
.B tgrep
supports all of grep(1) options except for the \-w option. It also has
a number of custom options not supported by grep(1)
.PP
tgrep will supply three different usage messages depending on the
arguments you pass to it to get more information. The first is the
option usage, which can be viewed by starting tgrep with no
option. The second is the usage for tgrep regular expression language,
which can be used by running tgrep with the -Z option. The last usage
message is avaliable only if tgrep was build with DEBUG turned on. If
this is the case, starting tgrep with the -d0 (zero) option will
display the usage on the different levels of debug information tgrep
will display.
.PP
Tgrep will search all directories and all files in the named
directories on the command line for a literal string, or a regular
expression string. tgrep will search recursively down through the
sub-directories. The same type of search could be performed by using the
command:
.PP
find . \-type f \-exec grep <pattern> /dev/null {} \\; 
.PP
or using tgrep:
.PP
tgrep <pattern> .
.PP 
If you do not specify a directory or file name on the command line,
the current working directory is added for you (DOT). All files in the
current directory and all files in all sub-directories below . (dot)
will be searched.
.PP
Tgrep supports two different pattern matching engines. The default is
a literal pattern matching algorithm called "Boyer-Moore". This is
used for fast literal string matching only. Tgrep supports regular
expression searching also. With the \-e option set, "Boyer-Moore" is
not used, in place of it, a PD regular expression engine is used. 

.SH OPTIONS (grep(1) like)
.B \-b 
Show block count. Block size is 512 bytes.
.br
.B \-c 
Print only a line count.
.br
.B \-h
Do not print the file name(s).
.br
.B \-i  
Case insensitive search.
.br
.B \-l  
Print file name only.
.br
.B \-n  
Print the line number with the line.
.br
.B \-s  
Suppress error messages.
.br
.B \-v  
Print all but matching lines.

.SH OPTIONS (Tgrep only)
.br
.B \-r  
Do not search for files in all sub-directories.
.br
.B \-C  
Show continued lines. Great for Makefile searches. ("\\")
.br
.B \-p  
File name regexp pattern. (Quote it).
.br
.B \-P  
Show progress. \-P1 prints a DOT on stderr for each file it finds,
-P10 prints a DOT on stderr for each 10 files it finds, etc...
.br
.B \-e  
Regular expression search. More then one \-e option is supported.
.br
.B \-B  
Limit the number of threads to TGLIMIT (see ENVIRONMENT below).
.br
.B \-S  
Print thread stats when done.
.br
.B \-Z  
Print help on the regexp used.


.SH OPTIONS (debug only)
.B \-d <levels> 
Print debug messages as tgrep is running to show what thread is
performing what operation. \-d0 (zero) will print debug usage.
.br
.B \-f #
Stop tgrep from using "#" (number) of file descriptors. Tgrep normally
will uses all the file descriptors the user has avaliable, but if
tgrep is run under debugger control, you need to reserve some.

.SH REGEXP LANGUAGE

Tgrep supports a custom regular expression language write by Marc
Staveley of Staveley.com. At the time tgrep was first written, libgen
was not MT-SAFE, so the systems regular expression functions could not
be used. Marc's regular expression engine supports most if not all the
normal expressions, and some unique ones.
.PP
.B meta-chars:
.in +0.25i
    . \- match any character. 
    * \- match 0 or more occurrences of pervious char. 
    + \- match 1 or more occurrences of pervious char. 
    ^ \- match at beginning of string.
    $ \- match end of string.
    [ \- start of character class.
    ] \- end of character class.
    ( \- start of a new pattern.
    ) \- end of a new pattern.
    @(n)c \- match <c> at column <n>.
    | \- match either pattern.
    \\ \- escape any special characters.
    \\c \- escape any special characters.
    \\o \- turn on any special characters.
.in -0.25i
.PP
To use the "or" operator, i.e. 
.br 
tgrep \-e '(pat1)|(pat2)' file ...
.br 
And you can have up to 10 \-e options on the same command line.

.SH ENVIRONMENT
.B TGLIMIT
Set the maximum number of threads tgrep will start at any one
time. This will limit the amount of resources tgrep will use on the
system. TGLIMIT is ignored if the -B option is NOT set on the command
line.

.SH FILES
NONE

.SH NOTES

.SH DIAGNOSTICS

Some of the "grep like" options do not behave exactly like
grep(1). This is why they are called "grep like". 

.SH EXAMPLES

To search all files from the current directory down, for the target
string foobar run:
.PP
tgrep foobar
.PP
To search all files from the current directory down, for the target
strings foobar or bizbar run:
.PP
tgrep \-e '(foobar)|(bizbar)' 
.br
or
.br
tgrep \-e 'foobar' \-e 'bizbar' .
.PP
To search all README files in the current directory and all
sub-directories for the strings boobar or foobar run:
.PP
tgrep \-p '^README$' \-e '[bf]oobar'
.PP
If the "$" char was omitted from the \-p option, then file names like
README.first, READMENOW, etc would also be searched.
.PP
To search all man page directories for a string of foobar, run:
.PP
tgrep foobar /usr/man /usr/local/man /opt/man
.PP
To search for the continued line SRC= in all Makefile (or makefile,
makefile.master, etc) from the current directory and down, run:
.PP
tgrep \-p '^[Mm]akefile' \-C \-e '^SRC.*='
.PP
The above command would find and display lines that look like:
.PP
SRC = \\
.in +0.25i
	foobar.c \\
.br
	main.c \\
.br
	lastfile.c
.in -0.25i

.SH AUTHOR
Ron Winacott	Email : Ron.Winacott@Canada.sun.com

