CTAGS(1)                   POSIX Programmer's Manual                  CTAGS(1)



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

NNAAMMEE
       ctags -- create a tags file (DDEEVVEELLOOPPMMEENNTT, FFOORRTTRRAANN)

SSYYNNOOPPSSIISS
       ctags [[-a]] [[-f _t_a_g_s_f_i_l_e]] _p_a_t_h_n_a_m_e...

       ctags -x _p_a_t_h_n_a_m_e...

DDEESSCCRRIIPPTTIIOONN
       The _c_t_a_g_s 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 _c_t_a_g_s utility shall write a _t_a_g_s_f_i_l_e or an index of objects from C-
       language or FORTRAN source files specified by the _p_a_t_h_n_a_m_e operands.
       The _t_a_g_s_f_i_l_e 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.

OOPPTTIIOONNSS
       The _c_t_a_g_s utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

       --aa        Append to _t_a_g_s_f_i_l_e.

       --ff _t_a_g_s_f_i_l_e
                 Write the object locator lists into _t_a_g_s_f_i_l_e instead of the
                 default file named ttaaggss in the current directory.

       --xx        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 _t_a_g_s_f_i_l_e shall not
                 be created when --xx is specified.

OOPPEERRAANNDDSS
       The following _p_a_t_h_n_a_m_e operands are supported:

       _f_i_l_e..cc    Files with basenames ending with the ..cc suffix shall be
                 treated as C-language source code. Such files that are not
                 valid input to _c_9_9 produce unspecified results.

       _f_i_l_e..hh    Files with basenames ending with the ..hh suffix shall be
                 treated as C-language source code. Such files that are not
                 valid input to _c_9_9 produce unspecified results.

       _f_i_l_e..ff    Files with basenames ending with the ..ff suffix shall be
                 treated as FORTRAN-language source code. Such files that are
                 not valid input to _f_o_r_t_7_7 produce unspecified results.

       The handling of other files is implementation-defined.

SSTTDDIINN
       See the INPUT FILES section.

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

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of
       _c_t_a_g_s:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_O_L_L_A_T_E
                 Determine the order in which output is sorted for the --xx
                 option. The POSIX locale determines the order in which the
                 _t_a_g_s_f_i_l_e is written.

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

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

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       The list of object name information produced by the --xx option shall be
       written to standard output in the following format:


           "%s %d %s %s", <_o_b_j_e_c_t_-_n_a_m_e>, <_l_i_n_e_-_n_u_m_b_e_r>, <_f_i_l_e_n_a_m_e>, <_t_e_x_t>

       where <_t_e_x_t> is the text of line <_l_i_n_e_-_n_u_m_b_e_r> of file <_f_i_l_e_n_a_m_e>.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       When the --xx option is not specified, the format of the output file
       shall be:


           "%s\t%s\t/%s/\n", <_i_d_e_n_t_i_f_i_e_r>, <_f_i_l_e_n_a_m_e>, <_p_a_t_t_e_r_n>

       where <_p_a_t_t_e_r_n> is a search pattern that could be used by an editor to
       find the defining instance of <_i_d_e_n_t_i_f_i_e_r> in <_f_i_l_e_n_a_m_e> (where
       _d_e_f_i_n_i_n_g _i_n_s_t_a_n_c_e is indicated by the declarations listed in the
       EXTENDED DESCRIPTION).

       An optional <circumflex> (''^^'') can be added as a prefix to <_p_a_t_t_e_r_n>,
       and an optional <dollar-sign> can be appended to <_p_a_t_t_e_r_n> to indicate
       that the pattern is anchored to the beginning (end) of a line of text.
       Any <slash> or <backslash> characters in <_p_a_t_t_e_r_n> 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", <_i_d_e_n_t_i_f_i_e_r>, <_f_i_l_e_n_a_m_e>, <_p_a_t_t_e_r_n>

       which is identical to the first format except that <slash> characters
       in <_p_a_t_t_e_r_n> shall not be preceded by escaping <backslash> characters,
       and <question-mark> characters in <_p_a_t_t_e_r_n> shall be preceded by
       <backslash> characters.

       A second alternative format is:


           "%s\t%s\t%d\n", <_i_d_e_n_t_i_f_i_e_r>, <_f_i_l_e_n_a_m_e>, <_l_i_n_e_n_o>

       where <_l_i_n_e_n_o> is a decimal line number that could be used by an editor
       to find <_i_d_e_n_t_i_f_i_e_r> in <_f_i_l_e_n_a_m_e>.

       Neither alternative format shall be produced by _c_t_a_g_s 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.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       If the operand identifies C-language source, the _c_t_a_g_s 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

        *  ##ddeeffiinnee statements

        *  ##lliinnee statements

       Any ##iiff and ##iiffddeeff statements shall produce no output. The tag mmaaiinn is
       treated specially in C programs. The tag formed shall be created by
       prefixing MM to the name of the file, with the trailing ..cc, and leading
       pathname components (if any) removed.

       On systems that do not support the C-Language Development Utilities
       option, _c_t_a_g_s 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 _c_t_a_g_s 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, _c_t_a_g_s 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.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The output with --xx is meant to be a simple index that can be written
       out as an off-line readable function index. If the input files to _c_t_a_g_s
       (such as ..cc files) were not created using the same locale as that in
       effect when _c_t_a_g_s --xx 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
       ##ddeeffiinnees, and this utility would be of no use if the real C
       preprocessor were run to identify them. The output from _c_t_a_g_s may be
       fooled and incorrect for various constructs.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       The option list was significantly reduced from that provided by
       historical implementations. The --FF option was omitted as redundant,
       since it is the default. The --BB option was omitted as being of very
       limited usefulness. The --tt option was omitted since the recognition of
       ttyyppeeddeeffs is now required for C source files. The --uu option was omitted
       because the update function was judged to be not only inefficient, but
       also rarely needed.

       An early proposal included a --ww 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 _L_C___C_T_Y_P_E 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 _L_C___C_O_L_L_A_T_E
       because it is typically not used by human readers, but only by programs
       such as _v_i to locate the tag within the source files. Using the POSIX
       locale eliminates some of the problems of coordinating locales between
       the _c_t_a_g_s file creator and the _v_i file reader.

       Historically, the tags file has been used only by _e_x and _v_i.  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 _v_i
       recognizes either. The _c_t_a_g_s 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 _l_e_x and _y_a_c_c.  The _c_t_a_g_s utility is not required to
       accommodate these languages, although implementors are encouraged to do
       so.

       The following historical option was not specified, as _v_g_r_i_n_d is not
       included in this volume of POSIX.1-2017:

       --vv        If the --vv flag is given, an index of the form expected by
                 _v_g_r_i_n_d 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 _s_o_r_t --ff.  Sample use:


                     ctags -v files | sort -f > index vgrind -x index

       The special treatment of the tag mmaaiinn makes the use of _c_t_a_g_s practical
       in directories with more than one program.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_9_9, _f_o_r_t_7_7, _v_i

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       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 .



IEEE/The Open Group                  2017                             CTAGS(1)
