Alan Hargreaves' Blog

The ramblings of an Australian SaND TSC* Principal Field Technologist

Cscope-fast in OpenSolaris-Land

While Chandan has written an absolutely fabulous source browser, there are times when
you may not have web access (like right now as I am writing this on
a train between Sydney and Gosford) or you may prefer a text based

About a year ago I gave a presentation to our local groups within
PTS about how to use cscope-fast.

This blog entry will be a slight rewrite of that presentation
removing stuff that is not relevant to the open solaris community
and adding a bit that is. For example, you really don’t need to know
where we keep the source trees inside Sun, but you will probably be
interested in how to build the inverted indexes that cscope-fast

Throughout this entry I will almost certainly say cscope.
In actuality I mean cscope-fast. Cscope-fast is a
modified version of cscope that uses larger and faster indexes.

OK, here’s what I’ll cover.

  • Why cscope?
  • What is cscope?
  • How to build indexes
  • Where is cscope?
  • Subtrees with indexes
  • Using cscope
  • Useful options
  • More?

Why Cscope?

Chandan’s browser provides a great interface for basic source tree
functionality. It does, however have it’s limitations.

The big one is that you need to be online to use it.

Another is that you can only look at the online tree with it. If you
have been modifying code, it’s not much use to you.

I’ve also never been a great fan of GUIs and web based interfaces.
While they have their place, give me a text based interface any day.
Cscope is one such tool.

Another nice feature is that I get to browse the code in the editor
of my choice rather than being limited to my browsers

What is Cscope?

This is a screenshot taken while running cscope.

The top line shows the most recent search.

Below that is the list of matches to this search.

At the bottom of the screen are the searches that can be performed.

Some of these are particularly useful.

I’ve found myself using

  • Find Assignments to:, and
  • Functions calling this function:

quite a bit of late.

How to build indexes

There are two options here.

  • Build all of the indexes defined in the source tree
  • Build the ones you are interested in.

/opt/onbld/bin/build_cscope will go away and build the indexes
defined in $SRC/tools/scripts/build_cscope.conf. By default
this means that we will get indexes in

  • usr/src
  • usr/src/uts
  • usr/src/uts/sun4u
  • usr/src/uts/sun4v
  • usr/src/uts/i86pc
  • usr/src/psm/stand
  • usr/src/psm/stand/boot
  • usr/src/psm/stand/boot/sparcv9/sun4u
  • usr/src/psm/stand/boot/sparcv9/sun4v

This build will also create ctags and etags cross references.

Alternately from any of the above named directories you can issue
the command

make cscope.out

This will create the cscope indexes along wit the ctags and etags
cross references for that particular directory.

Where is cscope?

cscope-fast can be found in /opt/onbld/bin/`uname
. For those interested in the sources, they can
be found in $SRC/tools/cscope-fast.

Subtrees with indexes

As mentioned earlier, we can build cscope indexes in various
subtrees. If you are only working with a particular subtree, it
makes sense to run cscope from that subtree to exclude things you
are not interested in. It also substantially speeds up egrep

Using cscope

From a directory with an index issue the command

cscope-fast -dq

-dq is probably the minimum arguments that you should run
with. I’ll mention some of the other options and what they actually
mean later.

You can navigate the search fields with the tab key or the up and
down arrows. When you are on the type of search you want, simply
type the key and hit return.

Let’s see what that looks like.

Yes it’s the same image I used earlier.

In this search we went looking for assignments to pidlock.
This was probably not a great example to use as pidlock
gets assigned from as an argument to mutex_enter(), but it
does show that this search includes the declaration of a variable.

Normally if there is only one match, you will be thrown straight
into the editor. We weren’t in this instance as I was using options
that prevent this. More on this later.

Once you are displaying the matches, you select the one you want by
typing the number to it’s left.

Again, with only -dq as options, you don’t need to hit a
return following thatnumber as there will always be fewer than 10
entries displayed. If you use the options that display more than 10,
then obviously, you will need to hit enter following your

One thing that I shoudl have mentioned earlieris the
$EDITOR environment variable. If you don’t define it, it
looks like it defaults to dtpad. At least it does if you
are running CDE. JDS appears to do the right thing (well that means
vi for me), but it’s probably a good idea to be specific.

Now it is almost always going to be the case that we will get more
than a single page of matches to a search. Plus and Minus (+/-)
allow you to navigate those pages. The space bar will also take you
forward through them.

We also have some search history, so you can drop back to the search
screen to quickly look for something else and then use history to go
back to where you were. History is implemented with Control-B (Back)
and Control-F (Forward).

Of course typing a ? will give you a help screen.

One of the really nice things about using vi is that as I
commented earlier, we created ctags (not being an emacs person, I
assume that the etags are for emacs, but I have not had to work out
how to use them).

This means that while you are looking at a file, you can type

:ta name

to look for the definition of name. Name can be things like
variables, functions or types.

To move back to the file you were editing, pop the tag-stack by
typing Control-T.

A Tag command can be repeated by simply typing


Useful options

Specifying the same options to cscope-fast gets a bit tiring after a
while, besides if you don’t use it a lot you probably don’t want to
have to go and find out what the ones you like were again. The fact
that for some reason the man page is not available does not help here

Saving then in your startup is not a bad idea. You can do this in

Anyway here are the options that I like to use are

  • ‘d’ – pre-built index
  • ‘q’ – fast (inverted) index
  • ‘r’ – show as many lines as will fit on the screen
  • ‘p’ – number of directory elements to display


If you have vim, it has a cscope mode which allows you to do cscope
operatins from inside the editor (in addition to the tag commands). This
adds some useful functionality like being able o have multiple files open
and to be able to jump to a definition simply by using a keystroke whle the
cursor is on top of the function or variable name that you are interested

A discussion of vim is beyond the scope of this introductory writeup and I
haven’t actually played a lot with it either, so if you want to find out
about it, google is your friend. Try the keywords “vim” and “cscope”.

Technorati Tags:


Written by Alan

July 16, 2005 at 5:54 pm

Posted in OpenSolaris

%d bloggers like this: