Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       exctags - Generate tag files for	source code

SYNOPSIS
       exctags [options] [file(s)]

       etags [options] [file(s)]

DESCRIPTION
       The exctags and etags programs (hereinafter collectively	referred to as
       ctags, except where distinguished) generate an index  (or  "tag")  file
       for  a variety of language objects found	in file(s).  This tag file al-
       lows 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, jEdit, Mined,	NEdit (Nirvana
	   Edit), TSE (The SemWare Editor), UltraEdit, WorkSpace, 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 recognized, and the kinds  of  tags  which  are
       generated for each, see the --list-languages and	--list-kinds options.

SOURCE FILES
       Unless  the  --language-force option is specified, the language of each
       source file is automatically selected based  upon  a  mapping  of  file
       names  to  languages.  The  mappings in effect for each language	may be
       display using the --list-maps option  and  may  be  changed  using  the
       --langmap option.  On platforms which support it, if the	name of	a file
       is not mapped to	a language and the file	is executable, the first  line
       of the file is checked to see if	the file is a "#!" script for a	recog-
       nized language.

       By default, all other files names are  ignored.	This  permits  running
       ctags on	all files in either a single directory (e.g. "ctags *"), or on
       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	param-
       eters are optional.

       Note also that the boolean parameters to	the long form  options	(those
       beginning with "--" and that take a "[=yes|no]" parameter) may be omit-
       ted, in which case "=yes" is implied. (e.g.  --sort  is	equivalent  to
       --sort=yes).  Note  further that	"=1" and "=on" are considered synonyms
       for "=yes", and that "=0" and "=off" are	considered synonyms for	"=no".

       Some options are	either ignored or useful only when used	while  running
       in etags	mode (see -e option). Such options will	be noted.

       Most  options  may  appear anywhere on the command line,	affecting only
       those files which follow	the option. A few options, however,  must  ap-
       pear 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 the --list-languages option 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 con-
	    taining the	string "etags" (either by renaming, or creating	a link
	    to,	 the executable), 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 spec-
	    ified as "-", then the tag file is written to standard output  in-
	    stead.  Ctags will stubbornly refuse to take orders	if tagfile ex-
	    ists 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 otherwise	overwrite your first C file  with  the
	    tags generated by the rest!	It will	also refuse to accept a	multi-
	    character 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 specified	more than once,	only the last will ap-
	    ply.

       -F   Use	forward	searching patterns (e.g. /pattern/)  (default).	  [Ig-
	    nored in etags mode]

       -h list
	    Specifies  a  list of file extensions, separated by	periods, which
	    are	to be interpreted as include (or header)  files.  To  indicate
	    files  having no extension,	use a period not followed by a non-pe-
	    riod character (e.g. ".", "..x", ".x."). This option only  affects
	    how	the scoping of a particular kinds of tags is interpreted (i.e.
	    whether or not they	are considered as globally visible or  visible
	    only  within  the file in which they are defined); it does not map
	    the	extension to any particular language. Any tag which is located
	    in a non-include file and cannot be	seen (e.g. linked to) from an-
	    other file is considered to	have file-limited (e.g.	static)	scope.
	    No	kind of	tag appearing in an include file will be considered to
	    have file-limited scope. If	the first character in the list	 is  a
	    plus sign, then the	extensions in the 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,	 spec-
	    ify	 -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 identifier-list
	    Specifies a	list of	identifiers 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  pre-
	    processor  macros.	When the identifiers listed are	simple identi-
	    fiers, these identifiers will be ignored  during  parsing  of  the
	    source  files.  If an identifier is	suffixed with a	'+' character,
	    ctags will also  ignore  any  parenthesis-enclosed	argument  list
	    which  may	immediately follow the identifier in the source	files.
	    If two identifiers are separated with the '=' character, the first
	    identifiers	is replaced by the second identifiers for parsing pur-
	    poses. The list of identifiers may be  supplied  directly  on  the
	    command line or read in from a separate file. If the first charac-
	    ter	of identifier-list is '@', '.' or a pathname separator ('/' or
	    '\'),  or  the  first  two characters specify a drive letter (e.g.
	    "C:"), the parameter identifier-list  will	be  interpreted	 as  a
	    filename  from  which to read a list of identifiers, one per input
	    line. Otherwise, identifier-list is	 a  list  of  identifiers  (or
	    identifier pairs) to be specially handled, each delimited by a ei-
	    ther a comma or by white space (in which case the list  should  be
	    quoted to keep the entire list as one command line argument). Mul-
	    tiple -I options may be supplied.  To clear	 the  list  of	ignore
	    identifiers, supply	a single dash ("-") for	identifier-list.

	    This feature is useful when	preprocessor macros are	used in	such a
	    way	that they cause	syntactic confusion due	to their presence. In-
	    deed,  this	is the best way	of working around a number of problems
	    caused by the presence of syntax-busting macros  in	 source	 files
	    (see CAVEATS, 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 in-
	    terpreted to be the	name of	the function instead  of  the  correct
	    name  of  "foo". Specifying	-I ARGDECL4 results in the correct be-
	    havior.

	       /* creates an RCS version string	in module */
	       MODULE_VERSION("$Revision: 690 $")

	    In the above example the macro invocation looks too	 much  like  a
	    function definition	because	it is not followed by a	semicolon (in-
	    deed, it could even	be followed by a  global  variable  definition
	    that  would	look much like a K&R style function parameter declara-
	    tion). In fact, this seeming function  definition  could  possibly
	    even cause the rest	of the file to be 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 ex-
	    pands 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++ key-
	    word "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  gen-
	    erated.   If  file	is  specified as "-", then file	names are read
	    from standard input. File names read using this  option  are  pro-
	    cessed following file names	appearing on the command line. Options
	    are	also accepted in this input. If	this option is specified  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  non-
	    trailing white space is considered significant, in order that file
	    names containing spaces may	be supplied (however,  trailing	 white
	    space  is  stripped	 from  lines); 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.

       -w   This option	is silently ignored  for  backward-compatibility  with
	    the	ctags of SVR4 Unix.

       -x   Print  a  tabular,	human-readable	cross reference	(xref) file to
	    standard output instead of generating a tag	file. The  information
	    contained  in  the output includes:	the tag	name; the kind of tag;
	    the	line number, file name,	and  source  line  (with  extra	 white
	    space condensed) of	the file which defines the tag.	No tag file is
	    written and	all options affecting tag file output will be ignored.
	    Example  applications for this feature are generating a listing of
	    all	functions located in a source file (e.g. ctags -x  --c-kinds=f
	    file), or generating a list	of all externally visible global vari-
	    ables  located  in	a  source  file	 (e.g.	ctags  -x  --c-kinds=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 re-
	    place 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'  capabil-
	    ity	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	directories. This  op-
	    tion 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	compiler, then
	    pattern may	contain	the usual shell	wildcards (not regular expres-
	    sions)  common  on	Unix (be sure to quote the option parameter to
	    protect the	wildcards from being expanded by the shell before  be-
	    ing	 passed	 to  ctags; also be aware that wildcards can match the
	    slash character, '/'). You can determine if	 shell	wildcards  are
	    available  on  your	platform by examining the output of the	--ver-
	    sion 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	 "CVS",	 which
	    are	 names	of directories for which it is generally not desirable
	    to descend while processing	the --recurse option.

       --excmd=type
	    Determines the type	of EX command  used  to	 locate	 tags  in  the
	    source file.  [Ignored in etags mode]

	    The	 valid	values	for  type (either the entire word or the first
	    letter is accepted)	are:

	    number   Use only line numbers in the tag file for 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 content. In pattern mode, du-
			 plicate entries are dropped because the  search  pat-
			 terns	they generate are identical, making the	dupli-
			 cate 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.	 Basi-
		     cally,  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 ig-
		     nored: -BF.

	    pattern  Use only search patterns for all tags,  rather  than  the
		     line numbers usually used for macro definitions. This has
		     the advantage of not referencing  obsolete	 line  numbers
		     when  lines have been added or removed since the tag file
		     was generated.

	    mixed    In	this mode, patterns are	generally used with a few  ex-
		     ceptions.	For C, line numbers are	used for macro defini-
		     tion 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 generally identical, making pattern searches  useless
		     for finding all matches.

       --extra=[+|-]flags
	    Specifies  whether	to include extra tag entries for certain kinds
	    of information. The	parameter flags	is a set of one-letter	flags,
	    each  representing	one  kind of extra tag entry to	include	in the
	    tag	file. If flags is preceded by by either	the '+'	or '-' charac-
	    ter,  the  effect of each flag is added to,	or removed from, those
	    currently enabled; otherwise the flags replace  any	 current  set-
	    tings. The meaning of each flag is as follows:

	       f   Include  an	entry  for  the	base file name of 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  lan-
		   guage  from which the tag was derived (using	a form that is
		   most	natural	for how	qualified calls	are specified  in  the
		   language).  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 oc-
		   currences of	a tag name occur in the	tag file.  Note,  how-
		   ever, that this could potentially 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 parameter flags  is	a  set	of  one-letter
	    flags,  each  representing one type	of extension field to include,
	    with the following meanings	 (disabled  by	default	 unless	 indi-
	    cated):

	       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 definition
	       s   Scope of tag	definition [enabled]
	       S   Signature of	routine	(e.g. prototype	or parameter list)
	       z   Include the "kind:" key in kind field
	       t   Type	 and name of a variable	or typedef as "typeref:" field
		   [enabled]

	    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 de-
	    fault set).	This option is ignored if the  option  --format=1  has
	    been specified. The	default	value of this option is	fkst.

       --file-scope[=yes|no]
	    Indicates  whether	tags  scoped only for a	single file (i.e. tags
	    which cannot be seen outside of the	file in	 which	they  are  de-
	    fined,  such  as  "static" tags) should be included	in the output.
	    See, also, the -h option. This option is enabled by	default.

       --filter[=yes|no]
	    Causes ctags to behave as a	filter,	reading	source file names from
	    standard  input  and  printing  their tags to standard output on a
	    file-by-file basis.	If --sorted is enabled,	tags are  sorted  only
	    within  the	 source	file in	which they are defined.	File names are
	    read from standard input in	line-oriented input mode (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 ap-
	    pear before	the first file name.

       --filter-terminator=string
	    Specifies  a string	to print to standard output following the tags
	    for	each file name parsed when the	--filter  option  is  enabled.
	    This  may permit an	application reading the	output of ctags	to de-
	    termine 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 sepa-
	    rated from the last	tag line for the file by its terminating  new-
	    line.  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-compati-
	    bility 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 description,  and  then
	    exits.

       --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 option  is
	    no.	 Note that this	indicates a preference only and	does not guar-
	    antee skipping code	within an "#if 0" branch, since	the  fall-back
	    algorithm used to generate tags when preprocessor conditionals are
	    too	complex	follows	all branches of	a conditional. This option  is
	    disabled by	default.

       --<LANG>-kinds=[+|-]kinds
	    Specifies  a list of language-specific kinds of tags (or kinds) to
	    include in the output file for a particular	language, where	<LANG>
	    is case-insensitive	and is one of the built-in language names (see
	    the	--list-languages option	for a complete	list).	The  parameter
	    kinds  is  a  group	 of one-letter flags designating kinds of tags
	    (particular	to the language) to either include or exclude from the
	    output.  The  specific sets	of flags recognized for	each language,
	    their meanings and defaults	may be list using the --list-kinds op-
	    tion.  Each	 letter	 or group of letters may be preceded by	either
	    '+'	to add it to, or '-' to	remove it from,	the  default  set.  In
	    the	absence	of any preceding '+' or	'-' sign, only those kinds ex-
	    plicitly 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-kinds=+px-d; to include only tags for
	    functions, use --c-kinds=f.

       --langdef=name
	    Defines a new user-defined language, name, to be parsed with regu-
	    lar	 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  the
	    --list-maps	option). Each comma-separated map consists of the lan-
	    guage  name	(either	a built-in or user-defined language), a	colon,
	    and	a list of file extensions and/or file name  patterns.  A  file
	    extension  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 sup-
	    port is available from the runtime library	of  your  C  compiler,
	    then  the  file name pattern may contain the usual shell wildcards
	    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  platform  by	examining  the output of the --version option,
	    which will include "+wildcards" in the compiled feature list; oth-
	    erwise,  the file name patterns are	matched	against	file names us-
	    ing	a simple textual comparison. When mapping a file extension, it
	    will first be unmapped from	any other languages.

	    If	the  first  character in a map is a plus sign, then the	exten-
	    sions and file name	patterns in that map will be appended  to  the
	    current map	for that language; otherwise, the map will replace the
	    current map. For example, to specify that only files  with	exten-
	    sions  of  .c  and	.x  are	to be treated as C language files, use
	    "--langmap=c:.c.x";	to also	add files with	extensions  of	.j  as
	    Java  language  files, specify "--langmap=c:.c.x,java:+.j".	To map
	    makefiles (e.g. files named	either "Makefile", "makefile", or hav-
	    ing	 the  extension	 ".mak")  to a language	called "make", specify
	    "--langmap=make:([Mm]akefile).mak".	 To map	files having no	exten-
	    sion,  specify  a  period  not  followed by	a non-period character
	    (e.g. ".", "..x", ".x."). To clear the mapping  for	 a  particular
	    language  (thus  inhibiting	 automatic generation of tags for that
	    language), specify an empty	extension list (e.g.   "--langmap=for-
	    tran:").  To  restore the default language mappings	for all	a par-
	    ticular language, supply the keyword "default"  for	 the  mapping.
	    To	specify	 restore  the  default	language mappings for all lan-
	    guages, specify "--langmap=default". Note that 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  lan-
	    guage  (case-insensitive;  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 automatically se-
	    lected (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 (case-in-
	    sensitive; either built-in or user-defined). If the	first language
	    of list is not preceded by either a	'+' or '-', the	 current  list
	    will  be  cleared before adding or removing	the languages in list.
	    Until a '-'	is encountered,	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, in-
	    cluding user-defined languages are enabled unless explicitly  dis-
	    abled  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	the --list-languages option for	a complete list	of the	built-
	    in language	names.

       --license
	    Prints  a  summary of the software license to standard output, and
	    then exits.

       --line-directives[=yes|no]
	    Specifies whether "#line" directives should	be  recognized.	 These
	    are	 present  in  the output of preprocessors 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 en-
	    abled, this	option will cause ctags	to generate tag	entries	marked
	    with  the  file names and line numbers of their locations original
	    source file(s), instead of their  actual  locations	 in  the  pre-
	    processor  output.	The actual file	names placed into the tag file
	    will have the same leading path  components	 as  the  preprocessor
	    output  file,  since  it is	assumed	that the original source files
	    are	located	relative to the	preprocessor output file  (unless,  of
	    course,  the #line directive specifies an absolute path). This op-
	    tion is off	by default. Note: This option is generally only	useful
	    when  used together	with the --excmd=number	(-n) option. Also, you
	    may	have to	use either the --langmap or --language-force option if
	    the	 extension  of	the  preprocessor  output file is not known to
	    ctags.

       --links[=yes|no]
	    Indicates whether symbolic links (if  supported)  should  be  fol-
	    lowed.  When  disabled, symbolic links are ignored.	This option is
	    on by default.

       --list-kinds[=language|all]
	    Lists the tag kinds	recognized for either the  specified  language
	    or all languages, and then exits. Each kind	of tag recorded	in the
	    tag	file is	represented by a one-letter flag, which	is  also  used
	    to	filter	the  tags  placed  into	 the output through use	of the
	    --<LANG>-kinds option. Note	that some languages and/or  tag	 kinds
	    may	be implemented using regular expressions and may not be	avail-
	    able if  regex  support  is	 not  compiled	into  ctags  (see  the
	    --regex-<LANG>  option).  Each  kind listed	is enabled unless fol-
	    lowed by "[off]".

       --list-maps[=language|all]
	    Lists the file extensions and file name patterns which associate a
	    file name with a language for either the specified language	or all
	    languages, and then	exits. See the --langmap  option,  and	SOURCE
	    FILES, above.

       --list-languages
	    Lists the names of the languages understood	by ctags, and then ex-
	    its.  These	language names are case	insensitive and	may be used in
	    the	   --language-force,	--languages,	--<LANG>-kinds,	   and
	    --regex-<LANG> options.

       --options=file
	    Read additional options from file. The file	should contain one op-
	    tion  per  line. As	a special case,	if --options=NONE is specified
	    as the first option	on the command line, it	will disable the auto-
	    matic  reading  of any configuration options from either a file or
	    the	environment (see FILES).

       --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 replace-
	    ment  pattern, similar in style to sed substitution	commands, with
	    which to generate tags from	source files mapped to the named  lan-
	    guage,  <LANG>,  (case-insensitive;	 either	a built-in or user-de-
	    fined language). The regular expression, regexp,  defines  an  ex-
	    tended  regular  expression	(roughly that used by egrep(1)), which
	    is used to locate a	single source line containing a	 tag  and  may
	    specify  tab characters using \t. When a matching line is found, a
	    tag	will be	generated for the name defined by  replacement,	 which
	    generally  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 ac-
	    tually be replaced by any character. Note that whichever separator
	    character  is  used	will have to be	escaped	with a backslash ('\')
	    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 specified
	    language  unless  the parameter is omitted,	in which case the cur-
	    rent list is cleared.

	    Unless modified by flags, regexp is	interpreted  as	 a  Posix  ex-
	    tended  regular  expression. The replacement should	expand for all
	    matching lines to a	non-empty string of characters,	or  a  warning
	    message  will  be  reported.  An  optional kind specifier for tags
	    matching regexp may	follow replacement, which will determine  what
	    kind  of  tag  is  reported	in the "kind" extension	field (see TAG
	    FILE FORMAT, below). The full form of kind-spec is in the form  of
	    a  single letter, a	comma, a name (without spaces),	a comma, a de-
	    scription, followed	by a separator,	which specify  the  short  and
	    long  forms	 of  the  kind value and its textual description (dis-
	    played using --list-kinds).	Either the kind	name  and/or  the  de-
	    scription  may be omitted. If kind-spec is omitted,	it defaults to
	    "r,regex". Finally,	flags are one or more single-letter characters
	    having the following effect	upon the interpretation	of regexp:

	       b   The pattern is interpreted as a Posix basic regular expres-
		   sion.

	       e   The pattern is interpreted as a Posix extended regular  ex-
		   pression (default).

	       i   The	regular	expression is to be applied in a case-insensi-
		   tive	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 support for regular expressions  is  compiled
	    in by examining the	output of the --version	option,	which will in-
	    clude "+regex" in the compiled feature list.

	    For	more information on the	regular	expressions 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 specifies	 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  tag  file
	    written during the current invocation of ctags. This option	is off
	    by default.	 This option must appear before	the first file name.

       --verbose[=yes|no]
	    Enable verbose mode. This prints out information  on  option  pro-
	    cessing  and a brief message describing what action	is being taken
	    for	each file considered by	ctags. Normally, ctags does  not  read
	    command  line arguments until after	options	are read from the con-
	    figuration files (see FILES,  below)  and  the  CTAGS  environment
	    variable.  However,	 if  this  option is the first argument	on the
	    command line, it will take effect before any options are read from
	    these sources. The default is no.

       --version
	    Prints a version identifier	for ctags to standard output, and then
	    exits. This	is guaranteed to always	contain	the string  "Exuberant
	    Ctags".

OPERATIONAL DETAILS
       As  ctags  considers  each file name in turn, it	tries to determine the
       language	of the file by applying	the following three tests in order: if
       the  file  extension  has  been	mapped to a language, if the file name
       matches a shell pattern mapped to a language, and finally if  the  file
       is  executable  and  its	 first line specifies an interpreter using the
       Unix-style "#!" specification (if supported on the platform). If	a lan-
       guage  was identified, the file is opened and then the appropriate lan-
       guage parser is called to operate  on  the  currently  open  file.  The
       parser  parses  through	the file and adds an entry to the tag file for
       each language object it is written to handle. See TAG FILE FORMAT,  be-
       low, for	details	on these entries.

       This  implementation  of	 ctags imposes no formatting requirements on C
       code as do  legacy  implementations.  Older  implementations  of	 ctags
       tended  to rely upon certain formatting assumptions in order to help it
       resolve coding dilemmas caused by preprocessor conditionals.

       In general, ctags tries to be smart about conditional preprocessor  di-
       rectives.  If a preprocessor conditional	is encountered within a	state-
       ment 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 fol-
       lowing example:

	      #ifdef TWO_ALTERNATIVES
	      struct {
	      #else
	      union {
	      #endif
		  short	a;
		  long b;
	      }

       Both branches cannot be followed, or braces become unbalanced and ctags
       would be	unable to make sense of	the syntax.

       If  the	application  of	this heuristic fails to	properly parse a file,
       generally due to	complicated and	inconsistent pairing within the	condi-
       tionals,	 ctags	will  retry the	file using a different heuristic which
       does not	selectively follow conditional preprocessor branches, but  in-
       stead  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 automatically ignored
       and the previous	name will be used.

       C++ operator definitions	are specially handled. In  order  for  consis-
       tency  with all types of	operators (overloaded and conversion), the op-
       erator name in the tag file will	always be preceded by the string  "op-
       erator  "  (i.e.	 even if the actual operator definition	was written as
       "operator<<").

       After creating or appending to the tag file, it is sorted  by  the  tag
       name, removing identical	tag lines.

TAG FILE FORMAT
       When  not running in etags mode,	each entry in the tag file consists of
       a separate line,	each looking like this in the most general case:

	tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields

       The fields and separators of these lines	are specified as follows:

	   1.  tag name
	   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	exten-
	       sion fields (described below) embedded in an EX comment immedi-
	       ately appended to the EX	command, which leaves it backward-com-
	       patible 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 general 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 visibility. 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>-kinds options above, or	a  full	 name.
		   It  is permitted (and is, in	fact, the default) for the key
		   portion of this field to be omitted.	The optional behaviors
		   are controlled with the --fields option.

       implementation
		   When	 present, this indicates a limited implementation (ab-
		   stract vs. concrete)	of a routine or	class, where value  is
		   specific  to	 the language ("virtual" or "pure virtual" for
		   C++;	"abstract" for Java).

       inherits	   When	present, value.	is a comma-separated list  of  classes
		   from	which this class is derived (i.e. inherits from).

       signature   When	 present, value	is a language-dependent	representation
		   of the signature of a routine. A routine signature  in  its
		   complete  form  specifies  the return type of a routine and
		   its formal argument list. This extension field is presently
		   supported  only  for	C-based	languages and does not include
		   the return type.

       In addition, information	on the scope of	 the  tag  definition  may  be
       available,  with	 the key portion equal to some language-dependent con-
       struct 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 cur-
       rent directory. Once the	tag file is built, the following commands  ex-
       ercise 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.

HOW TO USE WITH	NEDIT
       NEdit version 5.1 and later can handle the new extended tag file	format
       (see --format). To make NEdit use the tag file, select "File->Load Tags
       File". To jump to the definition	for a tag,  highlight  the  word,  the
       press  Ctrl-D. NEdit 5.1	can can	read multiple tag files	from different
       directories.  Setting the X resource nedit.tagFile to the name of a tag
       file  instructs	NEdit  to  automatically load that tag file at startup
       time.

CAVEATS
       Because ctags is	neither	a preprocessor nor a  compiler,	 use  of  pre-
       processor  macros can fool ctags	into either missing tags or improperly
       generating inappropriate	tags. Although ctags has been designed to han-
       dle  certain common cases, this is the single biggest cause of reported
       problems. 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.

       Note that since ctags generates 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 iden-
       tical  to  the  line  containing	 the tag. The following	example	demon-
       strates 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 parame-
       ter 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::func-
       tion"),	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 a C++ function is
       defined outside of the class declaration	(the usual case),  the	access
       specification  (i.e.  public, protected,	or private) and	implementation
       information (e.g. virtual, pure virtual)	contained in the function dec-
       laration	are not	known when the tag is generated	for the	function defi-
       nition.	It  will,   however   be   available   for   prototypes	  (e.g
       --c++-kinds=+p).

       No  qualified  tags are generated for language objects inherited	into a
       class.

ENVIRONMENT VARIABLES
       CTAGS   If this environment variable exists, it	will  be  expected  to
	       contain	a  set	of  default  options which are read when ctags
	       starts, after the configuration files listed in	FILES,	below,
	       are read, but before any	command	line options are read. Options
	       appearing on the	command	line will override  options  specified
	       in this variable. Only options will be read from	this variable.
	       Note that all white space in this variable is considered	a sep-
	       arator,	making	it impossible to pass an option	parameter con-
	       taining an embedded space. If this is a problem,	use a configu-
	       ration file instead.

       ETAGS   Similar	to  the	CTAGS variable above, this variable, if	found,
	       will be read when etags starts. If this variable	is not	found,
	       etags 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	tempo-
	       rary  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 only)
       .ctags
       ctags.cnf (on MSDOS, MSWindows only)
	      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 vari-
	      able is read or any command line options are read. This makes it
	      possible	to  set	 up  site-wide,	 personal or project-level de-
	      faults. It is possible to	compile	ctags to  read	an  additional
	      configuration  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  op-
	      tions  specified	in these files.	Only options will be read from
	      these files. Note	that the option	files are  read	 in  line-ori-
	      ented  mode in which spaces are significant (since shell quoting
	      is not possible).	Each line of the file is read as  one  command
	      line parameter (as if it were quoted with	single quotes).	There-
	      fore, use	new lines to indicate separate command-line arguments.

       tags   The default tag file created by ctags.

       TAGS   The default tag file created by etags.

SEE ALSO
       The official Exuberant Ctags web	site at:

	      http://ctags.sourceforge.net

       Also ex(1), vi(1), elvis, or, better yet, vim, the official  editor  of
       ctags. For more information on vim, see the VIM Pages web site at:

	      http://www.vim.org/

AUTHOR
       Darren Hiebert <dhiebert	at 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  fullness  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 <kirkenda@cs.pdx.edu> that comes with
       the Elvis vi clone (though virtually none  of  the  original  code  re-
       mains).

       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 others, 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.0			    EXCTAGS(1)

NAME | SYNOPSIS | DESCRIPTION | SOURCE FILES | OPTIONS | OPERATIONAL DETAILS | TAG FILE FORMAT | HOW TO USE WITH VI | HOW TO USE WITH GNU EMACS | HOW TO USE WITH NEDIT | CAVEATS | BUGS | ENVIRONMENT VARIABLES | FILES | SEE ALSO | AUTHOR | MOTIVATION | CREDITS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=exctags&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help