👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

RedHat 9 (Linux i386) - man page for ctags (redhat section 1)

CTAGS(1)										 CTAGS(1)

NAME
       ctags - Generate tag files for source code

SYNOPSIS
       ctags [options] [file(s)]

       etags [options] [file(s)]

DESCRIPTION
       The  ctags 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 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 lan-
       guages. 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
       Unless the --language-force option is specified, the language of each source file is auto-
       matically selected based upon a mapping of file names to  languages.  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 recognized
       language.  File	names are mapped to languages according to the following default mappings
       (which may be overridden with the --langmap option):

	   Assembler
		    *.asm *.ASM *.[sS] *.A51 *.29[kK] *.[68][68][kKsSxX] *.[xX][68][68]
	   ASP	    *.asp *.asa
	   Awk	    *.awk
	   C	    *.c
	   C++	    *.C *.c++ *.cc *.cpp *.cxx *.h *.H *.hh *.hpp *.hxx *.h++
	   BETA     *.bet
	   Cobol    *.cbl *.cob *.CBL *.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
	   PL/SQL   *.sql
	   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
	   Vera     *.vr *.vri *.vrh
	   Verilog  *.v
	   Vim	    *.vim
	   YACC/Bison
		    *.y

       By default, all other files names are ignored. This permits running ctags on all files  in
       either  a  single  directory  (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.

       Note  also that the boolean parameters to the long form options (those beginning with "--"
       and that take a "[=yes|no]" parameter) may be omitted, 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 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 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 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 otherwise overwrite
	    your first C file with the tags generated 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 specified 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 inter-
	    preted as include (or header) files. To indicate files having  no  extension,  use	a
	    period  not  followed by a non-period 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 lan-
	    guage. Any tag which is located in a non-include file and cannot be seen (e.g. linked
	    to) from another 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, 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
	    --language-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 suf-
	    fixed with a '+' character, ctags will also ignore any parenthesis-enclosed  argument
	    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 argument). 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 confusion 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  instead of the correct name of "foo". Specifying -I ARGDECL4
	    results in the correct behavior.

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

	    In the above example the macro invocation looks too much like a  function  definition
	    because  it  is  not  followed by a semicolon (indeed, it could even be followed by a
	    global variable definition that would look much like a K&R style  function	parameter
	    declaration). 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. Specify-
	    ing -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 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 spaces are considered significant, in order that file  names  con-
	    taining 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.

       -w   This option is silently ignored for backwards 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  writ-
	    ten  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-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 directories. This option may be specified
	    as many times as desired. For each file name considered by ctags, each pattern speci-
	    fied  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 pat-
	    terns  which  match  a given file name irrespective of its path, or match only a spe-
	    cific 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 being passed to ctags; also be aware that
	    wildcards can match the slash character, '/'). 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 compiled feature 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, 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  cor-
		     respond  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 advantage of not referencing obso-
		     lete 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 exceptions. For C, line
		     numbers are used for macro definition tags. This was the default format gen-
		     erated  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  '-'
	    character,	the  effect  of  each  flag is added to, or removed from, those currently
	    enabled; otherwise the flags replace any current settings. The meaning of  each  flag
	    is as follows:

	       f   Include  an	entry  for  the base file name of every source file (e.g.  "exam-
		   ple.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  occurrances  of	a
		   tag	name  occur  in  the tag file. Note, however, 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 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]
	       s   Signature of routine (e.g. prototype or parameter list)
	       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]
	    Indicates  whether tags scoped only for a single file (i.e. tags which cannot be seen
	    outside of the file in which they are defined,  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 output in line-oriented input	mode  (see  note  for  -L
	    option)  and  only	after file names listed on the command line or from any file sup-
	    plied 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 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 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 ter-
	    minating 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 back-
	    ward compatibility 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.

       --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 complex follows  all  branches  of	a
	    conditional. This option is disabled by default.

       --<LANG>-types=[+|-]kinds
	    Specifies a list of language-specific kinds of tags (or kinds) to include in the out-
	    put file for a particular language, where <LANG> is  one  of  the  built-in  language
	    names  (see TAG KINDS, below, 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 is described in TAG KINDS, below.  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  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 consists 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
	    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]ake-
	    file)").  If appropriate support is available from the runtime library of your C com-
	    piler, 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 wild-
	    cards  are available on your platfom by examining the output of the --version option,
	    which will include "+wildcards" in the compiled 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	language;  other-
	    wise,  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  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 "Make-
	    file", "makefile", or having the extension ".mak") to a language called "make", spec-
	    ify "--langmap=make:([Mm]akefile).mak".  To map files having no extension, 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=fortran:"). To
	    restore the default language mappings for all a particular language, supply the  key-
	    word "default" for the mapping.  To specify restore the default language mappings for
	    all languages, 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 language (either built-in or user-defined) to be used for every
	    supplied file instead of automatically selecting the language based upon  its  exten-
	    sion. In addition, the special value auto indicates that the language should be auto-
	    matically 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
	    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,
	    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  previ-
	    ously 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 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  enabled,  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 preprocessor 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  abso-
	    lute path). This option 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  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, simi-
	    lar 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 lan-
	    guage). The regular  expression,  regexp,  defines	an  extended  regular  expression
	    (roughly  that  used  by egrep(1)), which is used to locate a single source line con-
	    taining 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 actually be replaced by any character. Note that whichever separator char-
	    acter 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 current list is
	    cleared.

	    Unless  modified  by flags, regexp is interpreted as a Posix extended regular expres-
	    sion. 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 kind-spec is
	    expected to be in the form of a single letter, a comma, and a name followed by a sep-
	    arator,  which  specify  the  short and long forms of the kind value. 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 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 regu-
	    lar 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 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 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 ignore-
	    case"). 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	processing  and  a  brief
	    message describing what action is being taken for each file considered by ctags. Nor-
	    mally, ctags does not read command line arguments until after options are  read  from
	    the  configuration	files (see FILES, below) and the CTAGS environment variable. How-
	    ever, 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. 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  filter  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
	    f	function definitions
	    g	enumeration names
	    m	class, struct, or union members
	    n	namespaces
	    p	function prototypes and declarations [off]
	    s	structure names
	    t	typedefs
	    u	union names
	    v	variable definitions
	    x	extern and forward variable declarations [off]

       Cobol
	    d	data items
	    f	file descriptions (FD, SD, RD)
	    g	group items
	    p	paragraphs
	    P	program ids
	    s	sections

       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

       PHP
	    c	classes
	    f	functions

       Python
	    c	classes
	    f	functions

       REXX
	    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

       SQL
	    c	cursors
	    d	prototypes
	    f	functions
	    F	record fields
	    l	local variables
	    P	packages
	    p	procedures
	    r	records
	    s	subtypes
	    t	tables
	    T	triggers
	    v	variables

       Tcl
	    p	procedures

       Vera
	    c	class
	    d	macro
	    e	enumerator
	    f	function
	    g	enum
	    m	member
	    p	program
	    P	prototype
	    t	task
	    T	typedef
	    v	variable
	    x	externvar

       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 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 language was identified, the  file
       is  opened  and then the appropriate language 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, below, 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  condition-
       als.

       In  general,  ctags tries to be smart about conditional preprocessor directives. If a pre-
       processor 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 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 com-
       plicated and inconsistent pairing within the conditionals, ctags will retry the file using
       a different heuristic which does not selectively 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  paren-
       theses 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 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  writ-
       ten as "operator<<").

       After  creating or appending to the tag file, it is sorted by the tag name, removing iden-
       tical 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 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, however, 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 possible 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  corre-
		   sponding value.

       kind	   Indicates  the  type,  or  kind, of tag. Its value is either one of the corre-
		   sponding 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 omitted. The optional behaviors are controlled
		   with the --fields option.

       implementation
		   When  present, this indicates a limited implementation (abstract 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 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 look-
       ing 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.

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 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 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.

       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 exam-
       ple 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 func-
       tion 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 func-
       tion had when declared in the class is not known.

       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 in considered a separator, 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 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 speci-
	       fies  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 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 options  specified	in  these  files.
	      Only  options will be read from these files. Note that the option files are read in
	      line-oriented mode in which spaces are significant (since shell quoting is not pos-
	      sible).  Each line of the file is read as one command line parameter (as if it were
	      quoted with single quotes). Therefore, 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@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  virtu-
       ally 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 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.4					 CTAGS(1)


All times are GMT -4. The time now is 10:59 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?