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
12 ctags - create a tags file (DEVELOPMENT, FORTRAN)
13
15 ctags [-a][-f tagsfile] pathname ...
16 ctags -x pathname ...
18
21 The ctags utility shall be provided on systems that support the User
22 Portability Utilities option, the Software Development Utilities
23 option, and either or both of the C-Language Development Utilities
24 option and FORTRAN Development Utilities option. On other systems, it
25 is optional.
26 The ctags utility shall write a tagsfile or an index of objects from C-
28 language or FORTRAN source files specified by the pathname operands.
29 The tagsfile shall list the locators of language-specific objects
30 within the source files. A locator consists of a name, pathname, and
31 either a search pattern or a line number that can be used in searching
32 for the object definition. The objects that shall be recognized are
33 specified in the EXTENDED DESCRIPTION section.
34
36 The ctags utility shall conform to the Base Definitions volume of
37 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
38 The following options shall be supported:
40 -a Append to tagsfile.
42 -f tagsfile
44 Write the object locator lists into tagsfile instead of the
45 default file named tags in the current directory.
46 -x Produce a list of object names, the line number, and filename in
48 which each is defined, as well as the text of that line, and
49 write this to the standard output. A tagsfile shall not be cre‐
50 ated when -x is specified.
51
54 The following pathname operands are supported:
55 file.c Files with basenames ending with the .c suffix shall be treated
57 as C-language source code. Such files that are not valid input
58 to c99 produce unspecified results.
59 file.h Files with basenames ending with the .h suffix shall be treated
61 as C-language source code. Such files that are not valid input
62 to c99 produce unspecified results.
63 file.f Files with basenames ending with the .f suffix shall be treated
65 as FORTRAN-language source code. Such files that are not valid
66 input to fort77 produce unspecified results.
67 The handling of other files is implementation-defined.
70
72 See the INPUT FILES section.
73
75 The input files shall be text files containing source code in the lan‐
76 guage indicated by the operand filename suffixes.
77
79 The following environment variables shall affect the execution of
80 ctags:
81 LANG Provide a default value for the internationalization variables
83 that are unset or null. (See the Base Definitions volume of
84 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
85 ables for the precedence of internationalization variables used
86 to determine the values of locale categories.)
87 LC_ALL If set to a non-empty string value, override the values of all
89 the other internationalization variables.
90 LC_COLLATE
92 Determine the order in which output is sorted for the -x option.
94 The POSIX locale determines the order in which the tagsfile is
95 written.
96 LC_CTYPE
98 Determine the locale for the interpretation of sequences of
99 bytes of text data as characters (for example, single-byte as
100 opposed to multi-byte characters in arguments and input files).
101 When processing C-language source code, if the locale is not
102 compatible with the C locale described by the ISO C standard,
103 the results are unspecified.
104 LC_MESSAGES
106 Determine the locale that should be used to affect the format
107 and contents of diagnostic messages written to standard error.
108 NLSPATH
110 Determine the location of message catalogs for the processing of
111 LC_MESSAGES .
112
115 Default.
116
118 The list of object name information produced by the -x option shall be
119 written to standard output in the following format:
120 "%s %d %s %s", <object-name>, <line-number>, <filename>, <text>
123 where <text> is the text of line <line-number> of file <filename>.
125
127 The standard error shall be used only for diagnostic messages.
128
130 When the -x option is not specified, the format of the output file
131 shall be:
132 "%s\t%s\t/%s/\n", <identifier>, <filename>, <pattern>
135 where <pattern> is a search pattern that could be used by an editor to
137 find the defining instance of <identifier> in <filename> (where defin‐
138 ing instance is indicated by the declarations listed in the EXTENDED
139 DESCRIPTION).
140 An optional circumflex ( '^' ) can be added as a prefix to <pattern>,
142 and an optional dollar sign can be appended to <pattern> to indicate
143 that the pattern is anchored to the beginning (end) of a line of text.
144 Any slash or backslash characters in <pattern> shall be preceded by a
145 backslash character. The anchoring circumflex, dollar sign, and escap‐
146 ing backslash characters shall not be considered part of the search
147 pattern. All other characters in the search pattern shall be considered
148 literal characters.
149 An alternative format is:
151 "%s\t%s\t?%s?\n", <identifier>, <filename>, <pattern>
154 which is identical to the first format except that slashes in <pattern>
156 shall not be preceded by escaping backslash characters, and question
157 mark characters in <pattern> shall be preceded by backslash characters.
158 A second alternative format is:
160 "%s\t%s\t%d\n", <identifier>, <filename>, <lineno>
163 where <lineno> is a decimal line number that could be used by an editor
165 to find <identifier> in <filename>.
166 Neither alternative format shall be produced by ctags when it is used
168 as described by IEEE Std 1003.1-2001, but the standard utilities that
169 process tags files shall be able to process those formats as well as
170 the first format.
171 In any of these formats, the file shall be sorted by identifier, based
173 on the collation sequence in the POSIX locale.
174
176 If the operand identifies C-language source, the ctags utility shall
177 attempt to produce an output line for each of the following objects:
178 * Function definitions
180 * Type definitions
182 * Macros with arguments
184 It may also produce output for any of the following objects:
186 * Function prototypes
188 * Structures
190 * Unions
192 * Global variable definitions
194 * Enumeration types
196 * Macros without arguments
198 * #define statements
200 * #line statements
202 Any #if and #ifdef statements shall produce no output. The tag main is
204 treated specially in C programs. The tag formed shall be created by
205 prefixing M to the name of the file, with the trailing .c, and leading
206 pathname components (if any) removed.
207 On systems that do not support the C-Language Development Utilities
209 option, ctags produces unspecified results for C-language source code
210 files. It should write to standard error a message identifying this
211 condition and cause a non-zero exit status to be produced.
212 If the operand identifies FORTRAN source, the ctags utility shall pro‐
214 duce an output line for each function definition. It may also produce
215 output for any of the following objects:
216 * Subroutine definitions
218 * COMMON statements
220 * PARAMETER statements
222 * DATA and BLOCK DATA statements
224 * Statement numbers
226 On systems that do not support the FORTRAN Development Utilities
228 option, ctags produces unspecified results for FORTRAN source code
229 files. It should write to standard error a message identifying this
230 condition and cause a non-zero exit status to be produced.
231 It is implementation-defined what other objects (including duplicate
233 identifiers) produce output.
234
236 The following exit values shall be returned:
237 0 Successful completion.
239 >0 An error occurred.
241
244 Default.
245 The following sections are informative.
247
249 The output with -x is meant to be a simple index that can be written
250 out as an off-line readable function index. If the input files to ctags
251 (such as .c files) were not created using the same locale as that in
252 effect when ctags -x is run, results might not be as expected.
253 The description of C-language processing says "attempts to" because the
255 C language can be greatly confused, especially through the use of
256 #defines, and this utility would be of no use if the real C preproces‐
257 sor were run to identify them. The output from ctags may be fooled and
258 incorrect for various constructs.
259
261 None.
262
264 The option list was significantly reduced from that provided by histor‐
265 ical implementations. The -F option was omitted as redundant, since it
266 is the default. The -B option was omitted as being of very limited use‐
267 fulness. The -t option was omitted since the recognition of typedefs is
268 now required for C source files. The -u option was omitted because the
269 update function was judged to be not only inefficient, but also rarely
270 needed.
271 An early proposal included a -w option to suppress warning diagnostics.
273 Since the types of such diagnostics could not be described, the option
274 was omitted as being not useful.
275 The text for LC_CTYPE about compatibility with the C locale acknowl‐
277 edges that the ISO C standard imposes requirements on the locale used
278 to process C source. This could easily be a superset of that known as
279 "the C locale" by way of implementation extensions, or one of a few
280 alternative locales for systems supporting different codesets. No
281 statement is made for FORTRAN because the ANSI X3.9-1978 standard (FOR‐
282 TRAN 77) does not (yet) define a similar locale concept. However, a
283 general rule in this volume of IEEE Std 1003.1-2001 is that any time
284 that locales do not match (preparing a file for one locale and process‐
285 ing it in another), the results are suspect.
286 The collation sequence of the tags file is not affected by LC_COLLATE
288 because it is typically not used by human readers, but only by programs
289 such as vi to locate the tag within the source files. Using the POSIX
290 locale eliminates some of the problems of coordinating locales between
291 the ctags file creator and the vi file reader.
292 Historically, the tags file has been used only by ex and vi. However,
294 the format of the tags file has been published to encourage other pro‐
295 grams to use the tags in new ways. The format allows either patterns or
296 line numbers to find the identifiers because the historical vi recog‐
297 nizes either. The ctags utility does not produce the format using line
298 numbers because it is not useful following any source file changes that
299 add or delete lines. The documented search patterns match historical
300 practice. It should be noted that literal leading circumflex or trail‐
301 ing dollar-sign characters in the search pattern will only behave cor‐
302 rectly if anchored to the beginning of the line or end of the line by
303 an additional circumflex or dollar-sign character.
304 Historical implementations also understand the objects used by the lan‐
306 guages Pascal and sometimes LISP, and they understand the C source out‐
307 put by lex and yacc. The ctags utility is not required to accommodate
308 these languages, although implementors are encouraged to do so.
309 The following historical option was not specified, as vgrind is not
311 included in this volume of IEEE Std 1003.1-2001:
312 -v If the -v flag is given, an index of the form expected by vgrind
314 is produced on the standard output. This listing contains the
315 function name, filename, and page number (assuming 64-line
316 pages). Since the output is sorted into lexicographic order, it
317 may be desired to run the output through sort -f. Sample use:
318 ctags -v files | sort -f > index vgrind -x index
321 The special treatment of the tag main makes the use of ctags practical
324 in directories with more than one program.
325
327 None.
328
330 c99, fort77, vi
331
333 Portions of this text are reprinted and reproduced in electronic form
334 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
335 -- Portable Operating System Interface (POSIX), The Open Group Base
336 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
337 Electrical and Electronics Engineers, Inc and The Open Group. In the
338 event of any discrepancy between this version and the original IEEE and
339 The Open Group Standard, the original IEEE and The Open Group Standard
340 is the referee document. The original Standard can be obtained online
341 at http://www.opengroup.org/unix/online.html .
342IEEE/The Open Group 2003 CTAGS(1P)