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 a variety of language objects
       found in file(s).  This tag file allows these items to  be
       quickly and easily located by a text editor or other util­
       ity. A "tag" signifies a  language  object  for  which  an
       index  entry  is  available  (or, alternatively, 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
       this release are:

           Vi(1) and its  derivatives  (e.g.  Elvis,  Vim,  Vile,
           Lemmy),  CRiSP, Emacs, FTE (Folding Text Editor), JED,
           NEdit (Nirvana Edit), TSE (The  SemWare  Editor),  X2,
           Zeus

       Ctags is capable of generating different kinds of tags for
       each of many different languages. For a complete  list  of
       supported  languages,  the  names by which they are recog­
       nized, and the kinds of tags which are generated for each,
       see TAG KINDS, below.


SOURCE FILES

       Unless  the --language-force option is specified, the lan­
       guage of each source file is automatically selected  based
       upon  a  mapping  of file names to languages. On platforms
       which support it, if the name of a file is not mapped to a
       language and the file is executable, the first line of the
       file is checked to see if the file is a "#!" script for  a
       recognized  language.  File  names are mapped to languages
       according to the following default mappings (which may  be


           Assembler
                    *.asm *.s *.S
           ASP      *.asp *.asa
           Awk      *.awk
           C        *.c
           C++      *.C *.c++ *.cc *.cpp *.cxx *.h *.H *.hh *.hpp
                    *.hxx *.h++
           BETA     *.bet
           COBOL    *.cob *.COB
           Eiffel   *.e
           Fortran  *.f *.for *.ftn *.f77 *.f90 *.f95  *.F  *.FOR
                    *.FTN *.F77 *.F90 *.F95
           Java     *.java
           Lisp     *.cl *.clisp *.el *.l *.lisp *.lsp *.ml
           Make     *.mak [Mm]akefile*
           Pascal   *.p *.pas
           Perl     *.pl *.pm *.perl
           PHP      *.php *.php3 *.phtml
           Python   *.py *.python
           REXX     *.cmd *.rexx *.rx
           Ruby     *.rb
           Scheme   *.sch *.scheme *.scm *.sm *.SCM *.SM
           Shell scripts (Bourne/Korn/Z)
                    *.sh *.SH *.bsh *.bash *.ksh *.zsh
           S-Lang   *.sl
           Tcl      *.tcl *.wish
           Vim      *.vim

       By  default,  all other files names are ignored. This per­
       mits running ctags on all files in either a single  direc­
       tory  (e.g.  "ctags  *"), or all files in an entire source
       directory tree (e.g. "ctags -R"), since only  those  files
       whose names are mapped to languages will be scanned.

       The  reason  that  .h  extensions  are mapped to C++ files
       rather than C files is because it  is  common  to  use  .h
       extensions in C++, and no harm results in treating them as
       C++ files.


OPTIONS

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

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

       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  consid­
       ered  synonyms  for  "=yes",  and that "=0" and "=off" are
       considered synonyms for "=no".

       Some options are either ignored or useful only  when  used
       while  running in etags mode (see -e option). Such options
       will be noted.

       Most options may appear  anywhere  on  the  command  line,
       affecting  only those files which follow the option. A few
       options, however, must appear before the first  file  name
       and will be noted as such.

       Options  taking  language names will accept those names in
       either upper or lower case. See TAG KINDS for  a  complete
       list of the built-in language names.

       -a   Equivalent to --append.

       -B   Use  backward  searching  patterns  (e.g. ?pattern?).
            [Ignored in etags mode]

       -e   Enable etags mode, which will create a tag  file  for
            use  with  the Emacs editor.  Alternatively, if ctags
            is invoked by a name containing  the  string  "etags"
            (either  by renaming, or creating a link to, the exe­
            cutable), etags mode will  be  enabled.  This  option
            must appear before the first file name.

       -f tagfile
            Use  the  name  specified by tagfile for the tag file
            (default is "tags", or "TAGS" when running  in  etags
            mode).  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
            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! It will also refuse to  accept  a
            multicharacter  file  name  which  begins  with a '-'
            (dash) character, since this most likely  means  that
            you  left out the tag file name and this option tried
            to grab the next option as  the  file  name.  If  you
            really  want  to  name  your output tag file "-ugly",
            specify it as  "./-ugly".  This  option  must  appear

            fied more than once, only the last will apply.

       -F   Use  forward  searching  patterns  (e.g.   /pattern/)
            (default).  [Ignored in etags mode]

       -h list
            Specifies  a  list  of  file extensions, separated by
            periods, which are to be interpreted as  include  (or
            header) files. To indicate files having no extension,
            use a period not followed by a  non-period  character
            (e.g.  ".",  "..x",  ".x."). This option only affects
            how the scoping of a  particular  kinds  of  tags  is
            interpreted  (i.e. whether or not they are considered
            as globally visible or visible only within  the  file
            in  which  they  are  defined);  it  does not map the
            extension to any particular language. Any  tag  which
            is  located  in a non-include file and cannot be seen
            (e.g. linked to) from another file is  considered  to
            have file-limited (e.g. static) scope. No kind of tag
            appearing in an include file will  be  considered  to
            have  file-limited  scope.  If the first character in
            the list is a plus sign, then the extensions  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". To restore the default
            list,  specify  -h default. Note that if an extension
            supplied to this option is not already  mapped  to  a
            particular  language  (see  SOURCE FILES, above), you
            will also need to use either the --langmap or  --lan­
            guage-force 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
            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 '@', '.' or a pathname separator ('/' or
            '\'), or the first two  characters  specify  a  drive
            letter  (e.g.  "C:"), the parameter tokenlist will be

            of  tokens, one per input line.  Otherwise, 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 argu­
            ment). Multiple -I options may be supplied. To  clear
            the list of ignore tokens, supply a single dash ("-")
            for tokenlist.

            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 "ARGDECL4"  would  be
            mistakenly interpreted to be the name of the function
            instead of the correct name of "foo".  Specifying  -I
            ARGDECL4 results in the correct behavior.

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

            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
               };

            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(dllexport)"  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.

            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. File
            names read using this option are processed  following
            file names appearing on the command line. Options all
            also accepted in this input. If this option is speci­
            fied  more than once, only the last will apply. Note:
            file is read in line-oriented mode, where a new  line
            is  the only delimiter and spaces are considered sig­
            nificant, in order that file names containing  spaces
            may  be  supplied;  this  can  affect how options are
            parsed if included in the input.

       -n   Equivalent to --excmd=number.

       -N   Equivalent to --excmd=pattern.

       -o tagfile
            Equivalent to -f tagfile.

       -R   Equivalent to --recurse.

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

       -V   Equivalent to --verbose.

       -w   This option is silently ignored for backwards compat­
            ibility with the ctags of SVR4 Unix.

       -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
            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).
            This option must appear before the first file name.

            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.  This option must appear before the
            first file name.  [Ignored in etags mode]

       --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 in etags
            mode]

       --exclude=[pattern]
            Add pattern to a list of excluded files and  directo­
            ries. For each file name considered by ctags, pattern
            will be compared against both the complete path (e.g.
            some/path/base.ext) and the base name (e.g. base.ext)
            of the file, thus allowing  patterns  which  match  a
            given  file  name  irrespective of its path, or match
            only a  specific  path.  If  appropriate  support  is
            available  from  the  runtime  library of your C com­
            piler, then pattern may contain the usual shell wild­
            cards  common  on  Unix  (be sure to quote the option
            parameter  to  protect  the  wildcards   from   being
            expanded  by  the shell before being passed to ctags;
            also be aware that  wildcards  can  match  the  slash
            character, '/'). You can determine if shell wildcards
            are available on your platfom by examining the output
            of  the  --version option, which will include "+wild­
            cards" in the compiled feature list; otherwise,  pat­
            tern  is  matched  against  file names using a simple
            textual comparison.

            If pattern begins with the character  '@',  then  the
            rest of the string is interpreted as a file name from
            which to read exclusion patterns, one  per  line.  If
            pattern  is  empty,  the list of excluded patterns is
            cleared.  Note that at program startup,  the  exclude
            list  contains  "EIFGEN" and "SCCS" by default, which
            are directories for which it is generally not  desir­
            able to descend.

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

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

                     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
                         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.

            Specifies whether to include extra  tag  entries  for
            certain  kinds of information. The parameter flags is
            a set of one-letter flags, each representing one kind
            of  extra  tag  entry  to include in the tag file. If
            flags is preceded by by either the '+' or '-' charac­
            ter,  the effect of each flag is added to, or removed
            from, those currently enabled;  otherwise  the  flags
            replace  any  current  settings.  The meaning of each
            flag is as follows:

               f   Include an entry for the  base  file  name  of
                   every  source  file (e.g.  "example.c"), which
                   addresses the first line of the file.

               q   Include an extra class-qualified tag entry for
                   each  tag  which  is  a member of a class (for
                   languages  for  which  this   information   is
                   extracted;  currently  C++, Eiffel, and Java).
                   The actual form of the qualified  tag  depends
                   upon  the  language  from  which  the  tag was
                   derived (using a form that is most natural for
                   how  qualified calls are specified in the lan­
                   guage).  For  C++,   it   is   in   the   form
                   "class::member"; for Eiffel and Java, it is in
                   the form "class.member". This may allow easier
                   location  of  a  specific  tags  when multiple
                   occurrances of a tag name  occur  in  the  tag
                   file.  Note,  however,  that this could poten­
                   tially more than double the size  of  the  tag
                   file.

       --fields=[+|-]flags
            Specifies the available extension fields which are to
            be included in the entries of the tag file  (see  TAG
            FILE FORMAT, below, for more information). The param­
            eter flags is a set of one-letter flags, each  repre­
            senting  one type of extension field to include, with
            the following meanings (disabled  by  default  unless
            indicated):

               a   Access (or export) of class members
               f   File-restricted scoping [enabled]
               i   Inheritance information
               k   Kind of tag as a single letter [enabled]
               K   Kind of tag as full name
               l   Language of source file containing tag
               m   Implementation information
               n   Line number of tag definintion
               s   Scope of tag definition [enabled]


            Each  letter  or  group of letters may be preceded by
            either '+' to add it to the default set,  or  '-'  to
            exclude  it.  In  the absence of any preceding '+' or
            '-' sign, only those kinds explicitly listed in flags
            will  be  included in the output (i.e. overriding the
            default set). This option is ignored  if  the  option
            --format=1 has been specified.

       --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.

       --filter[=yes|no]
            Causes  ctags  to  behave as a filter, reading source
            file names from standard  input  and  printing  their
            tags  to  standard output on a file-by-file basis. If
            --sorted is enabled, tags are sorted only within  the
            source file in which they are defined. File names are
            read from standard output in line-oriented input mode
            (see  note  for  -L option) and only after file names
            listed on the command line or from any file  supplied
            using the -L option. When this option is enabled, the
            options -f, -o, and --totals are ignored. This option
            is  quite  esoteric  and is disabled by default. This
            option must appear before the first file name.

       --filter-terminator=string
            Specifies a string to print to standard  output  fol­
            lowing  the  tags  for each file name parsed when the
            --filter option is enabled. This may permit an appli­
            cation  reading the output of ctags to determine when
            the output for each file is finished.  Note  that  if
            the  file  name  read is a directory and --recurse is
            enabled, this string will be printed only one once at
            the  end  of  all  tags  found  for by descending the
            directory. This string will always be separated  from
            the  last  tag  line  for the file by its terminating
            newline.  This option is quite esoteric and is  empty
            by  default. This option must appear before the first
            file name.

       --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

            fields (but in a manner which retains  backward  com­
            patibility  with original vi(1) implementations). The
            default level is 2. This option  must  appear  before
            the first file name. [Ignored in etags mode]

       --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.

       --<LANG>-types=[+|-]kinds
            Specifies a list of language-specific kinds  of  tags
            (or  kinds)  to include in the output file for a par­
            ticular language, where <LANG> is one of the built-in
            language  names (see TAG KINDS, below, for a complete
            list). The parameter kinds is a group  of  one-letter
            flags  designating  kinds  of tags (particular to the
            language) to either include or exclude from the  out­
            put.  The  specific sets of flags recognized for each
            language, their meanings and defaults is described in
            TAG KINDS, below. Each letter or group of letters may
            be preceded by either '+' to add it  to  the  default
            set, or '-' to exclude it. In the absence of any pre­
            ceding '+' or '-' sign, only those  kinds  explicitly
            listed  in kinds will be included in the output (i.e.
            overriding the default for the specified language).

            As an example for the C language,  in  order  to  add
            prototypes  and external variable declarations to the
            default set of tag kinds,  but  exclude  macros,  use
            --c-types=+px-d;  to include only tags for functions,
            use --c-types=f.

       --langdef=name
            Defines a new  user-defined  language,  name,  to  be
            parsed  with  regular expressions. Once defined, name
            may be used in other options taking  language  names.

            language, then map file names to it using  --langmap,
            then specify regular expressions using --regex-<LANG>
            to define how its tags are found.

       --langmap=map[,map[...]]
            Controls how file names are mapped to languages  (see
            SOURCE  FILES,  above). Each comma-separated map con­
            sists of the language  name  (either  a  built-in  or
            user-defined  language),  a colon, and a list of file
            extensions and/or file name patterns. A  file  exten­
            sion  is  specified by preceding the extension with a
            period (e.g. ".c"). A file name pattern is  specified
            by   enclosing   the  pattern  in  parentheses  (e.g.
            "([Mm]akefile)"). If appropriate support is available
            from the runtime library of your C compiler, then the
            file name pattern may contain the usual  shell  wild­
            cards  common  on  Unix  (be sure to quote the option
            parameter  to  protect  the  wildcards   from   being
            expanded  by the shell before being passed to ctags).
            You can determine if shell wildcards are available on
            your platfom by examining the output of the --version
            option, which will include "+wildcards" in  the  com­
            piled feature list; otherwise, the file name patterns
            are matched against file names using a simple textual
            comparison.

            If  the first character in a map is a plus sign, then
            the extensions and file name  patterns  in  that  map
            will  be  appended  to  the current map for that lan­
            guage; otherwise, the map will  replace  the  current
            map.  For  example,  to  specify that only files with
            extensions of .c and .x are to be treated as  C  lan­
            guage  files,  use  "--langmap=c:.c.x";  to  also add
            files with extensions of .j as Java  language  files,
            specify "--langmap=c:.c.x,java:+.j". To map makefiles
            (.e.g files named either "Makefile",  "makefile",  or
            having  the  extension  ".mak")  to a language called
            "make",  specify  "--langmap=make:([Mm]akefile).mak".
            To  map  files  having no extension, specify a period
            not followed by a  non-period  character  (e.g.  ".",
            "..x",  ".x."). To clear the mapping for a particular
            language (thus  inhibiting  automatic  generation  of
            tags  for  that language), specify an empty extension
            list (e.g.   "--langmap=fortran:").  To  restore  the
            default  language  mappings for all a particular lan­
            guage, supply the keyword "default" for the  mapping.
            To  specify restore the default language mappings for
            all languages, specify "--langmap=default". Note that
            file  extensions are tested before file name patterns
            when inferring the language of a file.

            By default, ctags automatically selects the  language
            of a source file, ignoring those files whose language
            cannot be determined (see SOURCE FILES, above).  This
            option forces the specified language (either built-in
            or user-defined) to be used for every  supplied  file
            instead of automatically selecting the language based
            upon its extension. In addition,  the  special  value
            auto  indicates that the language should be automati­
            cally  selected  (which  effectively  disables   this
            option).

       --languages=[+|-]list
            Specifies  the  languages for which tag generation is
            enabled, with list containing a comma-separated  list
            of  language names (either built-in or user-defined).
            If the first language of  list  is  not  preceded  by
            either  a  languages  in list. Until a '-' is encoun­
            tered, each language in the list will be added to the
            current list. As either the '+' or '-' is encountered
            in the list, the languages following it are added  or
            removed from the current list, respectively. Thus, it
            becomes simple to replace the current list with a new
            one,  or  to add or remove languages from the current
            list. The actual list of files for which tags will be
            generated depends upon the language extension mapping
            in effect (see the --langmap option). Note  that  all
            languages,   including   user-defined  languages  are
            enabled unless explicitly disabled using this option.
            Language  names  included in list may be any built-in
            language or one previously  defined  with  --langdef.
            The  default  is  "all",  which is also accepted as a
            valid argument. See TAG KINDS for a complete list  of
            the built-in language names.

       --license
            Prints  a summary of the software license to standard
            output.

       --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

            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 --langmap or  --language-force  option  if
            the  extension of the preprocessor output file is not
            known to ctags.

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

       --options=file
            Read additional options from file.

       --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. Symbolic 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.  It is available if the  output
            of  the  --help  option  includes  this option.  See,
            also, the --exclude to limit recursion.

       --regex-<LANG>=/regexp/replacement/[kind-spec/][flags]
            The  /regexp/replacement/  pair  define   a   regular
            expression  replacement  pattern, similar in style to
            sed substitution commands,  with  which  to  generate
            tags  from source files mapped to the named language,
            <LANG>, (either a built-in or user-defined language).
            The  regular  expression  regexp  defines  a  regular
            expression which is used to locate  a  single  source
            line  containing a tag and may specify tab characters
            using \t. When a matching line is found, a  tag  will
            be  generated  for  the  name defined by replacement,
            which generally will contain the special  back-refer­
            ences  \1 through \9 to refer to matching sub-expres­
            sion groups within regexp. The '/' separator  charac­
            ters  shown  in the parameter to the option can actu­
            ally  be  replaced  by  any  character.   Note   that
            whichever separator character is used will have to be
            escaped with a backslash ('\') character wherever  it

            separator. The regular  expression  defined  by  this
            option  is  added  to  the  current  list  of regular
            expressions for the  specified  language  unless  the
            parameter  is omitted, in which case the current list
            is cleared.

            Unless modified by flags, regexp is interpreted as  a
            Posix  extended  regular  expression. The replacement
            should expand for all matching lines to  a  non-empty
            string  of  characters,  or a warning message will be
            reported. An optional kind specifier for tags  match­
            ing  regexp may follow replacement, which will deter­
            mine what kind of  tag  is  reported  in  the  "kind"
            extension  field  (see  TAG  FILE FORMAT, below). The
            kind-spec is expected to be in the form of  a  single
            letter,  a comma, and a name followed by a separator,
            which specify the short and long forms  of  the  kind
            value.  If  kind-spec  is  omitted,  it  defaults  to
            "r,regex".  Finally, flags are one  or  more  single-
            letter  characters  having  the following effect upon
            the interpretation of regexp:

               b   The pattern is interpreted as  a  Posix  basic
                   regular expression.

               e   The pattern is interpreted as a Posix extended
                   regular expression (default).

               i   The regular expression is to be applied  in  a
                   case-insensitive manner.

            Note  that this option is available only if ctags was
            compiled with support for regular expressions,  which
            depends upon your platform. You can determine if sup­
            port for regular expressions is compiled in by  exam­
            ining  the output of the --version option, which will
            include "+regex" in the compiled feature list.

       --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.  This  option  must  appear before the first
            file name.  [Ignored in etags mode]

       --tag-relative[=yes|no]
            Indicates that the file paths  recorded  in  the  tag
            file  should  be relative to the directory containing
            the tag file, rather than  relative  to  the  current

            line are specified with absolute paths.  This  option
            must  appear  before the first file name. The default
            is yes  when  running  in  etags  mode  (see  the  -e
            option), no otherwise.

       --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.  This option
            must appear before the first file name.

       --verbose[=yes|no]
            Enable verbose mode. This prints out  information  on
            option processing and a brief message describing what
            action is being taken for  each  file  considered  by
            ctags.  Normally,  ctags  does  not read command line
            arguments until after options are read from the  con­
            figuration  files  (see  FILES,  below) and the CTAGS
            environment variable. However, if this option is  the
            first  argument  on  the  command  line, it will take
            effect  before  any  options  are  read  from   these
            sources. The default is no.

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


TAG KINDS

       Each  type  (or  kind)  of tag recorded in the tag file is
       indicated by a one-letter flag, which is also used to fil­
       ter  the  tags  placed  into the output through use of the
       --<LANG>-type option. The flags corresponding to each  tag
       kind for each langauge are described below. Note that some
       languages and/or tag kinds may be implemented using  regu­
       lar  expressions and may not be available if regex support
       is  not  compiled  into  ctags  (see  the   --regex-<LANG>
       option).  Kinds  are enabled by default except where noted
       (with "[off]").

       Asm
            d   defines
            l   labels
            m   macros

       ASP

            s   subroutines

       Awk
            f   functions

       BETA
            f   fragment definitions
            p   all patterns [off]
            s   slots (fragment uses)
            v   patterns (only virtual or  rebound  patterns  are
                recorded)

       C and C++
            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]

       Cobol
            p   paragraphs

       Eiffel
            c   classes
            f   features
            l   local entities [off]

       Fortran
            b   block data
            c   common blocks
            e   entry points
            f   functions
            i   interfaces
            k   type components
            l   labels
            L   local and common block variables [off]
            m   modules
            n   namelists
            p   programs

            t   derived types
            v   module variables

       Java
            c   classes
            f   fields
            i   interfaces
            m   methods
            p   packages

       Lisp
            f   functions

       Make
            m   macros

       Pascal
            f   functions
            p   procedures

       Perl
            s   subroutines

       PHP
            c   classes
            f   functions

       Python
            c   classes
            f   functions

       REXX
            s   subroutines

       Ruby
            c   classes
            f   functions
            m   mixins

       Scheme
            f   functions
            s   sets

            f   functions

       SLang
            f   functions
            n   namespaces

       Tcl
            p   procedures

       Vim
            f   functions


