Man Linux: Main Page and Category List

NAME

       elvtags - Generates "tags" and (optionally) "refs" files

SYNOPSIS

       elvtags [-D word] [-FBNgitvshlpdxra] files...

VERSION

       This page describes the Elvis 2.2_0 version of ctags.  See elvis(1).

DESCRIPTION

       elvtags  generates  the  tags  and  refs files from a group of C source
       files.  The tags file is used by Elvis’ ":tag" command, ^] command, and
       -t option.  The refs file is sometimes used by the ref(1) program.

       Each  C  source  file  is  scanned  for  #define  statements and global
       function definitions.  The name of the macro or  function  becomes  the
       name of a tag.  For each tag, a line is added to the tags file.

       The filenames list will typically be the names of all C source files in
       the current directory, like this:

              $ elvtags *.c *.h

OPTIONS

       If no options are given, then elvtags acts as though the -l  -i  -t  -v
       and -s option flags were given.  If you want to omit those options, you
       can do so by explicitly giving a harmless option such as -F.

       -Dword This causes Elvis to ignore  any  instance  of  "word"  in  your
              source  code.   This  is  handy  if  you’re  using  a  macro for
              conditionally declaring the arguments to functions, in order  to
              make   your   code  be  backward-compatible  with  older  K&R  C
              compilers.  elvtags always ignores "P_" and  "__P";  the  -Dword
              flag allows you to make it ignore a third word.

       -F     Enclose  regular  expressions  in  slashes (/regexp/) which will
              cause elvis(1) to search from the top of the file.  This is  the
              default.

       -B     Enclose  the regular expressions in question marks (?regexp?) so
              elvis(1) will search backward from the bottom of the file.   The
              search  direction  rarely matters; this option exists mostly for
              compatibility with earlier versions of elvtags.

       -N     This causes elvtags to use line numbers for all  tags.   Without
              this  flag,  it  would  use  numbers  for #define’ed macros, and
              regular expressions for anything else.

       -g     For static tags, generate entries that look  like  global  tags.
              (I.e., never generate an extra "file:" attribute.)  This implies
              -s and -h.

       -i     Include inline definitions.  A tag will be  generated  for  each
              function  which  is  declared  as  being  inline,  __inline,  or
              __inline__.

       -t     Include typedefs.  A tag will be generated for each user-defined
              type.   Also  tags  will be generated for struct and enum names.
              Types are considered to be global  if  they  are  defined  in  a
              header  file, and static if they are defined in a C source file.

       -v     Include variable declarations.  A tag will be generated for each
              variable,  except for those that are declared inside the body of
              a function.

       -s     Include static tags.  elvtags will normally put global  tags  in
              the  tags  file, and silently ignore the static tags.  This flag
              causes both global and static tags to be added.

       -e     Include  extern  tags.   elvtags  will  normally  ignore  extern
              declarations  of  functions  or  variables;  that’s  handy  when
              generating tags for your own programs.   A  tags  file  for  the
              extern declarations in the system’s standard header files can be
              a very handy resource, so this -e flag was created.

       -h     Add hints that may help Elvis  handle  overloaded  tags  better.
              The resulting tags file may be unreadable by programs other than
              Elvis, though.

       -l     Add "ln" line number hints.  This implies -h, since it would  be
              pointless  if hints weren’t allowed.  The "ln" hints are used by
              elvis(1) to make its "showtag" option work much faster.

       -p     Write parsing information to stdout.  This is intended mainly as
              an  aid  to  debugging  the  elvtags command itself.  If elvtags
              doesn’t generate all of the tags that you expect it to, then try
              studying  the  -p  output  to  determine  what syntax feature is
              tripping it up.

       -d     Warn about duplicates, on  stdout.   elvtags  allows  tags  with
              duplicate  names,  except  for typedefs (tags with kind=t) which
              must be unique.  When a duplicate tag is detected,  elvtags  can
              either  add  it  if neither the new tag nor the existing one has
              "kind=t", skip it if the existing one has "kind=t",  or  add  it
              and  delete  the  existing  one  if  the  new  one has "kind=t".
              Usually you won’t care, but  -d  may  help  you  understand  why
              elvtags fails to add a tag that you expected it to add.

       -x     Generate  a  human-readable  tag  list instead of a "tags" file.
              The list is written to stdout.  Each line contains a  tag  name,
              the  line number and file name where the tag is defined, and the
              text of that line.

       -r     This causes elvtags to generate both tags and refs.  Without -r,
              it would only generate tags.

       -a     Append  to  tags,  and maybe refs.  Normally, elvtags overwrites
              these files each time it is invoked.  This flag is  useful  when
              you have too many files in the current directory for you to list
              them on a single  command-line;  it  allows  you  to  split  the
              arguments  among  several  invocations.   This  may result in an
              unsorted tags file.

FORMAT OF THE TAGS FILE

       The tags file is a text file.  Each line stores  the  attributes  of  a
       single tag.  The basic format of a line is:

              · the name of the tag
              · a tab character
              · the name of the file containing the tag
              · a tab character
              · the tag’s address within that file

       The  tag  address  may  be  given  as  either  line number (a string of
       digits), or  a  regular  expression  using  ex/vi’s  "nomagic"  syntax,
       delimited by either slashes or question marks.  Regular expressions are
       allowed to contain tab characters.

       The authors of Elvis, Vim, and  "Exuberant"  Ctags  have  agreed  on  a
       standard  format  for  adding  additional  attributes to tags.  In this
       format, the first three  fields  of  all  tags  are  identical  to  the
       traditional  format, except that a semicolon-doublequote character pair
       is appended to  the  tag  address  field,  with  the  extra  attributes
       appearing after that.

       The  semicolon-doublequote character pair is present because it has the
       surprising  side-effect  of  making  the  original  ex/vi  ignore   the
       remainder  of  the  line, thus allowing the original ex/vi to read new-
       format tags files.  The original ex/vi will  simply  ignore  the  extra
       attributes.

       Any  additional attributes are appended to the tag’s line.  They may be
       appended in any order.  Each attribute will use the following format:

              · a tab character
              · the name of the attribute
              · a colon character, ’:’
              · the value of the attribute.

       Note that each additional attribute has an  explicit  name.   Different
       tags  files  may use totally different names for additional attributes,
       and even within a single file, most tags will use only a subset of  the
       possible attributes.  This version of elvtags uses the following names:

       file   This attribute is used to mark static tags  --  i.e.,  tags  for
              C/C++  functions  or  variables  whose  scope  is limited to the
              function in which they are defined.  The value is  the  name  of
              the  file  where  it  is defined, except that if the file is the
              same as field 2 (and it nearly always is) then the value may  be
              given as a zero-length string.

       class  This is used to mark member functions of C++ classes.  The value
              is the class name.  However, currently elvtags doesn’t do a very
              good job of detecting whether a function is a member function or
              not.

       kind   This attribute’s  value  is  a  single  letter,  indicating  the
              lexical type of the tagged identifier: f for a function, t for a
              typedef, s for a struct  tag,  u  for  a  union  tag,  v  for  a
              variable,  d  for  a  macro  definition,  or  x  for  an  extern
              declaration.

              Note that in the tags file, the "kind:" label  is  omitted,  for
              the sake of compactness.

       ln     This  gives  the  line  number where the tag was defined.  It is
              redundant, but it is still somewhat  useful  because  it  allows
              elvis(1)’s "showtag" option to work faster.

       The  values  can  only  contain tabs if those tabs are converted to the
       ’\t’ (backslash-t) notation.  Similarly, a newline, carriage return, or
       literal  backslash  can  be  given as ’\n’, ’\r’, or ’\\’ respectively.
       For  MS-DOS  file  names,  this  means  the  names  must   use   double
       backslashes.   Space  characters  don’t  require  any special encoding.
       (This doesn’t apply to file names in the tagfile field, where names can
       be  given  without any special encoding.  It only applies to file names
       in extra fields.)

       As a special case, if an extra attribute contains no ’:’ to delimit the
       name  from  the  value,  then the attribute string is assumed to be the
       value of an attribute named "kind".  Usually  this  will  be  a  single
       letter  indicating  what  type  of  token the tag represents -- ’f’ for
       function, ’v’ for variable, and so on.

       Here’s an example of a new-format tag:
              bar  foo.c     /^void Foo::bar(int zot)$/;"  class:Foo
       The tagname is "bar", to match its function’s  name.   The  tagfile  is
       "foo.c".   The  tagaddress is a regular expression containing the whole
       definition line.  Note that a semicolon-doublequote character pair  has
       been  appended  to  the  tagaddress.   There  is  only  one  additional
       attribute, with the name "class" and the value "Foo".

FILES

       tags   A cross-reference that lists each tag  name,  the  name  of  the
              source  file  that contains it, and a way to locate a particular
              line in the source file.

       refs   The refs file contains the definitions for each tag in the  tags
              file,  and  very  little  else.   This  file  can be useful, for
              example, when licensing restrictions prevent you from making the
              source code to the standard C library readable by everybody, but
              you still want everybody to  know  what  arguments  the  library
              functions need.

BUGS

       elvtags  is  sensitive  to indenting and line breaks.  Consequently, it
       might not discover all of the tags in a file that is  formatted  in  an
       unusual way.

       The  -a  flag  causes  tag  files  to  be appended, but not necessarily
       sorted.  Some programs  expect  tags  files  to  be  sorted,  and  will
       misbehave   if   they   aren’t.    Also,   the   new  format  allows  a
       "!_TAG_FILE_SORTED" marker near the top of the file to indicate whether
       the  file  is sorted, but that might not be accurate after new tags are
       appended to the file.  Consequently, you should avoid the use of -a.

       The new standard doesn’t specify how overloaded  operators  are  to  be
       labelled.   If  your  C++ source contains a definition of operator+=(),
       then this version of elvtags  will  store  a  tag  named  "operator+=".
       Other versions of elvtags could simply use the name "+=".

SEE ALSO

       elvis(1), ref(1)

AUTHOR

       Steve Kirkendall
       kirkenda@cs.pdx.edu