1CTAGS(1P)                  POSIX Programmer's Manual                 CTAGS(1P)
2
3
4

PROLOG

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
11

NAME

13       ctags — create a tags file (DEVELOPMENT, FORTRAN)
14

SYNOPSIS

16       ctags [−a] [−f tagsfile] pathname...
17
18       ctags −x pathname...
19

DESCRIPTION

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
26       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

OPTIONS

35       The  ctags  utility  shall  conform  to  the Base Definitions volume of
36       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
37
38       The following options shall be supported:
39
40       −a        Append to tagsfile.
41
42       −f tagsfile
43                 Write the object locator lists into tagsfile instead  of  the
44                 default file named tags in the current directory.
45
46       −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

OPERANDS

52       The following pathname operands are supported:
53
54       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
58       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
62       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
66       The handling of other files is implementation-defined.
67

STDIN

69       See the INPUT FILES section.
70

INPUT FILES

72       The input files shall be text files containing source code in the  lan‐
73       guage indicated by the operand filename suffixes.
74

ENVIRONMENT VARIABLES

76       The  following  environment  variables  shall  affect  the execution of
77       ctags:
78
79       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
85       LC_ALL    If set to a non-empty string value, override  the  values  of
86                 all the other internationalization variables.
87
88       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
93       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
100       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
105       NLSPATH   Determine the location of message catalogs for the processing
106                 of LC_MESSAGES.
107

ASYNCHRONOUS EVENTS

109       Default.
110

STDOUT

112       The  list of object name information produced by the −x option shall be
113       written to standard output in the following format:
114
115           "%s %d %s %s", <object-name>, <line-number>, <filename>, <text>
116
117       where <text> is the text of line <line-number> of file <filename>.
118

STDERR

120       The standard error shall be used only for diagnostic messages.
121

OUTPUT FILES

123       When the −x option is not specified, the  format  of  the  output  file
124       shall be:
125
126           "%s\t%s\t/%s/\n", <identifier>, <filename>, <pattern>
127
128       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
133       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
142       An alternative format is:
143
144           "%s\t%s\t?%s?\n", <identifier>, <filename>, <pattern>
145
146       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
151       A second alternative format is:
152
153           "%s\t%s\t%d\n", <identifier>, <filename>, <lineno>
154
155       where <lineno> is a decimal line number that could be used by an editor
156       to find <identifier> in <filename>.
157
158       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
163       In any of these formats, the file shall be sorted by identifier,  based
164       on the collation sequence in the POSIX locale.
165

EXTENDED DESCRIPTION

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
170        *  Function definitions
171
172        *  Type definitions
173
174        *  Macros with arguments
175
176       It may also produce output for any of the following objects:
177
178        *  Function prototypes
179
180        *  Structures
181
182        *  Unions
183
184        *  Global variable definitions
185
186        *  Enumeration types
187
188        *  Macros without arguments
189
190        *  #define statements
191
192        *  #line statements
193
194       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
199       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
204       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
208        *  Subroutine definitions
209
210        *  COMMON statements
211
212        *  PARAMETER statements
213
214        *  DATA and BLOCK DATA statements
215
216        *  Statement numbers
217
218       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
223       It  is  implementation-defined  what other objects (including duplicate
224       identifiers) produce output.
225

EXIT STATUS

227       The following exit values shall be returned:
228
229        0    Successful completion.
230
231       >0    An error occurred.
232

CONSEQUENCES OF ERRORS

234       Default.
235
236       The following sections are informative.
237

APPLICATION USAGE

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
244       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

EXAMPLES

251       None.
252

RATIONALE

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
262       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
266       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
277       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
283       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
295       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
300       The  following  historical  option  was not specified, as vgrind is not
301       included in this volume of POSIX.1‐2008:
302
303       −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
310                     ctags −v files | sort −f > index vgrind −x index
311
312       The  special treatment of the tag main makes the use of ctags practical
313       in directories with more than one program.
314

FUTURE DIRECTIONS

316       None.
317

SEE ALSO

319       c99, fort77, vi
320
321       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
336       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 .
340
341
342
343IEEE/The Open Group                  2013                            CTAGS(1P)
Impressum