SYNOPSIS

       ctags [options] [file(s)]

       ctags -e [options] [file(s)]



NOTE

       There are three different versions of the ctags program on
       SuSE Linux.  Besides this one you might want to use either
       gnuctags(1),  supporting  wide variety of programming lan­
       guages and originaly distributed with emacs, or gctags(1),
       which  comes with global(1) and supports for example Yacc.

       For use with emacs(1) the best choice is perhaps etags(1),
       but  it's  also  possible  to  use  ctags -e, as described
       herein, since it supports for example Eiffel.



DESCRIPTION

       The ctags program generates 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 utility. 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

           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
           Lua      *.lua
           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
           Verilog  *.v
           Vim      *.vim
           YACC/Bison
                    *.y

       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.
       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
            before  the first file name. If this option is speci­
            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
            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
            interpreted as a filename from which to read  a  list
            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
            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.


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

            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.


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


       --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. [Available only in
            etags mode]


       --exclude=[pattern]
            Add pattern to a list of excluded files and  directo­
            ries.  This  option may be specified as many times as
            desired. For each file name considered by ctags, each
            pattern  specified using this option 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  (not  regular  expressions) 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 deter­
            mine if shell wildcards are available on your platfom
            by  examining  the  output  of  the --version option,
            which will include "+wildcards" in the compiled  fea­
            ture list; otherwise, pattern 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  default
            exclude  list  contains  "EIFGEN", "SCCS", "RCS", and
                     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.


                   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]
               z   Include the "kind:" key in kind field

            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]
            (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
            specifies a new extended format containing  extension
            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.
            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.
            The typical use of this option is to first define the
            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,
            file extensions are tested before file name  patterns
            when inferring the language of a file.


       --language-force=language
            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
            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  an  extended
            regular  expression  (roughly that used by egrep(1)),
            which is used to locate a single source line contain­
            ing  a  tag  and may specify tab characters using \t.
            When a matching line is found, a tag will  be  gener­
            ated  for the name defined by replacement, which gen­
            erally will contain the  special  back-references  \1
            through \9 to refer to matching sub-expression groups
            within regexp. The '/' separator characters shown  in
            the  parameter to the option can actually be replaced
            by any character. Note that whichever separator char­
            acter  is  used  will have to be escaped with a back­
            slash ('\') character wherever  it  is  used  in  the
            parameter  as  something  other than a separator. The
            regular expression defined by this option is added to
            the current list of regular expressions for the spec­
            ified language unless the parameter  is  omitted,  in
            which case the current list is cleared.
            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.

            For more information on the regular expressionss used
            by ctags, see either the regex(5,7) man page, or  the
            GNU info documentation for regex (e.g. "info regex").


       --sort[=yes|no|foldcase]
            Indicates whether the tag file should  be  sorted  on
            the tag name (default is yes). Note that the original
            vi(1) required sorted tags.  The foldcase value spec­
            ifies  case  insensitive  (or  case-folded)  sorting.
            Fast binary searches of tag files sorted  with  case-
            folding will require special support from tools using
            tag files, such as that found in the  ctags  readtags
            library,  or  Vim  version  6.2 or higher (using "set
            ignorecase"). 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
            directory, unless the files supplied on  the  command
            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
            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
            t   types (structs and records)


       ASP
            f   functions
            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


       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
            s   subroutines
            t   derived types
            v   module variables


       Java
            c   classes
            f   fields
            i   interfaces
            m   methods
            p   packages


       Lisp
            f   functions


       Lua
            f   functions


       Make
            m   macros


       Pascal
            f   functions
            p   procedures


       Perl
            p   packages
            s   subroutines


       Ruby
            c   classes
            f   functions
            m   mixins


       Scheme
            f   functions
            s   sets


       Sh (Bourne, Korn, Z)
            f   functions


       SLang
            f   functions
            n   namespaces


       Tcl
            p   procedures


       Verilog
            f   functions
            m   modules
            P   parameters
            p   ports
            r   registers
            t   tasks
            v   variables
            w   wires


       Vim
            f   functions


       YACC
            l   labels




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

       M-x visit-tags-table <RET> FILE <RET>
                 Select the tag file, "FILE", to use.

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

       M-*       Pop back to where you previously invoked  "M-.".

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


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


       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
       of the extension fields. Also, if the  function  defintion
       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
               options  specified  in this variable. Only options
               will be read from this  variable.  Note  that  all
               white space in this variable in considered a sepa­
               rator, making it  impossible  to  pass  an  option
               parameter containing 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 ctags -e starts.
               If this variable is not found, ctags -e  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

       /ctags.cnf (on MSDOS, MSWindows only)
       /etc/ctags.conf
       /usr/local/etc/ctags.conf
       $HOME/.ctags ($HOME/ctags.cnf on MSDOS, MSWindows)
       .ctags (ctags.cnf on MSDOS, MSWindows)
              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 before any of those  shown  above,  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­


SEE ALSO

       etags(1), gctags(1), global(1), gnuctags(1).


       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 <dhiebert@users.sourceforge.net>
       http://DarrenHiebert.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 info page for GNU etags.



Darren Hiebert            Version 5.3.1                  CTAGS(1)

Man(1) output converted with man2html