# cscope toolman page

## NAME

           cscope - interactively examine a C program

## SYNOPSIS

           cscope [ options ] [ C source files ]

## DESCRIPTION

           Cscope  is  an interactive screen-oriented tool that helps
           you:

                  Learn how a C program works without  endless  flip-
                  ping through a thick listing.

                  Locate  the  section of code to change to fix a bug
                  without having to learn the entire program.

                  Examine the effect of a  proposed  change  such  as
                  adding a value to an enum variable.

                  Verify  that  a  change has been made in all source
                  files such as adding an  argument  to  an  existing
                  function.

                  Rename a global variable in all source files.

                  Change  a  constant  to  a  preprocessor  symbol in
                  selected lines of files.

           It is designed to answer questions like:

                  Where is this symbol used?
                  Where is it defined?
                  Where did this variable get its value?
                  What is this global symbol's definition?
                  Where is this function in the source files?
                  What functions call this function?
                  What functions are called by this function?
                  Where does the message "out of space" come from?
                  Where is this source file in the directory structure?
                  What files include this header file?

           Cscope answers these questions from a symbol database that
           it  builds  the first time it is used on the source files.
           On a subsequent call, cscope rebuilds the database only if
           a  source  file has changed or the list of source files is
           different.  When the database is rebuilt the data for  the
           unchanged  files  is  copied  from the old database, which
           makes rebuilding much faster than the initial build.

           After the database is  ready  cscope  will  display  these
           input fields:

                  Find this C symbol:
                  Find this definition:
                  Find functions called by this function:
                  Find functions calling this function:
                  Find assignments to:
                  Change this grep pattern:
                  Find this egrep pattern:
                  Find this file:
                  Find files #including this file:

           Press  the TAB key repeatedly to move to the desired input
           field, type the pattern to search for, and then press  the
           RETURN  key.  For the first 5 and last 2 input fields, the
           pattern can be a regcmp(3X) regular  expression.   If  the
           search  is  successful,  you can use these command charac-
           ters:

           1-9    Edit the file containing the displayed line.
           space  Display next lines.
           +      Display next lines.
           -      Display previous lines.
           ^E     Edit all lines.
           >      Write all lines to a file.
           >>     Append all lines to a file.
           <      Read lines from a file.
           ^      Filter all lines through a shell command.
           |      Pipe all lines to a shell command.

           At any time you can use these command characters:

           ^P     Move to the previous input field.
           ^A     Search again with the last pattern typed.
           ^B     Recall previous input field and search pattern.
           ^F     Recall next input field and search pattern.
           ^C     Toggle ignore/use letter case when searching.
           ^R     Rebuild the symbol database.
           !      Start an interactive shell (type ^D  to  return  to
                  cscope).
           ^L     Redraw the screen.
           ?      Display this list of commands.
           ^D     Exit cscope.

           Note:  If  the  first character of the pattern you want to
           search for matches one of the above  commands,  type  a  \
           character first.

       Changing Text
           After  typing  the grep(1) pattern to be searched for, you
           will be prompted for the replacement text, then the  lines
           containing  the pattern will be displayed.  You select the
           lines to be changed with these command characters:

           1-9    Mark or unmark the line to be changed.
           *      Mark or unmark all displayed lines to be changed.
           space  Display next lines.
           +      Display next lines.
           -      Display previous lines.
           a      Mark or unmark all lines to be changed.
           ^D     Change the marked lines and exit.
           RETURN Exit without changing the marked lines.
           !      Start an interactive shell (type ^D  to  return  to
                  cscope).
           ^L     Redraw the screen.
           ?      Display this list of commands.

       Special Keys
           If your keyboard has arrow keys that work in vi(1) you can
           use them to move around the input  fields.   The  up-arrow
           key  is useful to move to the previous input field instead
           of using the TAB key repeatedly.  If you have  the  CLEAR,
           NEXT,  or PREV keys they will act as the ^L, +, and - com-
           mands respectively.

       Mouse
           If you have an AT&T  5620/630/730  terminal  and  use  the
           emacsterm(1),  myx(1),  or viterm(1) terminal programs; or
           use the X Window System and the  etermx(1)  terminal  pro-
           gram;  or  SunView  and the eterm(1) terminal program; you
           can use your mouse with cscope.  If  you  use  the  myx(1)
           terminal  program,  set  the MOUSE environment variable to
           myx (see ENVIRONMENT VARIABLES).

           Point with the mouse and click button 1  to  move  to  the
           desired  input  field, type the pattern to search for, and
           then press the RETURN key.  If the search  is  successful,
           you  can  edit  the  file  containing  a displayed line by
           pointing with the  mouse  and  clicking  button  1.   When
           changing  text, point with the mouse and click button 1 to
           mark or unmark the line to be changed.  Press mouse button
           2 to get a menu of commands.

       Options
           When invoking cscope you can use these options:

           -a       When using the "Find this egrep pattern:" search,
                    ask for a regular expression describing the  sub-
                    set of files to search.  If no expression is sup-
                    plied, all files known to  cscope  are  searched.
                    This option is particularly useful for very large
                    software systems where thousands of source  files
                    are used.  In such systems the set of files to be
                    searched is a small subset of  the  total.   This
                    option  is  also  available as the 'a' command in
                    the command-line interface.  The -l or -L options
                    turn off this option.
           -b       Build the database only.
           -c       Use  only  ASCII characters in the database file,
                    that is, do not compress the data.
           -C       Ignore letter case when searching.
           -d       Do not update the database.
           -e       Suppress the ^E command prompt between files.
           -f file  Use file as the database file name instead of the
                    default (cscope.out).
           -F file  Read  symbol reference lines from file, just like
                    the < command.
           -i file  Read any -I, -p, -q, and -T options and the  list
                    of  source files from file instead of the default
                    (cscope.files).
           -I dir   Look in dir for #include files.  If you  will  be
                    editing these files, use the -s option instead so
                    the rebuild (^R) command will  notice  they  have
                    changed.
           -k       Kernel  Mode  turns  off  the  use of the default
                    include dir (usually /usr/include) when  building
                    the database, since kernel source trees generally
                    do not use it.
           -l       Line-oriented interface (see Calling Cscope  with
                    a Line-Oriented Interface).
           -L       Do a single search with line-oriented output when
                    used with the -n pattern option.
           -o       Display OGS book and subsystem names.
           -p n     Display the last n file path  components  instead
                    of  the  default  (1).   Use 0 to not display the
                    file name at all.
           -P path  Prepend path to relative file  names  in  a  pre-
                    built  database  so  you do not have to change to
                    the directory where the database was built.  This
                    option  is only valid with the -d option.  Do not
                    use this option  if  a  viewpath  was  used  when
                    building the database (see Viewpath subsection of
                    EXAMPLES section).
           -q       Build an inverted index for quick  symbol  seach-
                    ing.   If you use this option with the -f option,
                    you must use -f on every call to cscope,  includ-
                    ing building the database, because it changes the
                    names of the inverted index files.

                    NOTE: This is not available on MSDOS or  MS  Win-
                    dows versions.
           -r       Require  pressing the RETURN key after typing the
                    selection digit(s) for a displayed line  to  edit
                    the  file  containing  it,  which  allows as many
                    lines as possible to be displayed.
           -R       Recurse subdirectories during search  for  source
                    files.

           -s dir   Look  in  dir  for additional source files.  This
                    option is ignored if source files  are  given  on
                    the command line.
           -t hours No  activity  timeout  in  hours  (minimum  of  4
                    hours).  Removing a database will not release the
                    disk space if a cscope process has the file open,
                    so a project can use this option in its script to
                    call  cscope  on  a  large database so unattended
                    cscope processes will exit overnight.
           -T       Use only the  first  eight  characters  to  match
                    against C symbols.  A regular expression contain-
                    ing special characters other than  a  period  (.)
                    will  not  match any symbol if its minimum length
                    is greater than eight characters.
           -u       Unconditionally build the database  (assume  that
                    all files have changed).
           -U       Do  not  check file time stamps (assume that some
                    files have changed).
           -x ext   Use the extended menu with option ext.  When  ext
                    is  set to "c", cscope will emulate ccalls(1) and
                    will display the following input  fields  instead
                    of the normal menu:
                  Find this type definition:
                  Find this preprocessor definition:
                  Find parameters of this function:
                  Find functions calling this function:
                  Find this global definition:
                  Find this local definition:
                  Find this structure definition:
                  Find this file:
                  Find this preprocessor include:
           When  ext  is  set to "s", system calls are ignored in the
           output.  To combine extension options,  use  concatenation
           e.g. "cs".  See cscalls(1).
           -n pattern
                  Go to input field n (counting from 0) and find pat-
                  tern.  The input field number is the  line  number,
                  counting  from  0,  of the search type displayed on
                  the screen. That is, given the following table

                 +----------------------------------------------------+
                 |LINE                   SEARCH TYPE                  |
                 +----------------------------------------------------+
                 | 0     Find this C symbol:                          |
                 | 1     Find this definition:                        |
                 | 2     Find functions called by this function:      |
                 | 3     Find functions calling this function:        |
                 | 4     Find assignments to:                         |
                 | 5     Change this grep pattern:                    |
                 | 6     Find this egrep pattern:                     |
                 | 7     Find this file:                              |
                 | 8     Find files #including this file:             |
                 +----------------------------------------------------+
                 |           (Used by samuel and cdb only)            |
                 | 9     Find all function/class definitions (samuel) |
                 | :     Find all function/class definitions (cdb)    |
                 +----------------------------------------------------+
                 |      (Used by ccalls with the extended menu)       |
                 | 0     Find this type definition:                   |
                 | 1     Find this preprocessor definition:           |
                 | 2     Find parameters of this function:            |
                 | 3     Find functions calling this function:        |
                 | 4     Find this global definition:                 |
                 | 5     Find this local definition:                  |
                 | 6     Find this structure definition:              |
                 | 7     Find this file:                              |
                 | 8     Find this preprocessor include:              |
                 | 9     Find definition of this function:            |
                 | :     Find all function/class definitions:         |
                 +----------------------------------------------------+
           If you wanted to "Find assignments to", then you would use
           "-4 pattern"

           The  -c, -k, -I, -p, -q, and -T options can also be in the
           cscope.files file.  See below for common uses of  most  of
           these options.

## EXAMPLES

       Calling Cscope from the Shell
           To use cscope on all the C, lex, yacc, breakpoint listing,
           Ingres(TM), and SDL files in the  current  directory  just
           type

                  cscope

           You  can  use  cscope on particular files if you have more
           than one program in the  same  directory.   The  above  is
           equivalent to

                  cscope *.[chlyCGHL] *.bp *.q[ch] *.pr *.sd

           If  you  want to use cscope on all the source files in the
           current and a few other directories, use the -s option  to
           give the other directory names, e.g.
                  cscope -s ../common,../../common

           If  you  want to use cscope on all the source files in the
           current and lower level directories, first create  a  list
           of the files with

                  find . -name '*.[chlyCGHL]' -print >cscope.files

           and then type

                  cscope

           Cscope  will  look  up  the  viewpath for the cscope.files
           file, so you can put it under change management to prevent
           accidental destruction.

           If  a  file #include's files that are in directories other
           than the  current  directory  or  the  standard  directory
           (/usr/include), use the -I option just like when using the
           cc(1) command

                  cscope -I../hdr -I../../hdr

           If you will be editing these  files,  use  the  -s  option
           instead  so the rebuild (^R) command will notice they have
           changed.

           If files may have the same base name, you will want to use
           the  -p  option to display the last n file path components
           instead of the default (1).

           If you use a compiler that  does  not  support  flexnames,
           that is, symbol name differences past eight characters are
           ignored, you will want to use the -T option to have cscope
           do the same.

           You can put -c, -k, -I, -p, -q, and -T options in the file
           containing the list of source  files  (see  above).   This
           shortens  the  cscope  command line and makes it easier to
           call cscope from an editor.

           If you use cscope on thousands of source files, use the -b
           option  to only build the database so you can do run it in
           the background with a batch(1) or at(1) job.

                  echo 'cscope -b' | batch

           Use the -d option on subsequent calls to cscope

                  cscope -d

           to avoid the time spent checking if the database is out of
           date, which can be significant.

           If the source files change infrequently, you can get quick
           symbol searching by building  the  database  with  the  -q
           option.   For  a  very  large database you will be able to
           find a symbol in a few  seconds  vs.  several  minutes  if
           built  without  -q,  at the expense of about twice as much
           database disk space and build CPU  time.   Updating  a  -q
           database  takes  about as half as long as building it.  It
           contains binary numbers, so it is  portable  only  between
           machines  with  the  same byte order and scalar-type sizes
           (such as int, long, short, char, and pointer).  Note  that
           3B,  Amdahl/IBM,  and MC680x0-based machines like Suns all
           have the same byte order.

           The -q option makes it practical  to  have  databases  for
           entire  projects.   If you try to build a project database
           and get a "File too large" message, you need to  get  your
           login's  ulimit  (file  size  limit) raised by your system
           administrator.  If you get the "No space left  on  device"
           message  you  will  have  to  use  a file system with more
           space.  You can change the temporary file system  by  set-
           ting  the TMPDIR environment variable.  If you have enough
           space to build the database but not to  rebuild  it  after
           some  files  have changed, try removing the inverted index
           cscope.in.out and cscope.po.out files.  If you still don't
           have  enough space to rebuild, you will have to remove the
           cscope.out file.

           If you want to use cscope separately on  several  programs
           in the same directory structure, but keep the databases in
           the same (top) directory, use the -f  and  -i  options  to
           rename the cscope.out and cscope.files file, respectively,
           e.g.

                  find dir1 -name '*.[chlyCGHL]' -print >dir1.files
                  find dir2 -name '*.[chlyCGHL]' -print >dir2.files
                  cscope -b -f dir1.db -i dir1.files
                  cscope -b -f dir2.db -i dir2.files

           and call cscope with

                  cscope -d -f dir2.db

           Note that options used only when  building  the  database,
           such  as  -i, are not needed with the -d option.  If other
           people are going to use these databases, you  will  should
           provide  a  shell  script  to call cscope with the correct
           options.  If a viewpath (see Viewpath below) was not  used
           when building the database, then use the -P option to give
           the path to relative file names so  the  script  does  not
           have  to  change  to  the directory where the database was
           built, which can confuse users.

       Calling Cscope with Compressed Databases
           To call cscope with a database which has  been  compressed
           using gzip, bzip2 or i<I>p just type

                  cscope -d

           The  compressed database will be uncompressed into a cache
           directory before being opened by cscope.  If the  database
           already exists in the cache, then no uncompressing will be
           performed and the existing database in the cache  will  be
           used.   The uncompressed database will be placed in a sub-
           directory in the cache, which derives its  name  from  the
           last two directories of the database filename.  This means
           different databases  will  be  stored  separately  in  the
           cache.

           If  a  compressed  database exists in the VPATH and in the
           current directory, then  following  normal  VPATH  conven-
           tions,  the  database  in  the  current  directory will be
           uncompressed into the cache.  If an uncompressed  database
           exists before a compressed database in the VPATH, then the
           uncompressed database will be accessed  as  normal.   How-
           ever,  if the cscope.out file has been removed in the cur-
           rent directory but the inverted indexes have been not been
           deleted,  then  be  warned that cscope may try to open the
           database in the cache and the inverted indexes in the cur-
           rent  directory.   If  this  is not the desired behaviour,
           then please remove the  unwanted  inverted  indexes  along
           with the uncompressed database.

           When  building  the  database,  if  a  compressed database
           exists in the VPATH, then cscope will uncompress it in the
           current directory before attempting to build the database.
           This allows the database to be built  and  compressed  and
           when  the  database  is updated, cscope will automatically
           uncompress the database ready for update.

           The compression of databases is not implemented by cscope.

           Control  of  the cache is suggested to be performed by the
           system administrator.  The file /etc/cscopemaxcache can be
           created,  containing  the  maximum  number of files in the
           cache.  If the cache size has been exceeded,  then  cscope
           will  attempt to remove files from the cache before uncom-
           pressing a new database.  If /etc/cscopemaxcache does  not
           exist,  then  no limit on the number of files in the cache
           will be applied,  except  for  the  following  check.   If
           TMPDIR  is more than 50% full, then cscope will attempt to
           remove  1  sub-directory  before   uncompressing   a   new
           database.

       Calling Cscope from an Editor
           To call cscope from within vi(1) type :!cscope followed by
           any  options  or  file  arguments.   From  emacs(1)   type
           M-!cscope  followed  by  any  file arguments.  There is an
           emacs(1) macro for the two most common  calls  to  cscope.
           Type  M-X  to call cscope with no file arguments, and type
           ^UM-X to call cscope with the -d option to not update  the
           database.   If nothing happens when you type M-X, add this
           line to your $HOME/.emacs_init and/or $HOME/.ve_init file:

                  ^X^L~EMACS/macros/basic

       Stacking Cscope and Editor Calls
           When  cscope  puts you in the editor to display one symbol
           reference and you see another symbol  of  interest,  don't
           leave  the  editor, just call cscope again from within the
           editor.  In this way you can stack cscope and editor calls
           so  you can go off on a tangent, and then back up to where
           you were by  exiting  the  tangential  cscope  and  editor
           calls.

           For  example,  when  learning  a program you will probably
           have cscope find the main function  and  display  it  with
           your  editor.   You can visualize this as an inverse stack
           of calls:

                  cscope: find and display main()
                       editor: display first lines of main()

           You may then see that main calls an  initialize  function.
           Rather  than exiting the editor to go back to cscope, call
           cscope again from within the editor to find the initialize
           function  and  display  it with another editor call.  Your
           stack of calls now looks like this:

                  cscope: find and display main()
                       editor: display first lines of main()
                                                                      cscope: find and display initialize()
                                                                      editor: display first lines of initialize()

           When you are through looking at  this  function,  you  can
           exit this second editor call, exit the second cscope call,
           and you are back in the first editor call that is display-
           ing the main function.  You are now back to:

                  cscope: find and display main()
                       editor: display first lines of main()

           and can continue reading the main function.

       Boolean Searching
           You  can  do the equivalent of Boolean or logical AND, OR,
           and NOT operations on searches with the ^, >,  >>,  and  <
           commands.   For  example,  if you wanted all references to
           the symbol stderr in file invlib.c, search for the  symbol
           and then use the ^ command with shell command

                  grep invlib.c

           If you wanted all the references not in this file, use the
           grep(1) -v option.  If you wanted all the lines where sym-
           bols  stderr or stdout are used, search for the first sym-
           bol, write the references to a file with  the  >  command,
           search for the second symbol, append the references to the
           same file with the >> command, read the file  with  the  <
           command, and get rid of duplicate lines with the ^ command
           using the shell command

                  sort | uniq

           Note that all <global> references will no longer be  first
           because the references will be sorted by file name.

       Viewpath
           As  described  above,  cscope searches for source files in
           the current directory by default.  When the VPATH environ-
           ment  variable is set, cscope searches for source files in
           directories that comprise your viewpath.  A viewpath is an
           ordered  list  of  directories, each of which has the same
           directory structure below it.

           For example, suppose you are part of a  software  project.
           There  is  an  official set of source files in directories
           below /fs1/ofc and each user has some matching directories
           under  their  home directory ($HOME).  If you make changes
           to the software system, you may have copies of just  those
           files  you are changing in $HOME/src/cmd/prog1.  The offi-
           cial versions of  the  entire  program  can  be  found  in
           /fs1/ofc/src/cmd/prog1.

           Suppose  you  use cscope to browse through the three files
           that comprise prog1, namely f1.c,  f2.c,  and  f3.c.   You
           would set VPATH to $HOME and /fs1/ofc, and export it:

                  VPATH=$HOME:/fs1/ofc
                  export VPATH

           You    would    then    make    your   current   directory
           $HOME/src/cmd/prog1 and invoke cscope:

                  cd $HOME/src/cmd/prog1
                  cscope

           Cscope will locate all files in  the  viewpath.   In  case
           duplicates  are  found,  cscope uses the file whose parent
           directory appears earlier in VPATH.  Thus if  f2.c  is  in
           your  directory  (and  all three files are in the official
           directory), cscope will use f2.c from your  directory  and
           f1.c and f3.c from the official directory.

           The  first  directory  in  VPATH must be a prefix (usually
           $HOME) of the directory you  will  be  working  in.   Each
           colon-separated  directory  in  VPATH must be a full path,
           that is, it must start with a slash (/).

       Calling Cscope with a Line-Oriented Interface
           The -l option lets you use cscope where a  screen-oriented
           interface  would  not be useful, e.g. from another screen-
           oriented program.  Cscope will prompt with ">> "  when  it
           is  ready for an input line starting with the field number
           (counting from 0) immediately followed by the search  pat-
           tern,  e.g. "1main" finds the definition of the main func-
           tion.  Field number 9 followed by any pattern, e.g.  "9a",
           finds all function and C++ class definitions.  If you just
           want a single search, instead of the -l option use the  -L
           and  -n  pattern  options,  and  you  won't  get the ">> "
           prompt.  For -l, cscope outputs the  number  of  reference
           lines

                  cscope: 2 lines

           For each reference found, cscope outputs a line consisting
           of the file name, function name,  line  number,  and  line
           text, separated by spaces, e.g.

                  main.c main 161 main(argc, argv)

           Note that as of this time, the file name, and the function
           name must not have embedded spaces (such as  what  happens
           on Microsoft boxes).

           Also  note that the editor is not called to display a sin-
           gle reference, unlike the screen-oriented interface.   You
           can  use  the  'c' command to toggle ignoring/using letter
           case when  searching,  the  'r'  command  to  rebuild  the
           database,  and  the 'P' command to print the path to rela-
           tive file names (either the -P option  path  or  the  full
           current directory path).  Cscope will quit when it detects
           end-of-file, or when the first character of an input  line
           is ^D or 'q'.

           This  option  allows you to write a program like samuel(1)
           that uses cscope to look up symbol information.  The  pro-
           gram  can  send  search  commands  to  cscope and read the
           results.  The xcscope macro package available for emacs(1)
           uses  this  option  to look up C symbols.  This option may
           also be useful for terminals not supported by  terminfo(4)
           or for sight-impaired users of printing terminals.

           The  following table lists the commands available in line-
           oriented mode (-l). If a string is specified,  there  must
           be  no  whitespace  between  the  command  letter  and the
           string. The string is shown here as '<str>' for  readabil-
           ity but the '<>' chars are not used.

           +----------------------------------------------------------+
           | CMD                          ACTION                      |
           +----------------------------------------------------------+
           |0<str>   Find this C symbol:                              |
           |1<str>   Find this definition:                            |
           |2<str>   Find functions called by this function:          |
           |3<str>   Find functions calling this function:            |
           |4<str>   Find assignments to:                             |
           |5<str>   Change this grep pattern:                        |
           |6<str>   Find this egrep pattern:                         |
           |7<str>   Find this file:                                  |
           |8<str>   Find files #including this file:                 |
           +----------------------------------------------------------+
           |9<str>   Find all function/class definitions (samuel)     |
           |:<str>   Find all function/class definitions (cdb)        |
           +----------------------------------------------------------+
           |a<str>   Set  the directory search pattern for 'Find this |
           |         egrep pattern'.  This is the equivalent  of  the |
           |         command line option of -a                        |
           |^<str>   Set the directory filter pattern for all queries |
           |c        Toggle Caseless mode                             |
           |C        Clear file names                                 |
           |F        Add file name                                    |
           |P        Print the path to the files                      |
           |r        rebuild the database cscope style                |
           |R        rebuild the database samuel style                |
           +----------------------------------------------------------+
           |q        Quit                                             |
           +----------------------------------------------------------+
           |         (used by ccalls with the extended menu)          |
           |0<str>   Find this type definition:                       |
           |1<str>   Find this preprocessor definition:               |
           |2<str>   Find parameters of this function:                |
           |3<str>   Find functions calling this function:            |
           |4<str>   Find this global definition:                     |
           |5<str>   Find this local definition:                      |
           |6<str>   Find this structure definition:                  |
           |7<str>   Find this file:                                  |
           |8<str>   Find this preprocessor include:                  |
           |9<str>   Find definition of this function:                |
           |:<str>   Find all function/class definitions:             |
           +----------------------------------------------------------+
           If you wanted to "Find assignments to", then you would use
           "-4pattern"

           The -c, -k, -I, -p, -q, and -T options can also be in  the
           cscope.files  file.   See below for common uses of most of
           these options.

## SYMBOL DATABASE FORMAT

           The symbol database (cscope.out) file format is

                  <header>
                  <first file symbol data>
                         ...
                  <last file symbol data>
                  <trailer>

           The header is a single line

                  cscope <format version> <current dir> [-c] [-q <symbols>] [-T] <trailer offset>

           The format version is first number in the  cscope  version
           that  wrote the database, e.g. the format version is 9 for
           cscope version 9.14.  When the format  version  number  in
           the  cscope  program is greater than that in the database,
           the entire database will be rebuilt when any part of it is
           out  of date.  The current directory is either a full path
           or prefixed by $HOME, allowing  the  user's  login  to  be
           moved  to  a  different file system without rebuilding the
           database.  The trailer offset is the  fseek(3)  offset  of
           the trailer.

           The header is followed by the symbol data for each file in
           alphabetical order.  This  allows  fast  updating  of  the
           database  when  only a few files have changed, because the
           old database is copied to the new database up to the point
           of  the changed file.  Then the changed file's symbol data
           is added to the new database, the old database  is  copied
           up to the next changed file, and so on.

           Two  data  compression  techniques  are used on the symbol
           data: (1) keywords and trailing syntax  are  converted  to
           control  characters,  and  (2)  common digraphs (character
           pairs) are compressed to meta-characters (characters  with
           the  eight  bit set).  Since this makes it hard to read or
           postprocess the database, you  may  want  to  use  the  -c
           option  to  turn off data compression when the database is
           built.

           The symbol data for each file starts with

                  <file mark><file path>
                  <empty line>

           and for each source line containing a symbol

                  <line number><blank><non-symbol text>
                  <optional mark><symbol>
                  <non-symbol text>
                  repeat above 2 lines as necessary
                  <empty line>

           Leading and trailing white space in  the  source  line  is
           removed.   Tabs are changed to blanks, and multiple blanks
           are squeezed to a single  blank,  even  in  character  and
           string  constants.  The symbol data for the last file ends
           with

                  <file mark>

           A mark is a tab followed by one of these characters:

                  Char   Meaning

                  @      file
                  $      function definition
                  `      function call
                  }      function end
                  #      #define
                  )      #define end
                  ~      #include
                  =      direct assignment, increment, or decrement
                  ;      enum/struct/union definition end
                  c      class definition
                  e      enum definition
                  g      other global definition
                  l      function/block local definition
                  m      global enum/struct/union member definition
                  p      function parameter definition
                  s      struct definition
                  t      typedef definition
                  u      union definition

           A #include mark is followed by '<' or '"' to determine  if
           the  current  directory  should  be searched.  An untagged
           enum/struct/union definition has a mark without  a  symbol
           name so its beginning can be found.

           Historical note: The first three mark characters were cho-
           sen because they are not used by the C language, but since
           they  can  appear in a string constant, the tab prefix was
           added.  They were never changed to more meaningful charac-
           ters  because  other programs had been written to read the
           database file.

           The trailer contains lists of source directories,  include
           directories, and source files; its format is

                  <number of viewpath nodes>
                  <first directory in viewpath, if any>
                         ...
                  <last directory in viewpath>
                  <number of source directories>
                  <first source directory path (always .)>
                         ...
                  <last source directory path>
                  <number of include directories>
                  <first include directory path>
                         ...

                  <last include directory path (normally /usr/include)>
                  <number of source and included files>
                  <length of string space needed>
                  <first file path>
                         ...
                  <last file path>

           Low  level access to the symbol database was traditionally
           provided by ccalls.  Cscope now emulates this  functional-
           ity  with the -x option so that everyone can get access to
           the extra information stored in the database.  One of  the
           main  differences  in  the  output is that a new column is
           added, entitled "Ccalls", which contains the  symbol  name
           from  the  database.  This information was previously only
           extracted as part of the  code  fragment  associated  with
           each  set of results.  As such, the new output format when
           using the -x option consists of the  file  name,  function
           name, line number, ccalls information and line text, sepa-
           rated by spaces.

## ENVIRONMENT VARIABLES

           CSCOPEOPTIONS
                        Cscope options.
           EDITOR       Your editor, which defaults to vi(1).
           HOME         Your home directory, which  is  automatically
                        set when you login.
           MOUSE        Set to myx if that is your 5620 terminal pro-
                        gram.
           MOUSEMENU    Set to none if you  do  not  want  cscope  to
                        switch to its mouse menu so you can have your
                        own customized Cscope submenu  on  the  shell
                        menu.
           SHELL        Your shell, which defaults to sh(1).
           TERM         Your  terminal  type,  which must be a screen
                        terminal.
           TERMINFO     Terminal  information  directory  full   path
                        name.   If  your terminal is not in the stan-
                        dard terminfo directory, see  curses(3X)  and
                        terminfo(4) for how to make your own terminal
                        description.
           TMPDIR       Temporary file directory, which  defaults  to
                        /usr/tmp.
           VIEWER       Your  file  display  program, which overrides
                        EDITOR (see above).
           VPATH        Viewpath (see Viewpath subsection of EXAMPLES
                        section).

           To set a variable such as EDITOR to a value such as emacs,
           put this in your .profile:

                  export EDITOR
                  EDITOR=emacs

## FILES

           cscope.files  Default file containing -c, -k, -I, -p,  -q,
                         and  -T options and the list of source files
                         (overridden by the -i option).
           cscope.out    Default symbol database file (overridden  by
                         the  -f  option).   It  is  put in your home
                         directory if it cannot  be  created  in  the
                         current directory.
           cscope.in.out
           cscope.po.out Default  files containing the inverted index
                         for quick symbol searching (-q option).   If
                         you   use   the  -f  option  to  rename  the
                         cscope.out file name, .in and  .po  will  be
                         suffixed  to  its  base name to create these
                         file names.
           ncscope*.out  Temporary files containing the new  database
                         before it replaces the old database.  If you
                         use the -f option to rename  the  cscope.out
                         file name, an n will be prefixed to its base
                         name to create these file names.
           /usr/include  Standard directory for #include files.

## SEE ALSO

           cscalls(1), grep(1), regcmp(3X),  slimmer(1)

## WARNINGS

           Spaces in the displayed source line text for  a  reference
           may  not  exactly  match the actual source line because of
           the data compression used to store them in  the  database.
           Leading   spaces  and  tab  characters  are  removed,  and
           sequences of them are replaced with a single  space,  even
           inside a quoted string.  A space may also be added after a
           keyword, e.g. "(void)" will be displayed as "(void )".

           The Function column of the search  output  for  the  "Find
           functions  called by this function:" input field will only
           display the first function called in the  line,  that  is,
           for this function

                  e()
                  {
                         return(f() + g());
                  }

           the display would be

                  Functions called by this function: e

                    File Function Line
                    a.c  f        3 return(f() + g());

## BUGS

       C Parsing Bugs
           Occasionally,  a  function  definition  or call may not be
           recognized because of braces inside #if statements.  Simi-
           larly, the use of a variable may be incorrectly recognized
           as a definition.

           A typedef name preceding a preprocessor statement will  be
           incorrectly recognized as a global definition, e.g.

                  LDFILE *
                  #if AR16WR

           Preprocessor  statements  can also prevent the recognition
           of a global definition, e.g.

                  char flag
                  #ifdef ALLOCATE_STORAGE
                         = -1
                  #endif
                  ;

           A function definition will not be recognized  if  the  '('
           after the function name is on the next line, e.g.

                  f
                  ()
                  {

       C++ Parsing Bugs
           Cscope  recognizes  C++  classes  by looking for the class
           keyword, but doesn't recognize that a  struct  is  also  a
           class, so it doesn't recognize inline member function def-
           initions in a structure.  It also doesn't expect the class
           keyword  in a typedef, so it incorrectly recognizes X as a
           definition in

                  typedef class X * Y;

           It also doesn't recognize operator function definitions

                  Bool Feature::operator==(const Feature & other) {

           and function definitions with a function pointer argument

                  ParseTable::Recognizes(int startState, char *pattern,
                         int finishState, void (*FinalAction)(char *)) {

## AUTHOR

           Joe Steffen