'cscope manpage'에 해당되는 글 1건

  1. 2014.09.07 cscope manpage

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


Man(1) output converted with man2html
신고
Posted by code cat

티스토리 툴바