CTAGS(1)                   Commands and Applications                  CTAGS(1)

NAME

       ctags - create a tags file

SYNOPSIS

       ctags [-BFadtuwvx] [-f tagsfile] name...

DESCRIPTION

       Ctags  makes  a  tags file for ex(1) from the specified C, Pascal, For‐
       tran, YACC, lex, and lisp sources.  A tags file gives the locations  of
       specified objects in a group of files.  Each line of the tags file con‐
       tains the object name, the file in which it is defined,  and  a  search
       pattern for the object definition, separated by white-space.  Using the
       tags file, ex(1) can quickly locate these object definitions.   Depend‐
       ing upon the options provided to ctags, objects will consist of subrou‐
       tines, typedefs, defines, structs, enums and unions.

       -B     use backward searching patterns (?...?).

       -F     use forward searching patterns (/.../) (the default).

       -a     append to tags file.

       -d     create tags for #defines that  don't  take  arguments;  #defines
              that take arguments are tagged automatically.

       -f     Places  the tag descriptions in a file called tagsfile.  The de‐
              fault behaviour is to place them in a file called tags.

       -t     create tags for typedefs, structs, unions, and enums.

       -u     update the specified files in the tags file, that is, all refer‐
              ences  to  them  are deleted, and the new values are appended to
              the file.  (Beware: this option is implemented in a way which is
              rather  slow;  it  is  usually faster to simply rebuild the tags
              file.)

       -v     An index of the form expected by vgrind(1) is  produced  on  the
              standard  output.   This  listing contains the object name, file
              name, and page number (assuming 64 line pages).  Since the  out‐
              put  will  be sorted into lexicographic order, it may be desired
              to run the output through sort(1).  Sample use:

                        ctags -v files | sort -f > index
                        vgrind -x index

       -w     suppress warning diagnostics.

       -x     ctags produces a list of object names, the line number and  file
              name  on which each is defined, as well as the text of that line
              and prints this on the standard output.  This is a simple  index
              which can be printed out as an off-line readable function index.

       Files  whose names end in .c or .h are assumed to be C source files and
       are searched for C style routine and macro  definitions.   Files  whose
       names end in .y are assumed to be YACC source files.  Files whose names
       end in .l are assumed to be lisp files if their first non-blank charac‐
       ter  is  `;',  `(',  or  `[', otherwise, they are treated as lex files.
       Other files are first examined to see if they  contain  any  Pascal  or
       Fortran routine definitions, and, if not, are searched for C style def‐
       initions.

       The tag main is treated specially in C programs.   The  tag  formed  is
       created  by  prepending M to the name of the file, with the trailing .c
       and any leading pathname components removed.  This makes use  of  ctags
       practical in directories with more than one program.

       Yacc  and  lex  files each have a special tag.  Yyparse is the start of
       the second section of the yacc file, and yylex is the start of the sec‐
       ond section of the lex file.

FILES

       tags   default output tags file

DIAGNOSTICS

       Ctags  exits  with a value of 1 if an error occurred, 0 otherwise.  Du‐
       plicate objects are not considered errors.

ATTRIBUTIONS

       This command was ported from FreeBSD source code for distribution  with
       GNO/ME 2.0.6.

SEE ALSO

       ex(1), vi(1)

BUGS

       Recognition  of  functions,  subroutines and procedures for FORTRAN and
       Pascal is done is a very simpleminded way.  No attempt is made to  deal
       with  block  structure;  if you have two Pascal procedures in different
       blocks with the same name you lose.   Ctags  doesn't  understand  about
       Pascal types.

       The  method  of deciding whether to look for C, Pascal or FORTRAN func‐
       tions is a hack.

       Ctags relies on the input being well formed, and any syntactical errors
       will completely confuse it.  It also finds some legal syntax confusing;
       for example, since it doesn't understand #ifdef's (incidentally, that's
       a  feature, not a bug), any code with unbalanced braces inside #ifdef's
       will cause it to become somewhat disoriented.  In  a  similar  fashion,
       multiple  line  changes  within a definition will cause it to enter the
       last line of the object, rather than the first, as the  searching  pat‐
       tern.   The  last  line  of  multiple  line typedef's will similarly be
       noted.

HISTORY

       The Ctags command appeared in 3.0BSD.



GNO                              October 1997                         CTAGS(1)