Go to the first, previous, next, last section, table of contents.

Database Query Tools

The ID database is useless without database query tools. The remainder of this document describes those tools.

The lid, gid, aid, eid, and pid programs are all the same program installed with links to different names. The name used to invoke the program determines how it will act.

The iid program is an interactive query shell that sits on top of the other query tools.

Common Options

Since many of the programs are really links to one common program, it is only reasonable to expect that most of the query tools would share common command line options. Not all options make sense for all programs, but they are all described here. The description of each program gives the options that program uses.

-f<file>
Read the database specified by <file>. Normally the tools look for a file named `ID' in either the current directory or in any of the directories above the current directory. This means you can keep a global `ID' database in the root of a large source tree and use the query tools from anywhere within that tree.
-r<directory>
The query tools usually assume the file names in the database are relative to the directory holding the database. The -r option tells the tools to look for the files relative to <directory> regardless of the location of the database.
-c
This is shorthand for -r`pwd`. It tells the query tools to assume the file names are stored relative to the current working directory.
-e
Force the pattern arguments to be treated as regular expressions. Normally the query tools attempt to guess if the patterns are regular expressions or simple identifiers by looking for special characters in the pattern.
-w
Force the pattern arguments to be treated as simple words even if they contain special regular expression characters.
-k
Normally the query tools that generate lists of file names attempt to compress the lists using the csh brace notation. This option suppresses the file name compression and outputs each name in full. (This is particularly useful if you are a ksh user and want to feed the list of names to another command -- the -k option comes from the k in ksh).
-g
It is possible to build the query tools so the -k option is the default behavior. If this is the case for your system, the -g option turns on the globbing of file names using the csh brace notation.
-n
Normally the query tools that generate lists of file names also list the matching identifier at the head of the list of names. This is irritating if you want just a list of names to feed to another command, so the -n option suppresses the identifier and lists only file names.
-b
This option is only used by the pid tool. It restricts pid to pattern match only the basename part of a file name. Normally the absolute file name is matched against the pattern.
-d -o -x -a
These options may be used in any combination to limit the radix of numeric matches. The -d option will allow matches on decimal numbers, -o on octal, and -x on hexadecimal numbers. The -a option is shorthand for specifying all three. Any combination of these options may be used.
-m
Merge multiple lines of output into a single line. (If your query matches more than one identifier the default action is to generate a separate line of output for each matching identifier).
-s
Search for identifiers that appear only once in the database. This helps to locate identifiers that are defined but never used.
-u<number>
List identifiers that conflict in the first <number> characters. This could be useful porting programs to brain-dead computers that refuse to support long identifiers, but your best long term option is to set such computers on fire.

Patterns

You can attempt to match either simple identifiers or numbers in a query, or you can specify a regular expression pattern which may match many different identifiers in the database. The query programs use either regex and regcmp or re_comp and re_exec, depending on which one is available in the library on your system. These might not always support the exact same regular expression syntax, so consult your local man pages to find out. Any regular expression routines should support the following syntax:

.
A dot matches any character.
[ ]
Brackets match any of the characters specified within the brackets. You can match any characters except the ones in brackets by typing ^ as the first character. A range of characters can be specified using -.
*
An asterisk means repeat the previous pattern zero or more times.
^
An ^ at the beginning of a pattern means the pattern must match starting at the first character of the identifier.
$
A $ at the end of the pattern means the pattern must match ending at the last character in the identifier.

Lid

Command: lid [-f<file>] [-u<n>] [-r<dir>] [-ewdoxamskgnc] patterns...

The lid program stands for lookup identifier. It searches the database for any identifiers matching the patterns and prints the names of the files that match each pattern. The exact format of the output depends on the options.

Aid

Command: aid [-f<file>] [-u<n>] [-r<dir>] [-doxamskgnc] patterns...

The aid command is an abbreviation for apropos identifier. The patterns cannot be regular expressions, but it looks for them using a case insensitive match, and any pattern that is a substring of an identifier in the database will match that identifier.

For example `aid get' might match the identifiers fgets, GETLINE, and getchar.

Gid

Command: gid [-f<file>] [-u<n>] [-r<dir>] [-doxasc] patterns...

The gid command stands for grep for identifiers. It finds identifiers in the database that match the specified patterns, then greps for those identifiers in just the set of files containing matches. In a large source tree, this saves a fantastic amount of time.

There is an emacs interface to this program (see section GNU Emacs Interface). If you are an emacs user, you will probably prefer the emacs interface over the eid tool.

Eid

Command: eid [-f<file>] [-u<n>] [-r<dir>] [-doxasc] patterns...

The eid command allows you to invoke an editor on each file containing a matching pattern. The EDITOR environment variable is the name of the program to be invoked. If the specified editor can accept an initial search argument on the command line, you can use the EIDARG, EIDLDEL, and EIDRDEL environment variables to specify the form of that argument.

EDITOR
The name of the editor program to invoke.
EIDARG
A printf string giving the form of the argument to pass containing the initial search string (the matching identifier). For vi it should be set to `+/%s/''.
EIDLDEL
A string giving the regular expression pattern that forces a match at the beginning (left end) of a word. This string is inserted in front of the matching identifier when composing the search argument. For vi, this should be `\<'.
EIDRDEL
The matching right end word delimiter. For vi, use `\>'.

Pid

Command: pid [-f<file>] [-u<n>] [-r<dir>] [-ebkgnc] patterns...

The pid tool is unlike all the other tools. It matches the patterns against the file names in the database rather than the identifiers in the database. Patterns are treated as shell wild card patterns unless the -e option is given, in which case full regular expression matching is done.

The wild card pattern is matched against the absolute path name of the file. Most shells treat slashes `/' and file names that start with dot `.' specially, pid does not do this. It simply attempts to match the absolute path name string against the wild card pattern.

The -b option restricts the pattern matching to the base name of the file (all the leading directory names are stripped prior to pattern matching).

Go to the first, previous, next, last section, table of contents.