NAME
findbug - find selected defect record IDs
SYNOPSIS
findbug [-p project] ... [-u username] ... [-o fieldname] ...
[-s] [-e] [-t] [-fqv] [-z] [-NAORVDP] [-k class]
[-c | -d | -r | -h | -g ]
[expr [op expr] ...]
DESCRIPTION
Use findbug to query the ClearDDTS database to answer
questions such as "What are all the severity 1 bugs?". The
options and other command line arguments restrict the search
of the defect database. The bug IDs of any bug records
matching the query are printed on standard out. Ordinarily,
the output of findbug is piped to another program such as
dumpbug(1) or summarybug(1).
If invoked with no options, findbug will list to standard
out every bug ID in the system.
A search of the ClearDDTS database is fast for cached
keywords. These cached keywords may be found in the file
~ddts/dbms/ddts/schema_file. The ClearDDTS administrator can
add additional keywords to this list which will improve
findbug's performance when searching for those keywords. If
entries are added to this list, the defect database must be
rebuilt with the adminbug(1) dbms command. See the
ClearDDTS Administrator's Guide or adminbug(1) for more
information.
The command line options select defect record
characteristics as follows:
-c Specifies that the number of qualifying records is only
to be counted. When the search is over the total
number of qualifying record IDs is printed on the
standard output. The record IDs themselves are not
printed.
-h Instead of printing record IDs to the standard output,
print a pretty projects string from the query for use
with graphbug.
-g Instead of printing record IDs to the standard output,
print a pretty version of the query string for use with
graphbug.
-d Instead of printing record IDs to the standard output,
print the raw defect data from the ClearDDTS database.
The output is written in the same format as the raw
defect record file in ~ddts/allbugs. Only the fields
defined in ~ddts/dbms/ddts/schema_file are printed.
-e This option specifies that defect records assigned to
the invoking user are to be listed. It is the same as
-u username where username is the login name of the
invoking user. If this option is used with the -s
option, records submitted by the invoking user are
listed.
-f Suppress the printing of the message "No bugs were
found that match the search criteria" when no match is
found.
-k class
Restrict the search to only those projects that belong
to class class. Note that this will produce redundant
results if also used with the -p project option if the
project belongs to the same class.
-o fieldname
If one or more -o options are used, the query output is
ordered by the fieldnames. Default SQL ordering
(ascending) is used.
-p project
If one or more -p options are used, the search is
restricted to the named projects. Each project name
must be preceded by a -p option. Shell-style patterns
are supported for project names. For example, the
command:
findbug -N -p lang* -p comp*
would find all of the New bugs in all projects whose
names begin with lang or comp. If such an expression
is entered from the shell, the pattern characters must
be escaped or quoted. Thus, the above example could be
entered as:
$ findbug -N -p lang\* -p 'comp*'
-q Suppress warning message for specification of a bad
project name with the -p option.
-r Instead of printing record IDs to the standard output,
print the raw defect record file itself. This differs
from the -d option in that all fields and the
enclosures are written to the standard output, not just
the fields that are cached. If per project or per bug
security has been installed in the ~ddts/etc/ddtsrc
file, then this option is ignored (its a security
problem).
-s This option changes the meaning of the -u username
option. In this case the search is for defect
submitters with the given username. For example,
findbug -s -u mike
will find all records on this system submitted by user
mike.
-t This option puts findbug into test mode. It returns
the generated SQL string to stdout but does not
actually run the query.
-u username
This restricts the search to defect records assigned to
a user with login name username. This may be used with
other options such as the -p option to find records
logged against the specified project and assigned to
the engineer with name username.
-v This option prints the class name of the first bug that
matches the search criteria. It may not be specified
unless -d has been specified also. The option is used
to give a "hint" about which class of bugs are being
searched. This is used for internal ClearDDTS shell
scripts that need to decide what printing format &
states are associated with a particular group of bugs.
-NAORDVP
Restrict the search to defect records in the specified
states. Each individual upper case letter specified
represents a state that a defect record goes through.
The letters stand for New, Assigned, Open, Resolved,
Duplicate, Verified, and Postponed, respectively. The
findbug program will also accept any user-defined
states and will perform searches on the basis of those
states as well.
expr Each expr is a relational expression that can be
combined with other relational expressions by operators
to direct the search. Parentheses may also be used to
give precedence. These must be escaped or quoted to
prevent their being interpreted directly by the shell.
Each expression has three parts: a keyword, a
relational operator, and a value. For example:
Severity != 1
Engineer == mike
Software has foobar
The relational operators have C-like forms and textual
forms. The textual form may be used for English-like
expressions. Either form of the operator is
acceptable. Listed below are the English-like and C-
like forms.
| English-like | English-like | C-like |
| isequal notequal greaterthan lessthan atleast atmost has hasno |
is after before |
== != > < >= <= |
The has and hasno English-like operators above are for
string comparison. The after and before operators are
provided to help make expressions involving dates more
intelligible.
op The logical operators && and || can be used to combine
expressions, performing the logical AND and OR
operations. Care should be taken with using these with
the shell; they will need to be escaped or quoted.
-z This option changes the SQL code generated with the hasno
and notequal operators. The resulting SQL query does not
match fields that have null values, conforming to SQL
standards. Use the -t option to see the SQL code
generated.
EXAMPLES
Find all bugs in the system:
findbug
Find all of the open bugs in the system:
findbug -O
Find all the bugs on this system which are assigned to mike:
findbug -u mike
Find all the bugs in the system that are unresolved (states
O & A) and assigned to user mike:
findbug -OA -u mike
Find all the bugs submitted by user mike on this system:
findbug -s -u mike
List all the bugs for project compiler:
findbug -p compiler
Find all new and open bugs in projects compiler and kernel:
findbug -NO -p compiler -p kernel
Find all open bugs in project compiler with a severity of 1
or 2:
findbug -O -p compiler "Severity is 1 || \
Severity == 2"
findbug -O -p compiler "Severity <= 2"
Find all open bugs in project blah with severity of 1 or 2
assigned to engineer mike:
findbug -O -p blah "(Severity == 1 || Severity == 2) \
&& Engineer is mike"
Find all of the resolved bugs in project compiler where the
string syntax was used in the headline description of the
bug.
findbug -R -p compiler "Headline has syntax"
WARNING
If you enter these commands to the shell you must escape the
shell meta characters. For example:
% findbug (Severity == 1 || Headline has core) \
&& Opened-on < 900101
will fail if entered as shown above to the shell. Instead
this should be entered as:
% findbug \(Severity == 1 \|\| Headline has core\) \
\&\& Opened-on \< 900101
this will escape the shell meta characters '&', '(', ')',
and '<'.
FILES
~ddts/dbms/ddts/schema_file List of cached keywords
SEE ALSO
bugs(1), dumpbug(1), sortbug(1), summarybug(1)