NAME

ctags - create a tags file (DEVELOPMENT, FORTRAN)

 SYNOPSIS

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

ctags -x pathname ...

 DESCRIPTION

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.

 OPTIONS

The ctags utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-a

Append to tags file.

-f tagsfile

Write the object locator lists into tagsfile instead of the default file named tags in the current directory.

-x

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.

 OPERANDS

The following pathname operands are supported:

file.c

Files with basenames ending with the .c suffix are treated as C-language source code. Such files that are not valid input to c89 produce unspecified results.

file.h

Files with basenames ending with the .h suffix are treated as C-language source code. Such files that are not valid input to c89 produce unspecified results.

file.f

Files with basenames ending with the .f suffix are treated as FORTRAN-language source code. Such files that are not valid input to fort77 produce unspecified results.

The handling of other files is implementation-dependent.

 STDIN

See the INPUT FILES section.

 INPUT FILES

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

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of ctags:

LANG

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.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_COLLATE

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.

LC_CTYPE

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.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

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 <text> is the text of line <line-number> of file <filename>.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

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

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

 EXTENDED DESCRIPTION

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 #if and #ifdef statements will produce no output. The tag main is treated specially in C programs. The tag formed is created by prefixing M to the name of the file, with the trailing .c, 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.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

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

 EXAMPLES

None.

 FUTURE DIRECTIONS

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.

 SEE ALSO

c89, fort77, vi.