1CTAGS(1P) POSIX Programmer's Manual CTAGS(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 ctags — create a tags file (DEVELOPMENT, FORTRAN)
14
16 ctags [−a] [−f tagsfile] pathname...
17 ctags −x pathname...
19
21 The ctags utility shall be provided on systems that support the the
22 Software Development Utilities option, and either or both of the C-Lan‐
23 guage Development Utilities option and FORTRAN Development Utilities
24 option. On other systems, it is optional.
25 The ctags utility shall write a tagsfile or an index of objects from C-
27 language or FORTRAN source files specified by the pathname operands.
28 The tagsfile shall list the locators of language-specific objects
29 within the source files. A locator consists of a name, pathname, and
30 either a search pattern or a line number that can be used in searching
31 for the object definition. The objects that shall be recognized are
32 specified in the EXTENDED DESCRIPTION section.
33
35 The ctags utility shall conform to the Base Definitions volume of
36 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
37 The following options shall be supported:
39 −a Append to tagsfile.
41 −f tagsfile
43 Write the object locator lists into tagsfile instead of the
44 default file named tags in the current directory.
45 −x Produce a list of object names, the line number, and filename
47 in which each is defined, as well as the text of that line,
48 and write this to the standard output. A tagsfile shall not
49 be created when −x is specified.
50
52 The following pathname operands are supported:
53 file.c Files with basenames ending with the .c suffix shall be
55 treated as C-language source code. Such files that are not
56 valid input to c99 produce unspecified results.
57 file.h Files with basenames ending with the .h suffix shall be
59 treated as C-language source code. Such files that are not
60 valid input to c99 produce unspecified results.
61 file.f Files with basenames ending with the .f suffix shall be
63 treated as FORTRAN-language source code. Such files that are
64 not valid input to fort77 produce unspecified results.
65 The handling of other files is implementation-defined.
67
69 See the INPUT FILES section.
70
72 The input files shall be text files containing source code in the lan‐
73 guage indicated by the operand filename suffixes.
74
76 The following environment variables shall affect the execution of
77 ctags:
78 LANG Provide a default value for the internationalization vari‐
80 ables that are unset or null. (See the Base Definitions vol‐
81 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
82 ables for the precedence of internationalization variables
83 used to determine the values of locale categories.)
84 LC_ALL If set to a non-empty string value, override the values of
86 all the other internationalization variables.
87 LC_COLLATE
89 Determine the order in which output is sorted for the −x
90 option. The POSIX locale determines the order in which the
91 tagsfile is written.
92 LC_CTYPE Determine the locale for the interpretation of sequences of
94 bytes of text data as characters (for example, single-byte as
95 opposed to multi-byte characters in arguments and input
96 files). When processing C-language source code, if the locale
97 is not compatible with the C locale described by the ISO C
98 standard, the results are unspecified.
99 LC_MESSAGES
101 Determine the locale that should be used to affect the format
102 and contents of diagnostic messages written to standard
103 error.
104 NLSPATH Determine the location of message catalogs for the processing
106 of LC_MESSAGES.
107
109 Default.
110
112 The list of object name information produced by the −x option shall be
113 written to standard output in the following format:
114 "%s %d %s %s", <object-name>, <line-number>, <filename>, <text>
116 where <text> is the text of line <line-number> of file <filename>.
118
120 The standard error shall be used only for diagnostic messages.
121
123 When the −x option is not specified, the format of the output file
124 shall be:
125 "%s\t%s\t/%s/\n", <identifier>, <filename>, <pattern>
127 where <pattern> is a search pattern that could be used by an editor to
129 find the defining instance of <identifier> in <filename> (where defin‐
130 ing instance is indicated by the declarations listed in the EXTENDED
131 DESCRIPTION).
132 An optional <circumflex> ('^') can be added as a prefix to <pattern>,
134 and an optional <dollar-sign> can be appended to <pattern> to indicate
135 that the pattern is anchored to the beginning (end) of a line of text.
136 Any <slash> or <backslash> characters in <pattern> shall be preceded by
137 a <backslash> character. The anchoring <circumflex>, <dollar-sign>, and
138 escaping <backslash> characters shall not be considered part of the
139 search pattern. All other characters in the search pattern shall be
140 considered literal characters.
141 An alternative format is:
143 "%s\t%s\t?%s?\n", <identifier>, <filename>, <pattern>
145 which is identical to the first format except that <slash> characters
147 in <pattern> shall not be preceded by escaping <backslash> characters,
148 and <question-mark> characters in <pattern> shall be preceded by <back‐
149 slash> characters.
150 A second alternative format is:
152 "%s\t%s\t%d\n", <identifier>, <filename>, <lineno>
154 where <lineno> is a decimal line number that could be used by an editor
156 to find <identifier> in <filename>.
157 Neither alternative format shall be produced by ctags when it is used
159 as described by POSIX.1‐2008, but the standard utilities that process
160 tags files shall be able to process those formats as well as the first
161 format.
162 In any of these formats, the file shall be sorted by identifier, based
164 on the collation sequence in the POSIX locale.
165
167 If the operand identifies C-language source, the ctags utility shall
168 attempt to produce an output line for each of the following objects:
169 * Function definitions
171 * Type definitions
173 * Macros with arguments
175 It may also produce output for any of the following objects:
177 * Function prototypes
179 * Structures
181 * Unions
183 * Global variable definitions
185 * Enumeration types
187 * Macros without arguments
189 * #define statements
191 * #line statements
193 Any #if and #ifdef statements shall produce no output. The tag main is
195 treated specially in C programs. The tag formed shall be created by
196 prefixing M to the name of the file, with the trailing .c, and leading
197 pathname components (if any) removed.
198 On systems that do not support the C-Language Development Utilities
200 option, ctags produces unspecified results for C-language source code
201 files. It should write to standard error a message identifying this
202 condition and cause a non-zero exit status to be produced.
203 If the operand identifies FORTRAN source, the ctags utility shall pro‐
205 duce an output line for each function definition. It may also produce
206 output for any of the following objects:
207 * Subroutine definitions
209 * COMMON statements
211 * PARAMETER statements
213 * DATA and BLOCK DATA statements
215 * Statement numbers
217 On systems that do not support the FORTRAN Development Utilities
219 option, ctags produces unspecified results for FORTRAN source code
220 files. It should write to standard error a message identifying this
221 condition and cause a non-zero exit status to be produced.
222 It is implementation-defined what other objects (including duplicate
224 identifiers) produce output.
225
227 The following exit values shall be returned:
228 0 Successful completion.
230 >0 An error occurred.
232
234 Default.
235 The following sections are informative.
237
239 The output with −x is meant to be a simple index that can be written
240 out as an off-line readable function index. If the input files to ctags
241 (such as .c files) were not created using the same locale as that in
242 effect when ctags −x is run, results might not be as expected.
243 The description of C-language processing says ``attempts to'' because
245 the C language can be greatly confused, especially through the use of
246 #defines, and this utility would be of no use if the real C preproces‐
247 sor were run to identify them. The output from ctags may be fooled and
248 incorrect for various constructs.
249
251 None.
252
254 The option list was significantly reduced from that provided by histor‐
255 ical implementations. The −F option was omitted as redundant, since it
256 is the default. The −B option was omitted as being of very limited use‐
257 fulness. The −t option was omitted since the recognition of typedefs is
258 now required for C source files. The −u option was omitted because the
259 update function was judged to be not only inefficient, but also rarely
260 needed.
261 An early proposal included a −w option to suppress warning diagnostics.
263 Since the types of such diagnostics could not be described, the option
264 was omitted as being not useful.
265 The text for LC_CTYPE about compatibility with the C locale acknowl‐
267 edges that the ISO C standard imposes requirements on the locale used
268 to process C source. This could easily be a superset of that known as
269 ``the C locale'' by way of implementation extensions, or one of a few
270 alternative locales for systems supporting different codesets. No
271 statement is made for FORTRAN because the ANSI X3.9‐1978 standard (FOR‐
272 TRAN 77) does not (yet) define a similar locale concept. However, a
273 general rule in this volume of POSIX.1‐2008 is that any time that
274 locales do not match (preparing a file for one locale and processing it
275 in another), the results are suspect.
276 The collation sequence of the tags file is not affected by LC_COLLATE
278 because it is typically not used by human readers, but only by programs
279 such as vi to locate the tag within the source files. Using the POSIX
280 locale eliminates some of the problems of coordinating locales between
281 the ctags file creator and the vi file reader.
282 Historically, the tags file has been used only by ex and vi. However,
284 the format of the tags file has been published to encourage other pro‐
285 grams to use the tags in new ways. The format allows either patterns or
286 line numbers to find the identifiers because the historical vi recog‐
287 nizes either. The ctags utility does not produce the format using line
288 numbers because it is not useful following any source file changes that
289 add or delete lines. The documented search patterns match historical
290 practice. It should be noted that literal leading <circumflex> or
291 trailing <dollar-sign> characters in the search pattern will only
292 behave correctly if anchored to the beginning of the line or end of the
293 line by an additional <circumflex> or <dollar-sign> character.
294 Historical implementations also understand the objects used by the lan‐
296 guages Pascal and sometimes LISP, and they understand the C source out‐
297 put by lex and yacc. The ctags utility is not required to accommodate
298 these languages, although implementors are encouraged to do so.
299 The following historical option was not specified, as vgrind is not
301 included in this volume of POSIX.1‐2008:
302 −v If the −v flag is given, an index of the form expected by
304 vgrind is produced on the standard output. This listing con‐
305 tains the function name, filename, and page number (assuming
306 64-line pages). Since the output is sorted into lexicographic
307 order, it may be desired to run the output through sort −f.
308 Sample use:
309 ctags −v files | sort −f > index vgrind −x index
311 The special treatment of the tag main makes the use of ctags practical
313 in directories with more than one program.
314
316 None.
317
319 c99, fort77, vi
320 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
322 Variables, Section 12.2, Utility Syntax Guidelines
323
325 Portions of this text are reprinted and reproduced in electronic form
326 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
327 -- Portable Operating System Interface (POSIX), The Open Group Base
328 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
329 cal and Electronics Engineers, Inc and The Open Group. (This is
330 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
331 event of any discrepancy between this version and the original IEEE and
332 The Open Group Standard, the original IEEE and The Open Group Standard
333 is the referee document. The original Standard can be obtained online
334 at http://www.unix.org/online.html .
335 Any typographical or formatting errors that appear in this page are
337 most likely to have been introduced during the conversion of the source
338 files to man page format. To report such errors, see https://www.ker‐
339 nel.org/doc/man-pages/reporting_bugs.html .
340IEEE/The Open Group 2013 CTAGS(1P)