CTAGS(1) General Commands Manual CTAGS(1)

ctags — create a tags file (DEVELOPMENT, FORTRAN)

ctags [-a][-f tagsfile] pathname ...

ctags -x pathname ...

The ctags utility creates a tags file or an index of objects from C-language or FORTRAN source files specified by the pathname operands. (FORTRAN source is processed only on systems supporting the FORTRAN option.) The tags file lists the locators of language-specific objects within the source files. A locator consists of a name, pathname and either basic regular expression or a line number that can be used in searching for the object definition. The objects that will be recognised are specified in the EXTENDED DESCRIPTION section.

The ctags utility supports the XBD specification, .

The following options are supported:

Append to tags file.
Write the object locator lists into tagsfile instead of the default file named tags in the current directory.
Produce a list of object names, the line number and filename in which each is defined, as well as the text of that line, and write this to the standard output. A tags file is not created when -x is specified.

The following pathname operands are supported:

Files with basenames ending with the .c suffix are treated as C-language source code. Such files that are not valid input to c89(1) produce unspecified results.
Files with basenames ending with the .h suffix are treated as C-language source code. Such files that are not valid input to c89(1) produce unspecified results.
Files with basenames ending with the .f suffix are treated as FORTRAN-language source code. Such files that are not valid input to fort77(1) produce unspecified results.

The handling of other files is implementation-dependent.

See the INPUT FILES section.

The input files must be text files containing source code in the language indicated by the operand filename suffixes.

The following environment variables affect the execution of ctags :

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
If set to a non-empty string value, override the values of all the other internationalisation variables.
Determine the order in which output is sorted for the -x option. The POSIX locale determines the order in which the tags file is written.
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files). When processing C-language source code, if the locale is not compatible with the C locale described by the ISO C standard, the results are unspecified.
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
Determine the location of message catalogues for the processing of LC_MESSAGES .

Default.

The list of object name information produced by the -x option is written to standard output in the following format:

"%s %d %s %s", <object-name>, <line-number>, <filename>, <text> where < > is the text of line < > of file < filename >.

Used only for diagnostic messages.

When the -x option is not specified, the format of the output file is:

"%s\t%s\t/%s/\n", <identifier>, <filename>, <rexp> where < > is a basic regular expression (see the specification, re(7) ) 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 section).

An alternative format is:

"%s\t%s\t%d\n", <identifier>, <filename>, <lineno> where < > is a decimal line number that could be used by an editor to find < identifier > in < filename >. This alternative format is not produced by ctags when it is used as described by this specification, but the standard utilities that process tags files are able to process this format as well as the preceding one.

In either format, the file will be sorted by identifier, based on the collation sequence in the POSIX locale.

If the operand identifies C-language source, the ctags utility will attempt to produce an output line for each of the following objects:

  • function definitions
  • type definitions
  • macros with arguments.

It may also produce output for any of the following objects:

  • function prototypes
  • structures
  • unions
  • global variable definitions
  • enumeration types
  • macros without arguments
  • #define statements
  • #line statements.

Any and statements will produce no output. The tag main is treated specially in C programs. The tag formed is created by prefixing to the name of the file, with the trailing , and leading pathname components (if any) removed. This special treatment of main makes the use of ctags practical in directories with more than one program.

If the operand identifies FORTRAN source, the ctags utility will produce an output line for each function definition. It may also produce output for any of the following objects:

  • subroutine definitions
  • COMMON statements
  • PARAMETER statements
  • DATA and BLOCK DATA statements
  • statement numbers.

On systems that do not support the FORTRAN option, ctags produces unspecified results for FORTRAN source code files. It writes to standard error a message identifying this condition and causes a non-zero exit status to be produced.

It is implementation-dependent what other objects (including duplicate identifiers) produce output.

The following exit values are returned:

Successful completion.
An error occurred.

Default.

The output with -x is meant to be a simple index that can be written out as an off-line readable function index. If the input files to ctags (such as .c files) were not created using the same locales as those in effect when ctags -x is run, results might not be as expected.

The description of C-language processing says "will attempt to" because the C language can be greatly confused, especially through the use of , 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.

None.

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

c89(1) , fort77(1) , vi(1) .

February 1997 posix.fail