OPERATIONAL DETAILS

       As  ctags  considers  each  file name in turn, it tries to
       determine the language of the file by applying the follow­
       ing  three  tests in order: if the file extension has been
       mapped to a language, if the file  name  matches  a  shell
       pattern  mapped  to a language, and finally if the file is
       executable and its first  line  specifies  an  interpreter
       using  the  Unix-style "#!" specification (if supported on
       the platform). If a language was identified, the  file  is
       opened  and then the appropriate language parser is called
       to operate on the currently open file. The  parser  parses
       through  the  file  and  adds an entry to the tag file for
       each language object it is written to handle. See TAG FILE
       FORMAT, below, for details on these entries.

       This   implementation   of  ctags  imposes  no  formatting
       requirements on C code as do legacy implementations. Older
       implementations  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;

              }

       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 ("}")
       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.


TAG FILE FORMAT

       When not running in etags mode, each entry in the tag file
       consists of a separate line, each looking like this in the
       most general case:

        tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields

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

           1.  tag name
           2.  single tab character
           3.  name of the file in which  the  object  associated
               with the tag is located
           4.  single tab character
           5.  EX command used to locate the tag within the file;

               ?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 fields (described below) embedded in  an
               EX comment immediately appended to the EX command,
               which leaves it backwards compatible 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
       number  to  detect  a tag file for purposes of determining
       whether a valid tag file is being overwritten rather  than
       a source file.

       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 the current directory,  then  it  will  be
       recorded  in  that  same manner in the tag file. See, how­
       ever, the --tag-relative option for how this behavior  can
       be modified.

       Extension   fields   are   tab-separated  key-value  pairs
       appended to the end of the EX command  as  a  comment,  as
       described  above. These key value pairs appear in the gen­
       eral form "key:value". Their presence in the lines of  the
       tag file are controlled by the --fields option. The possi­
       ble keys and the meaning of their values are as follows:

       access      Indicates the visibility of this class member,
                   where value is specific to the language.

       file        Indicates  that the tag has file-limited visi­
                   bility. This key has no corresponding value.

       kind        Indicates the type, or kind, of tag. Its value
                   is  either one of the corresponding one-letter
                   flags    described    under    the     various
                   --<LANG>-types  options above, or a full name.
                   It is permitted (and is, in fact, the default)
                   for  the key portion of this field to be omit­
                   ted. The  optional  behaviors  are  controlled
                   with the --fields option.

       implementation
                   When  present, this indicates a limited imple­
                   mentation (abstract vs. concrete) of a routine

                   guage ("virtual" or "pure  virtual"  for  C++;
                   "abstract" for Java).

       inherits    When present, value. is a comma-separated list
                   of classes from which this  class  is  derived
                   (i.e. inherits from).

       In  addition,  information on the scope of the tag defini­
       tion may be available, with the key portion equal to  some
       language-dependent  construct  name and its value the name
       declared for that construct in  the  program.  This  scope
       entry  indicates the scope in which the tag was found. For
       example, a tag generated for a C  structure  member  would
       have a scope looking like "struct:myStruct".


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.

       :ta tag     Find a tag.

       Ctrl-]      Find the tag under the cursor.

       Ctrl-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 <RET> FILE <RET>
                   Display a list of the tags defined in the pro­
                   gram file FILE.

       Meta-. [TAG] <RET>
                   Find  the  first definition of TAG (default is
                   identifier under cursor).  The default tag  is
                   the identifier under the cursor.

       C-u M-.     Find the next definition for the last tag.

       document.


