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