home | help 
CTAGS(1)		     General Commands Manual			CTAGS(1)

NAME
     ctags -- create a tags file

SYNOPSIS
     ctags [-BFTaduwvx] [-f tagsfile] file ...

DESCRIPTION
     The ctags utility makes a tags file for ex(1) from the specified C, Pascal,
     Fortran,  yacc(1),  lex(1),  and Lisp sources.  A tags file gives the loca-
     tions of specified objects in a group of files.  Each line of the tags file
     contains 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.   Depending
     upon  the	options  provided to ctags, objects will consist of subroutines,
     typedefs, defines, structs, enums and unions.

     The following options are available:

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

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

     -T      Do not create tags for typedefs, structs, unions, and enums.

     -a      Append to tags file.

     -d      Create tags for #defines that do not take arguments; #defines  that
	     take arguments are tagged automatically.

     -f      Place  the tag descriptions in a file called tagsfile.  The default
	     behaviour is to place them in a file called tags.	If  tagsfile  is
	     "-", the tags will be written to standard output instead.

     -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.   This is ignored if the tags file does not exist or is not a
	     regular file (e.g.  -f- was used to write to standard output).

	     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 stan-
	     dard output.  This listing contains the object name, file name, and
	     page  number  (assuming  64  line pages).	Since the output will be
	     sorted into lexicographic order, it may be desired to run the  out-
	     put 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(1) source files.  Files whose names end in .l
     are assumed to be Lisp files if their first  non-blank  character	is  `;',
     `(',  or `[', otherwise, they are treated as lex(1) files.  Other files are
     first examined to see if they contain any Pascal or Fortran routine defini-
     tions, and, if not, are searched for C style definitions.

     The tag "main" is treated specially in C programs.  The tag formed is  cre-
     ated  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.

     The yacc(1) and lex(1) files each have a special  tag.   "yyparse"  is  the
     start  of	the second section of the yacc(1) file, and "yylex" is the start
     of the second section of the lex(1) file.

FILES
     tags  default output tags file

EXIT STATUS
     The ctags utility exits with a value of 1 if an error  occurred,  0  other-
     wise.  Duplicate objects are not considered errors.

COMPATIBILITY
     The  -t option is a no-op for compatibility with previous versions of ctags
     that did not create tags for typedefs, enums, structs  and  unions  by  de-
     fault.

SEE ALSO
     ex(1), vi(1)

STANDARDS
     The ctags utility conforms to IEEE Std 1003.1-2001 ("POSIX.1").

HISTORY
     The ctags utility appeared in 3.0BSD.

BUGS
     Recognition of functions, subroutines and procedures for Fortran and Pascal
     is  done in 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.   The ctags utility does not understand about Pascal
     types.

     The method of deciding whether to look for C, Pascal or  Fortran  functions
     is a hack.

     The  ctags utility relies on the input being well formed, and any syntacti-
     cal errors will completely confuse it.  It also  finds  some  legal  syntax
     confusing;  for  example,	since  it does not understand #ifdef's (inciden-
     tally, that is a feature, not a bug), any code with unbalanced  braces  in-
     side  #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.

FreeBSD 15.1			  May 23, 2023				CTAGS(1)
home | help