


CTAGS(1)                                                 CTAGS(1)


NAME
       ctags - Generate tag files for source code



SYNOPSIS
       ctags [options] [file(s)]

       etags [options] [file(s)]



DESCRIPTION
       The  ctags  and  etags  programs (hereinafter collectively
       referred to as ctags, except where distinguished) generate
       an  index (or "tag") file for C, C++, Eiffel, Fortran, and
       Java language objects found in  file(s).   This  tag  file
       allows  these  items to be quickly and easily located by a
       text editor or other utility. A "tag" signifies a language
       object for which an index entry is available (or, alterna-
       tively, the index entry created for that object).


       Alternatively, ctags can generate a cross  reference  file
       which lists, in human readable form, information about the
       various source objects found in a set of language files.


       Tag index files are supported by numerous  editors,  which
       allow the user to locate the object associated with a name
       appearing in a source file and jump to the file  and  line
       which  defines  the name. Those known about at the time of
       release are:


           vi(1) and its many derivatives
           emacs
           CRiSP
           FTE (Folding Text Editor)
           Lemmy
           NEdit
           TSE (The SemWare Editor)
           Zeus


       ctags is capable of generating tags for all of the follow-
       ing language constructs:


           C/C++:
               macros (names defined/undefined by #define/#undef)
               enumerators (enumerated values)
               function definitions, prototypes, and declarations
               class, enum, struct, and union names



Darren Hiebert            Version 3.2.4                         1





CTAGS(1)                                                 CTAGS(1)


               namespaces
               typedefs
               variables (definitions and declarations)
               class, struct, and union members

           Eiffel:
               classes
               features
               local entities

           Fortran:
               block data
               common blocks
               entry points
               functions
               interfaces
               labels
               modules
               namelists
               programs
               subroutines
               derived types

           Java:
               classes
               fields
               interfaces
               methods
               packages



SOURCE FILES
       The language of each source file is automatically selected
       based upon its file extension (unless the --lang option is
       specified). File extensions are mapped to source file lan-
       guages according to the following default mapping  (unless
       the --langmap option is specified):


           C        *.c
           C++      *.C *.c++ *.cc *.cpp *.cxx *.h *.H *.hh *.hpp
                    *.hxx *.h++
           Eiffel   *.e
           Fortran  *.f *.for *.ftn *.f77 *.f90 *.F  *.FOR  *.FTN
                    *.F77 *.F90
           Java     *.java


       By  default,  all other files extensions are ignored. This
       permits running ctags on all  files  in  either  a  single
       directory  (e.g.  "ctags  *"),  or  all files in an entire
       source directory tree (e.g. "ctags -R"), since only  those
       files whose extensions are known to ctags will be scanned.



Darren Hiebert            Version 3.2.4                         2





CTAGS(1)                                                 CTAGS(1)


       The reason that .h extensions  are  mapped  to  C++  files
       rather  than C files is because no information is lost and
       because it is common to use .h extensions  in  C++,  where
       information  would  be lost if .h files were parsed with C
       rules.



OPTIONS
       Despite the wealth of available options, defaults are  set
       so  that  ctags  is  most  commonly  executed  without any
       options (e.g. "ctags *"), which will create a tag file  in
       the  current  directory  for  all  known source files. The
       options described below are provided merely to allow  cus-
       tom tailoring to meet special needs.


       Note that spaces separating the single-letter options from
       their parameters are optional.


       Note also that the boolean parameters  to  the  long  form
       options  (those  beginning  with  "--"  and  that  take  a
       "=yes|no" parameter) may be omitted, in which case  "=yes"
       is  implied.  (e.g.  --sort  is equivalent to --sort=yes).
       Note further that "=1" and "=on" are  considered  synonyms
       for  "=yes",  and that "=0" and "=off" are considered syn-
       onyms for "=no".

       Some options are either ignored, or only useful, when used
       together  with  etags  or, equivalently, when ctags is run
       with the -e option. These options will be noted.


       -a   Append the tags to an existing tag  file.  Equivalent
            to --append.  [Ignored with -e]


       -B   Use  backward  searching  patterns  (e.g.  ?regexp?).
            [Ignored with -e]


       -e   Output a tag file for use with Emacs. If this program
            is executed by the name etags, this option is enabled
            by default.


       -f tagfile
            Use the name specified by tagfile for  the  tag  file
            (default  is  "tags",  or  "TAGS"  when  using the -e
            option). If tagfile is specified as "-", then the tag
            file  is  written  to  standard output instead. Ctags
            will stubbornly refuse  to  take  orders  if  tagfile
            exists  and  its  first line contains something other



Darren Hiebert            Version 3.2.4                         3





CTAGS(1)                                                 CTAGS(1)


            than a valid tags line. This will save your  neck  if
            you  mistakenly type "ctags -f *.c", which would oth-
            erwise overwrite your first C file with the tags gen-
            erated by the rest!


       -F   Use   forward   searching  patterns  (e.g.  /regexp/)
            (default).  [Ignored with -e]


       -h list
            Specifies a list of  file  extensions,  separated  by
            periods,  which  are to be interpreted as include, or
            header, files. This option affects how the scoping of
            tag  types  is  interpreted (i.e. whether or not they
            are considered as globally visible  or  visible  only
            within  the file in which they are defined).  Any tag
            type which is located in a non-include file and  can-
            not  be  seen  (e.g.  linked to) from another file is
            considered to have file-limited (e.g. static)  scope.
            No tag type appearing in an include file will be con-
            sidered to have  file-limited  scope.  If  the  first
            character in the list is a plus sign, then the exten-
            sions in the list will be  appended  to  the  current
            list;  otherwise,  the  list will replace the current
            list. See also the --file-scope option.  The  default
            list is ".h.H.hh.hpp.hxx.h++.inc.def".


       -i types
            This option is similar to the --c-types option and is
            retained for compatibility with earlier versions.  If
            types begins with the '=' character, it is equivalent
            to --c-types=types. Otherwise, it  is  equivalent  to
            --c-types=+types.  In addition, for backward compati-
            bility, the following two  additional  modifiers  are
            accepted:


               F   An alternative for the --file-tags option.
               S   An alternative for the --file-scope option.


       -I tokenlist
            Specifies  a list of tokens which are to be specially
            handled while parsing C and C++  source  files.  This
            option  is  specifically  provided  to handle special
            cases arising through the use of preprocessor macros.
            When  the  tokens  listed  are  simple  tokens, these
            tokens will be ignored during parsing of  the  source
            files.  If  a token is suffixed with a '+' character,
            ctags will also ignore any parenthesis-enclosed argu-
            ment  list  which may immediately follow the token in
            the source files. If two tokens  are  separated  with



Darren Hiebert            Version 3.2.4                         4





CTAGS(1)                                                 CTAGS(1)


            the '=' character, the first token is replaced by the
            second token for parsing purposes. The list of tokens
            may  be supplied directly on the command line or read
            in from a separate file. If the  first  character  of
            tokenlist  is  either  a  '.' or a pathname separator
            ('/' or '\'), the parameter tokenlist will be  inter-
            preted  as  a  filename  from which to read a list of
            white-space delimited  tokens  (use  "./filename"  to
            specify a file found in the current directory).  Oth-
            erwise, tokenlist is  a  list  of  tokens  (or  token
            pairs)  to  be specially handled, each delimited by a
            either a comma or by white space (in which  case  the
            list  should be quoted to keep the entire list as one
            command line argument). Multiple -I  options  may  be
            supplied.


            This  feature  is useful when preprocessor macros are
            used in such a way that they cause  syntactic  confu-
            sion  due to their presence. Indeed, this is the best
            way of working around a number of problems caused  by
            the presence of syntax-busting macros in source files
            (see BUGS, below). Some examples will illustrate this
            point.


               int foo ARGDECL4(void *, ptr, long int, nbytes)


            In  the  above example, the macro "ARGDECL2" would be
            mistakenly interpreted to be the name of the function
            instead  of  the correct name of "foo". Specifying -I
            ARGDECL2 results in the correct behavior.


               /* creates an RCS version string in module */
               MODULE_VERSION("$Revision: 8.4 $")


            In the above example the macro invocation  looks  too
            much  like  a  function  definition because it is not
            followed by a semicolon (indeed,  it  could  even  be
            followed  by  a global variable definition that would
            look much like a K&R style function parameter  decla-
            ration).  In  fact,  this seeming function definition
            could possibly even cause the rest of the file to  be
            skipped over while trying to complete the definition.
            Specifying -I  MODULE_VERSION+  would  avoid  such  a
            problem.


               CLASS Example {
                   // your content here
               };



Darren Hiebert            Version 3.2.4                         5





CTAGS(1)                                                 CTAGS(1)


            The  example  above  uses  "CLASS"  as a preprocessor
            macro which expands to something different  for  each
            platform. For instance CLASS may be defined as "class
            __declspec(ddlexport)" on Win32 platforms and  simply
            "class"  on  UNIX.   Normally, the absence of the C++
            keyword "class" would cause the  source  file  to  be
            incorrectly  parsed. Correct behavior can be restored
            by specifying -I CLASS=class.


       -L file
            Read from file a list of file names  for  which  tags
            should  be  generated.   If file is specified as "-",
            then file names are read from standard input.


       -n   Equivalent to --excmd=number.


       -N   Equivalent to --excmd=pattern.


       -o tagfile
            Equivalent to -f tagfile.


       -p path
            Use path as the default directory for  each  supplied
            source  file (whether supplied on the command line or
            in a file specified with the -L option),  unless  the
            source file is already specified as an absolute path.
            The supplied path is merely  prepended  to  the  each
            non-absolute  source  file name, adding any necessary
            path separator.


       -R   Equivalent to --recurse=yes.


       -u   Equivalent to --sort=no (i.e. "unsorted").


       -V   Enable verbose mode. This prints out a brief  message
            describing  what  action is being taken for each file
            considered by ctags.


       -x   Print  a  tabular,  human-readable  cross   reference
            (xref)  file to standard output instead of generating
            a tag file. The information contained in  the  output
            includes:  the  tag  name;  the kind of tag; the line
            number, file name, and source line (with extra  white
            space  condensed)  of the file which defines the tag.
            No tag file is written and all options affecting  tag



Darren Hiebert            Version 3.2.4                         6





CTAGS(1)                                                 CTAGS(1)


            file output will be ignored. Example applications for
            this feature are generating a listing  of  all  func-
            tions  located  in  a source file (e.g. ctags -x --c-
            types=f file), or generating a list of all externally
            visible  global  variables  located  in a source file
            (e.g. ctags -x --c-types=v --file-scope=no file).


       --append=yes|no
            Indicates whether tags generated from  the  specified
            files  should be appended to those already present in
            the tag file or should replace them. This  option  is
            off by default.


       --c-types=types
            Specifies  a  list  of  C/C++  language  tag types to
            include in the output file.  The parameter types is a
            group  of  one-letter flags designating types of tags
            (listed below) to either include or exclude from  the
            output.  Each  letter or group of letters may be pre-
            ceded by either '+' (default, if omitted) to  add  it
            to  the  default  set,  or  '-' to exclude it. In the
            absence of any preceding included in the output.  For
            example,  to  exclude  macros but include prototypes,
            use --c-types=-m+p; to include only  tags  for  func-
            tions,  use  --c-types=f. Tags for the following lan-
            guage constructs are supported (types are enabled  by
            default except as noted):


               c   classes
               d   macro definitions (and #undef names)
               e   enumerators
               f   function definitions
               g   enumeration names
               m   class, struct, or union members
               n   namespaces
               p   function prototypes and declarations [off]
               s   structure names
               t   typedefs
               u   union names
               v   variable definitions
               x   extern and forward variable declarations [off]


            In addition to the above flags,  the  following  one-
            letter modifiers are accepted:


               A   Record  the access of each member into the tag
                   file. This information is  recorded  using  an
                   extension flag labeled "access".
               C   Include  an  extra,  class-qualified tag entry



Darren Hiebert            Version 3.2.4                         7





CTAGS(1)                                                 CTAGS(1)


                   for each class member in the form "class::mem-
                   ber".  This  allows  locating  class-qualified
                   tags (e.g.  ":tag  class::member"  in  vi(1)).
                   This is disabled by default because this could
                   potentially more than double the size  of  the
                   tag file.




       --eiffel-types=types
            Specifies  a  list of Eiffel language tag types to be
            included in the output.  See --c-types for the  defi-
            nition of the format of types. Tags for the following
            Eiffel language constructs are supported  (types  are
            enabled by default except as noted):


               c   classes
               f   features
               l   local entities [off]


       --etags-include=file
            Include  a  reference  to  file in the tag file. This
            option may be specified as  many  times  as  desired.
            This  supports  Emacs'  capability  to use a tag file
            which "includes" other tag files. [Used only with -e]


       --excmd=type
            Determines the type of EX command used to locate tags
            in the source file.  [Ignored with -e]


            The valid values for type (either the entire word  or
            the first letter is accepted) are:

            number   Use  only  line  numbers in the tag file for
                     locating tags. This has four advantages:
                     1.  Significantly reduces the  size  of  the
                         resulting tag file.
                     2.  Eliminates failures to find tags because
                         the line defining the tag  has  changed,
                         causing  the pattern match to fail (note
                         that some editors, such as vim, are able
                         to recover in many such instances).
                     3.  Eliminates  finding  identical matching,
                         but incorrect, source lines  (see  BUGS,
                         below).
                     4.  Retains separate entries in the tag file
                         for lines which are  identical  in  con-
                         tent. In pattern mode, duplicate entries
                         are dropped because the search  patterns



Darren Hiebert            Version 3.2.4                         8





CTAGS(1)                                                 CTAGS(1)


                         they  generate are identical, making the
                         duplicate entries useless.

                     However, this  option  has  one  significant
                     drawback:  changes  to  the source files can
                     cause the line numbers recorded in  the  tag
                     file to no longer correspond to the lines in
                     the source file, causing jumps to some  tags
                     to miss the target definition by one or more
                     lines. Basically, this option is  best  used
                     when  the source code to which it is applied
                     is not subject  to  change.  Selecting  this
                     option  type causes the following options to
                     be ignored: -BF.


            pattern  Use  only  search  patterns  for  all  tags,
                     rather  than  the  line numbers usually used
                     for macro definitions. This has  the  advan-
                     tage  of  not referencing obsolete line num-
                     bers when lines have been added  or  removed
                     since the tag file was generated.


            mixed    In  this  mode,  patterns are generally used
                     with a few exceptions. For C,  line  numbers
                     are used for macro definition tags. This was
                     the default format generated by the original
                     ctags  and  is,  therefore,  retained as the
                     default for this option. For  Fortran,  line
                     numbers  are  used for common blocks because
                     their corresponding source lines are  gener-
                     ally identical, making pattern searches use-
                     less for finding all matches.


       --file-scope=yes|no
            Indicates whether tags scoped only for a single  file
            (i.e.  tags  which cannot be seen outside of the file
            in which they are defined,  such  as  "static"  tags)
            should  be  included  in  the output. See also the -h
            option. This option is enabled by default.


       --file-tags=yes|no
            Indicates whether tags should be generated for source
            file names. This option is disabled by default.


       --format=level
            Change  the  format of the output tag file. Currently
            the only valid values for level are 1 or 2.  Level  1
            specifies  the  original  tag file format and level 2
            specifies a new extended format containing  extension



Darren Hiebert            Version 3.2.4                         9





CTAGS(1)                                                 CTAGS(1)


            flags (but in a manner which retains backward compat-
            ibility with  original  vi(1)  implementations).  The
            default level is 2.  [Ignored with -e]


       --fortran-types=types
            Specifies  a list of Fortran language tag types to be
            included in the output.  See --c-types for the  defi-
            nition of the format of types. Tags for the following
            Fortran language constructs are supported (types  are
            enabled by default except as noted):


               b   block data
               c   common blocks
               e   entry points
               f   functions
               i   interfaces
               l   labels [off]
               m   modules
               n   namelists
               p   programs
               s   subroutines
               t   derived types


       --help
            Prints  to  standard output a detailed usage descrip-
            tion.


       --if0=yes|no
            Indicates a preference as to whether code  within  an
            "#if  0"  branch of a preprocessor conditional should
            be examined for non-macro tags (macro tags are always
            included). Because the intent of this construct is to
            disable code, the default value of  this  options  is
            no.  Note  that  this indicates a preference only and
            does not guarantee skipping code within  an  "#if  0"
            branch,  since the fall-back algorithm used to gener-
            ate tags when preprocessor conditionals are too  com-
            plex  follows  all  branches  of  a conditional. This
            option is disabled by default.


       --java-types=types
            Specifies a list of Java language  tag  types  to  be
            included  in the output.  See --c-types for the defi-
            nition of the format of types. Tags for the following
            Java  language  constructs  are  supported  (all  are
            enabled by default):


               c   classes



Darren Hiebert            Version 3.2.4                        10





CTAGS(1)                                                 CTAGS(1)


               f   fields
               i   interfaces
               m   methods
               p   packages


            In addition to the above flags,  the  following  one-
            letter modifiers are accepted:


               A   Record  the  access of each field into the tag
                   file. This information is  recorded  using  an
                   extension flag labeled "access".
               C   Include  an  extra,  class-qualified tag entry
                   for each class member in the form  "class.mem-
                   ber".  This  allows  locating  class-qualified
                   tags (e.g. ":tag class.member" in vi(1)). This
                   is  disabled  by  default  because  this could
                   potentially more than double the size  of  the
                   tag file.




       --kind-long=yes|no
            Specifies  whether the identifier for the kind of the
            tag listed in extension flags of the tag  file  is  a
            verbose  name or a single letter. See the description
            of kind in EXTENSION FLAGS, below. When enabled, this
            will increase the size of the output by an average of
            about 5 characters per line or, roughly, 5%.


       --lang=c|c++|eiffel|fortran|java
            By default, ctags automatically selects the  language
            of  a  source  file according to its file name exten-
            sion,  ignoring  those  files  whose  extensions  are
            unrecognized  by ctags. This option forces the speci-
            fied language to be  used  for  every  supplied  file
            instead of automatically selecting the language based
            upon its extension.


       --langmap=map(s)
            Changes  the  mapping  between  file  extensions  and
            source  languages  (see  SOURCE  FILES,  above). Each
            comma-separated map consists of the  source  language
            name,  a colon, and a list of extensions separated by
            periods.  If the first character in a map is  a  plus
            sign, then the extensions in the map will be appended
            to the current map; otherwise, the map  will  replace
            the  current  map.For  example,  to specify that only
            files with extensions of .c, .ec, and .xs are  to  be
            treated      as     C     language     files,     use



Darren Hiebert            Version 3.2.4                        11





CTAGS(1)                                                 CTAGS(1)


            "--langmap=c:.c.ec.xs". To also  specify  that  files
            with  extensions of .j are to be treated as Java lan-
            guage files, use "--langmap=c:.c.ec.xs,java:+.j".


       --line-directives=yes|no
            Specifies whether "#line" directives should be recog-
            nized.  These are present in the output of preproces-
            sors and contain the line number,  and  possibly  the
            file  name, of the original source file(s) from which
            the preprocessor  output  file  was  generated.  When
            enabled, this option will cause ctags to generate tag
            entries marked with the file names and  line  numbers
            of  their  locations original source file(s), instead
            of their actual locations in the preprocessor output.
            The  actual  file names placed into the tag file will
            have the same leading path components as the  prepro-
            cessor  output  file,  since  it  is assumed that the
            original source files are  located  relative  to  the
            preprocessor  output  file  (unless,  of  course, the
            #line directive specifies  an  absolute  path).  This
            option is off by default. Note: This option is gener-
            ally  only  useful  when  used  together   with   the
            --excmd=number (-n) option. Also, you may have to use
            either the --lang or --langmap option if  the  exten-
            sion  of the preprocessor output file is not known to
            ctags.


       --links=yes|no
            Indicates  whether  symbolic  links  (if  suppported)
            should be followed. When disabled, symbolic links are
            ignored. This option is on by default.


       --recurse=yes|no
            Recurse into directories encountered in the  list  of
            supplied  files.  If  the  list  of supplied files is
            empty and no file  list  is  specified  with  the  -L
            option,  then  the  current  directory  (i.e. ".") is
            assumed.  On  Unix,  directories  named  "SCCS"   are
            skipped,  because  files in these directories are not
            source code, even though they have the same names  as
            the  source  code  to  which they relate. Directories
            named "EIFGEN" are  skipped,  because  these  contain
            Eiffel compiler-generated C files. Also on Unix, sym-
            bolic links are followed. If  you  don't  like  these
            behaviors,  either  explicitly  specify  the files or
            pipe the output of find(1) into  ctags  -L-  instead.
            Note:  This  option is not supported on all platforms
            at present.






Darren Hiebert            Version 3.2.4                        12





CTAGS(1)                                                 CTAGS(1)


       --sort=yes|no
            Indicates whether the tag file should  be  sorted  on
            the tag name (default is yes). Note that the original
            vi(1) requires sorted tags.  This  option  is  on  by
            default. [Ignored with -e]


       --totals=yes|no
            Prints statistics about the source files read and the
            tag file written during  the  current  invocation  of
            ctags. This option is off by default.


       --version
            Prints  a  version  identifier  for ctags to standard
            output. This is  guaranteed  to  always  contain  the
            string "Exuberant Ctags".



OPERATIONAL DETAILS
       For  every  one of the qualified objects which are discov-
       ered in the source files supplied  to  ctags,  a  separate
       line  is  added to the tag file, each looking like this in
       the most general case:


           tag_name    file_name    ex_cmd;"    xflags


       The fields and separators of these lines are specified  as
       follows:


           1.  tag name (a C language identifier)
           2.  a single tab character
           3.  the  name  of the file in which the object associ-
               ated with the tag is located
           4.  a single tab character
           5.  an EX command to locate the tag within  the  file;
               generally  a  search  pattern (either /pattern/ or
               ?pattern?) or line number (see --excmd). Tag  file
               format  2  (see  --format) extends this EX command
               under certain circumstances to include  a  set  of
               extension   flags  (see  EXTENSION  FLAGS,  below)
               embedded in an EX comment immediately appended  to
               the EX command, which leaves it backwards compati-
               ble with original vi(1) implementations.


       A few special tags are  written  into  the  tag  file  for
       internal  purposes.  These tags are composed in such a way
       that they always sort to the top of the file.   Therefore,
       the  first  two  characters of these tags are used a magic



Darren Hiebert            Version 3.2.4                        13





CTAGS(1)                                                 CTAGS(1)


       number to detect a tag file for  purposes  of  determining
       whether  a valid tag file is being overwritten rather than
       a source file.


       When this program is invoked by the name  etags,  or  with
       the  -e  option,  the output file is in a different format
       that is used by emacs(1).


       Note that the name of each source file will be recorded in
       the  tag  file  exactly as it appears on the command line.
       Therefore, if the path you specified on the  command  line
       was  relative  to some directory, then it will be recorded
       in that same manner in the tag file.


       This version of ctags imposes no formatting  requirements.
       Other  versions  of ctags tended to rely upon certain for-
       matting assumptions in order to  help  it  resolve  coding
       dilemmas caused by preprocessor conditionals.


       In general, ctags tries to be smart about conditional pre-
       processor directives. If  a  preprocessor  conditional  is
       encountered  within a statement which defines a tag, ctags
       follows only the first branch of that conditional  (except
       in  the  special case of "#if 0", in which case it follows
       only the last branch). The reason for this is that failing
       to  pursue only one branch can result in ambiguous syntax,
       as in the following example:


              #ifdef TWO_ALTERNATIVES
              struct {
              #else
              union {
              #endif
                  short a;
                  long b;
              }


       Both branches cannot be followed, or braces become  unbal-
       anced  and ctags would be unable to make sense of the syn-
       tax.


       If the application of this  heuristic  fails  to  properly
       parse  a  file, generally due to complicated and inconsis-
       tent pairing within the conditionals, ctags will retry the
       file  using  a  different  heuristic which does not selec-
       tively  follow  conditional  preprocessor  branches,   but
       instead  falls  back to relying upon a closing brace ("}")



Darren Hiebert            Version 3.2.4                        14





CTAGS(1)                                                 CTAGS(1)


       in column 1 as indicating the end  of  a  block  once  any
       brace  imbalance  results from following a #if conditional
       branch.


       Ctags will also try to specially  handle  arguments  lists
       enclosed  in double sets of parentheses in order to accept
       the following conditional construct:


              extern void foo __ARGS((int one, char two));


       Any name immediately preceding the "((" will be  automati-
       cally ignored and the previous name will be used.


       C++  operator  definitions are specially handled. In order
       for consistency with all types  of  operators  (overloaded
       and  conversion),  the  operator name in the tag file will
       always be preceded by the string "operator " (i.e. even if
       the  actual  operator  definition  was  written as "opera-
       tor<<").


       After creating or appending to the tag file, it is  sorted
       by the tag name, removing identical tag lines.


       Note  that the path recorded for filenames in the tag file
       and utilized by the editor to search for tags are  identi-
       cal  to  the  paths  specified  for file(s) on the command
       line. This means the if you want the paths for files to be
       relative to some directory, you must invoke ctags with the
       same pathnames for file(s) (this can  be  overridden  with
       -p).



EXTENSION FLAGS
       Extension flags are tab-separated key-value pairs appended
       to the end of the EX command as a  comment,  as  described
       above  in  OPERATIONAL  DETAILS.   These  key  value pairs
       appear in the general form "key:value".  The possible keys
       and the meaning of their values are as follows:


       class       Indicates  that  this  tag  is a member of the
                   class whose name is given by value.


       enum        Indicates that this tag is  a  member  of  the
                   enumeration whose name is given by value.




Darren Hiebert            Version 3.2.4                        15





CTAGS(1)                                                 CTAGS(1)


       file        Indicates  that  the  tag  has  a file-limited
                   scope (i.e. is static to the file).  This  key
                   has no corresponding value.


       kind        Indicates  the  type  of the tag. Its value is
                   either one  of  the  corresponding  one-letter
                   flags     described    under    the    various
                   --<lang>-types options above, or a full  name,
                   depending  upon  the  value of the --kind-long
                   option. Alternatively, this key may  be  omit-
                   ted, with only its value present (i.e. a field
                   without a ':' defaults to the kind key).


       interface   Indicates that this tag is  a  member  of  the
                   interface whose name is given by value.


       namespace   Indicates  that  this  tag  is a member of the
                   namespace whose name is given by value.


       private     Indicates the visibility of this class  member
                   is  private.   This  key  has no corresponding
                   value.


       protected   Indicates the visibility of this class  member
                   is  protected.   This key has no corresponding
                   value.


       public      Indicates the visibility of this class  member
                   is  public.   This  key  has  no corresponding
                   value.


       struct      Indicates that this tag is  a  member  of  the
                   structure whose name is given by value.


       union       Indicates  that  this  tag  is a member of the
                   union whose name is given by value.



ENVIRONMENT VARIABLES
       CTAGS   This variable, if found, will be assumed  to  con-
               tain  a  set  of  custom default options which are
               read when ctags starts,  but  before  any  command
               line  options  are  read. Options in this variable
               should be in the same form as those on the command
               line.  Command  line options will override options



Darren Hiebert            Version 3.2.4                        16





CTAGS(1)                                                 CTAGS(1)


               specified in this variable. Only  options  may  be
               specified with this variable; no source file names
               are read from its value.


       ETAGS   Similar to the CTAGS variable  above,  this  vari-
               able, if found, will be read when etags starts. If
               this variable is not found, etags will try to  use
               CTAGS instead.


HOW TO USE WITH VI
       Vi  will, by default, expect a tag file by the name "tags"
       in the current directory. Once the tag file is built,  the
       following commands exercise the tag indexing feature:

       vi -t tag   Start  vi  and position the cursor at the file
                   and line where "tag" is defined.

       Control-]   Find the tag under the cursor.

       :ta tag     Find a tag.

       Control-T   Return to previous location before jump to tag
                   (not widely implemented).



HOW TO USE WITH GNU EMACS
       Emacs  will,  by  default,  expect  a tag file by the name
       "TAGS" in the current directory.  Once  the  tag  file  is
       built,  the  following  commands exercise the tag indexing
       feature:

       Meta-x visit-tags-table
                   Visit a TAGS file.

       Meta-.      Find a definition for a tag.  The default  tag
                   is  the identifier under the cursor.  There is
                   name completion in the minibuffer; typing "foo
                   TAB"  completes  the  identifier starting with
                   `foo' (`foobar', for  example)  or  lists  the
                   alternatives.

       Meta-,      Find  the  next definition for the tag.  Exact
                   matches are found first, followed  by  fuzzier
                   matches.


       For  more  commands,  see the Tags topic in the Emacs info
       tree.






Darren Hiebert            Version 3.2.4                        17





CTAGS(1)                                                 CTAGS(1)


BUGS (CAVEATS)
       ctags has almost as many options as ls(1).


       Because ctags is neither a preprocessor  nor  a  compiler,
       use  of  preprocessor  macros  can  fool ctags into either
       missing tags or improperly generating inappropriate  tags.
       Although  ctags has been designed to handle certain common
       cases, this is the single biggest cause of reported  prob-
       lems.  In  particular,  the use of preprocessor constructs
       which alter the textual syntax of C can  fool  ctags.  You
       can work around many such problems by using the -I option.


       Legacy C source code which uses C++ reserved  keywords  as
       variable  or  parameter  names  (e.g.  "class", etc.) in a
       header file may fail to have correct  tags  generated  for
       the  objects  using them. In order to properly handle such
       code, use the --lang option.


       Note that when ctags generates uses patterns for  locating
       tags  (see  the  --excmd  option), it is entirely possible
       that the wrong line may be found by your editor  if  there
       exists  another source line which is identical to the line
       containing the tag.  The  following  example  demonstrates
       this condition:


              int variable;

              /* ... */
              void foo(variable)
              int variable;
              {
                  /* ... */
              }


       Depending  upon which editor you use and where in the code
       you happen to be, it is possible that the  search  pattern
       may locate the local parameter declaration in foo() before
       it finds the actual global variable definition, since  the
       lines (and therefore their search patterns are identical).
       This can be avoided by use of the --excmd=n option.



FILES
       tags      The default tag file created by ctags.

       TAGS      The default tag file created by etags.





Darren Hiebert            Version 3.2.4                        18





CTAGS(1)                                                 CTAGS(1)


SEE ALSO
       The official Exuberant Ctags web site at:


           http://darren.hiebert.com/ctags/index.html


       Also ex(1), vi(1), elvis, or, better yet, vim,  the  offi-
       cial editor of ctags. For more information on vim, see the
       VIM Pages web site at:


           http://www.vim.org/



AUTHOR
       Darren Hiebert <darren@hiebert.com>, <darren@hiwaay.net>
       http://darren.hiebert.com/



MOTIVATION
       "Think ye at all times of rendering some service to  every
       member of the human race."


       "All  effort  and exertion put forth by man from the full-
       ness of his heart is worship, if it  is  prompted  by  the
       highest motives and the will to do service to humanity."


                 -- From the Baha'i Writings



CREDITS
       This  version  of  ctags  was  originally derived from and
       inspired by the ctags program by Steve  Kirkendall  <kirk-
       enda@cs.pdx.edu>  that  comes  with  the  Elvis  vi  clone
       (though virtually none of the original code remains).


       Credit is also  due  Bram  Moolenaar  <Bram@vim.org>,  the
       author  of  vim,  who  has devoted so much of his time and
       energy both to developing the editor as a service to  oth-
       ers, and to helping the orphans of Uganda.


       The  section  entitled  "HOW  TO  USE  WITH GNU EMACS" was
       shamelessly stolen from the man page for GNU etags.






Darren Hiebert            Version 3.2.4                        19


