# ctags

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           ctags — create a tags file (**DEVELOPMENT** , **FORTRAN**)
    


## SYNOPSIS



           ctags **[** -a**] [** -f _tagsfile_**]**_pathname_...
    
           ctags -x _pathname_...
    


## DESCRIPTION



           The _ctags_ utility shall be provided on systems that support the
           the Software Development Utilities option, and either or both of
           the C-Language Development Utilities option and FORTRAN
           Development Utilities option. On other systems, it is optional.
    
           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.
    


## OPTIONS



           The _ctags_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following options shall be supported:
    
           **-a** Append to _tagsfile_.
    
           **-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
                     _tagsfile_ shall not be created when **-x** is specified.
    


## OPERANDS



           The following _pathname_ operands are supported:
    
           _file_**.c** Files with basenames ending with the **.c** suffix shall be
                     treated as C-language source code. Such files that are
                     not valid input to _c99_ produce unspecified results.
    
           _file_**.h** Files with basenames ending with the **.h** suffix shall be
                     treated as C-language source code. Such files that are
                     not valid input to _c99_ produce unspecified results.
    
           _file_**.f** Files with basenames ending with the **.f** suffix shall be
                     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-defined.
    


## STDIN



           See the INPUT FILES section.
    


## INPUT FILES



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


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _ctags_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_COLLATE_
                     Determine the order in which output is sorted for the **-x**
                     option. The POSIX locale determines the order in which
                     the _tagsfile_ is written.
    
           _LC_CTYPE_  Determine the locale for the interpretation of sequences
                     of bytes of text data as characters (for example,
                     single-byte 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 catalogs for the
                     processing of _LC_MESSAGES_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           The list of object name information produced by the **-x** option
           shall be 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



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           When the **-x** option is not specified, the format of the output file
           shall be:
    
               "%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> (**'^'**) 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.
    


## EXTENDED DESCRIPTION



           If the operand identifies C-language source, the _ctags_ utility
           shall 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 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:
    
            *  Subroutine definitions
    
            *  COMMON statements
    
            *  PARAMETER statements
    
            *  DATA and BLOCK DATA statements
    
            *  Statement numbers
    
           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.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## 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
           locale as that in effect when _ctags_ **-x** is run, results might not
           be as expected.
    
           The description of C-language processing says ``attempts to''
           because the C language can be greatly confused, especially through
           the use of **#define** s, 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.
    


## RATIONALE



           The option list was significantly reduced from that provided by
           historical implementations. The **-F** option was omitted as
           redundant, since it is the default. The **-B** option was omitted as
           being of very limited usefulness. The **-t** option was omitted since
           the recognition of **typedef** s is now required for C source files.
           The **-u** option was omitted because the update function was judged
           to be not only inefficient, but also rarely needed.
    
           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:
    
           **-v** If the **-v** flag is given, an index of the form expected
                     by _vgrind_ is produced on the standard output. This
                     listing contains the function name, filename, and page
                     number (assuming 64-line pages). Since the output is
                     sorted into lexicographic order, it may be desired to
                     run the output through _sort_ **-f**.  Sample use:
    
                         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.
    


## FUTURE DIRECTIONS



           None.
    


* * *