ref - Display a C function header
ref [-t] [-c class]... [-f file]... tag
ref quickly locates and displays the header of a function. To do this,
ref looks in the "tags" file for the line that describes the function,
and then scans the source file for the function. When it locates the
function, it displays an introductory comment (if there is one), the
function's declaration, and the declarations of all arguments.
ref uses a fairly sophisticated tag look-up algorithm. If you supply a
filename via -f file, then elvis first scans the tags file for a static
tag from that file. This search is limited to the tags file in the
If you supply a classname via -c class, then elvis searches for a tag
from that class. This search is not limited to the current directory;
You can supply a list of directories in the environment variable TAGPATH,
and ref will search through the "tags" file in each directory until it
finds a tag in the desired class.
If that fails, ref will then try to look up an ordinary global tag. This
search checks all of the directories listed in TAGPATH, too.
If you've given the -t flag, then ref will simply output the tag line
that it found, and then exit. Without -t, though, ref will search for
the tag line. It will try to open the source file, which should be in
the same directory as the tags file where the tag was discovered. If the
source file doesn't exist, or is unreadable, then ref will try to open a
file called "refs" in that directory. Either way, ref will try to locate
the tag, and display whatever it finds.
INTERACTION WITH ELVIS
ref is used by elvis' shift-K command. If the cursor is located on a
word such as "splat", in the file "foo.c", then elvis will invoke ref
with the command "ref -f foo.c splat".
If elvis has been compiled with the -DEXTERNAL_TAGS flag, then elvis will
use ref to scan the tags files. This is slower than the built-in tag
searching, but it allows elvis to access the more sophisticated tag
lookup provided by ref. Other than that, external tags should act
exactly like internal tags.
-t Output tag info, instead of the function header.
The tag might be a static function in file. You can use several -f
flags to have ref consider static tags from more than one file.
The tag might be a member of class class. You can use several -c
flags to have ref consider tags from more than one class.
tags List of function names and their locations, generated by ctags.
refs Function headers extracted from source files (optional).
List of directories to be searched. The elements in the list are
separated by either semicolons (for MS-DOS, Atari TOS, and
AmigaDos), or by colons (every other operating system). For each
operating system, ref has a built-in default which is probably
You might want to generate a "tags" file the directory that contains the
source code for standard C library on your system. If licensing
restrictions prevent you from making the library source readable by
everybody, then you can have ctags generate a "refs" file, and make
"refs" readable by everybody.
If your system doesn't come with the library source code, then perhaps
you can produce something workable from the lint libraries.