CAVEATS

       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.

       White space is treated as a separator for file  names  and
       options  read  from  list  files,  specified  using the -L
       option, and in filter mode (specified using  the  --filter
       option). Therefore, it is not currently possible to supply
       file names or  other  options  containing  embedded  white
       space (spaces, etc.) through these options.

       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.


BUGS

       Ctags has more options than ls(1).

       When  parsing  a  C++  member  function  definition  (e.g.
       "className::function"), ctags cannot determine whether the
       scope  specifier  is a class name or a namespace specifier
       and always lists it as a class name in the  scope  portion

       is located in a separate file from than where the class is
       defined  (the  usual case), the access specification (i.e.
       public, protected, or private) that the function had  when
       declared in the class is not known.

       No  qualified  tags  are  generated  for  language objects
       inherited into a class.


ENVIRONMENT VARIABLES

       CTAGS   If this environment variable exists,  it  will  be
               expected to contain a set of default options which
               are read when ctags starts, after  the  configura­
               tion  files  listed in FILES, below, are read, but
               before any command line options are read.  Options
               appearing   on  the  command  line  will  override
               options specified in this file. Only options  will
               be  read from this file. Note that all white space
               in this variable in considered a separator, making
               it impossible to pass an option parameter contain­
               ing an embedded space.  If this is a problem,  use
               a configuration file instead.

       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.

       TMPDIR  On Unix-like hosts where mkstemp()  is  available,
               the value of this variable specifies the directory
               in which to place temporary  files.  This  can  be
               useful if the size of a temporary file becomes too
               large to fit on the partition holding the  default
               temporary  directory  defined at compilation time.
               ctags creates temporary files only if  either  (1)
               an  emacs-style  tag  file is being generated, (2)
               the tag file is being sent to standard output,  or
               (3)  the  program  was compiled to use an internal
               sort algorithm to sort the tag  files  instead  of
               the  the  sort utility of the operating system. If
               the sort utility of the operating system is  being
               used,  it  will  generally  observe  this variable
               also. Note that if ctags is setuid, the  value  of
               TMPDIR will be ignored.


FILES

       /etc/ctags.conf
       /usr/local/etc/ctags.conf

       .ctags
              If  any  of  these  configuration files exist, each
              will be  expected  to  contain  a  set  of  default
              options  which  are  read  in the order listed when
              ctags starts,  but  before  the  CTAGS  environment
              variable  is  read  or any command line options are
              read. This makes it possible to set  up  site-wide,
              personal  or project-level defaults. It is possible
              to compile ctags to read an  additional  configura­
              tion  file  immediately  before $HOME/.ctags, which
              will be indicated if the  output  produced  by  the
              --version  option  lists the "custom-conf" feature.
              Options appearing in the CTAGS environment variable
              or on the command line will override options speci­
              fied in these files. Only options will be read from
              these files. Note that the option files are read in
              line-oriented mode in which spaces are  significant
              (since shell quoting is not possible). Each line of
              the file is read as one command line parameter  (as
              if  it  were quoted with single quotes). Therefore,
              use new lines  to  indicate  separate  command-line
              arguments.

       tags   The default tag file created by ctags.

       TAGS   The default tag file created by etags.


SEE ALSO

       The official Exuberant Ctags web site at:

              http://ctags.sourceforge.net

       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>,
       <dhiebert@users.sourceforge.net>
       http://darren.hiebert.com/


MOTIVATION

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

       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 info page for GNU etags.


Man(1) output converted with man2html