ctags [-a] [-f tagsfile] pathname... ctags -x pathname...
The ctags utility shall write a tagsfile or an index of objects from C-language or FORTRAN source files specified by the pathname operands. The tagsfile shall list the locators of language-specific objects within the source files. A locator consists of a name, pathname, and either a search pattern or a line number that can be used in searching for the object definition. The objects that shall be recognized are specified in the EXTENDED DESCRIPTION section.
The following options shall be supported:
The handling of other files is implementation-defined.
"%s %d %s %s", <object-name>, <line-number>, <filename>, <text>
where <text> is the text of line <line-number> of file <filename>.
"%s\t%s\t/%s/\n", <identifier>, <filename>, <pattern>
where <pattern> is a search pattern that could be used by an editor to find the defining instance of <identifier> in <filename> (where defining instance is indicated by the declarations listed in the EXTENDED DESCRIPTION).
An optional
<circumflex>
('ha')
can be added as a prefix to <pattern>, and an optional
<dollar-sign>
can be appended to <pattern> to indicate that the pattern is
anchored to the beginning (end) of a line of text. Any
<slash>
or
<backslash>
characters in <pattern> shall be preceded by a
<backslash>
character. The anchoring
<circumflex>,
<dollar-sign>,
and escaping
<backslash>
characters shall not be considered part of the search pattern. All other
characters in the search pattern shall be considered literal characters.
An alternative format is:
"%s\t%s\t?%s?\n", <identifier>, <filename>, <pattern>
which is identical to the first format except that <slash> characters in <pattern> shall not be preceded by escaping <backslash> characters, and <question-mark> characters in <pattern> shall be preceded by <backslash> characters.
A second alternative format is:
"%s\t%s\t%d\n", <identifier>, <filename>, <lineno>
where <lineno> is a decimal line number that could be used by an editor to find <identifier> in <filename>.
Neither alternative format shall be produced by ctags when it is used as described by POSIX.1-2008, but the standard utilities that process tags files shall be able to process those formats as well as the first format.
In any of these formats, the file shall be sorted by identifier, based on the collation sequence in the POSIX locale.
It may also produce output for any of the following objects:
Any #if and #ifdef statements shall produce no output. The tag main is treated specially in C programs. The tag formed shall be created by prefixing M to the name of the file, with the trailing .c, and leading pathname components (if any) removed.
On systems that do not support the C-Language Development Utilities option, ctags produces unspecified results for C-language source code files. It should write to standard error a message identifying this condition and cause a non-zero exit status to be produced.
If the operand identifies FORTRAN source, the ctags utility shall produce an output line for each function definition. It may also produce output for any of the following objects:
On systems that do not support the FORTRAN Development Utilities option, ctags produces unspecified results for FORTRAN source code files. It should write to standard error a message identifying this condition and cause a non-zero exit status to be produced.
It is implementation-defined what other objects (including duplicate identifiers) produce output.
The following sections are informative.
The description of C-language processing says ``attempts to'' because the C language can be greatly confused, especially through the use of #defines, and this utility would be of no use if the real C preprocessor were run to identify them. The output from ctags may be fooled and incorrect for various constructs.
An early proposal included a -w option to suppress warning diagnostics. Since the types of such diagnostics could not be described, the option was omitted as being not useful.
The text for LC_CTYPE about compatibility with the C locale acknowledges that the ISO C standard imposes requirements on the locale used to process C source. This could easily be a superset of that known as ``the C locale'' by way of implementation extensions, or one of a few alternative locales for systems supporting different codesets. No statement is made for FORTRAN because the ANSI X3.9-1978 standard (FORTRAN 77) does not (yet) define a similar locale concept. However, a general rule in this volume of POSIX.1-2017 is that any time that locales do not match (preparing a file for one locale and processing it in another), the results are suspect.
The collation sequence of the tags file is not affected by LC_COLLATE because it is typically not used by human readers, but only by programs such as vi to locate the tag within the source files. Using the POSIX locale eliminates some of the problems of coordinating locales between the ctags file creator and the vi file reader.
Historically, the tags file has been used only by ex and vi. However, the format of the tags file has been published to encourage other programs to use the tags in new ways. The format allows either patterns or line numbers to find the identifiers because the historical vi recognizes either. The ctags utility does not produce the format using line numbers because it is not useful following any source file changes that add or delete lines. The documented search patterns match historical practice. It should be noted that literal leading <circumflex> or trailing <dollar-sign> characters in the search pattern will only behave correctly if anchored to the beginning of the line or end of the line by an additional <circumflex> or <dollar-sign> character.
Historical implementations also understand the objects used by the languages Pascal and sometimes LISP, and they understand the C source output by lex and yacc. The ctags utility is not required to accommodate these languages, although implementors are encouraged to do so.
The following historical option was not specified, as vgrind is not included in this volume of POSIX.1-2017:
ctags -v files | sort -f > index vgrind -x index
The special treatment of the tag main makes the use of ctags practical in directories with more than one program.
The Base Definitions volume of POSIX.1-2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines
Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .