Commit | Line | Data |
---|---|---|
b5dc1377 | 1 | .\" Copyright (c) 1987, 1990 The Regents of the University of California. |
083e16be | 2 | .\" All rights reserved. |
cab8f024 | 3 | .\" |
a7edb52c | 4 | .\" %sccs.include.redist.roff% |
083e16be | 5 | .\" |
5237c2bf | 6 | .\" @(#)ctags.1 6.8 (Berkeley) %G% |
cab8f024 | 7 | .\" |
b5dc1377 CL |
8 | .Dd |
9 | .Dt CTAGS 1 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm ctags | |
13 | .Nd create a tags file | |
14 | .Sh SYNOPSIS | |
15 | .Nm ctags | |
16 | .Op Fl BFadtuwvx | |
17 | .Op Fl f Ar tagsfile | |
18 | .Ar name ... | |
19 | .Sh DESCRIPTION | |
20 | .Nm Ctags | |
21 | makes a tags file for | |
22 | .Xr ex 1 | |
23 | from the specified C, | |
a7edb52c CL |
24 | Pascal, Fortran, |
25 | .Tn YACC , | |
26 | lex, and lisp sources. A tags file gives the | |
8c5e71ad KB |
27 | locations of specified objects in a group of files. Each line of the |
28 | tags file contains the object name, the file in which it is defined, | |
29 | and a search pattern for the object definition, separated by white-space. | |
b5dc1377 CL |
30 | Using the |
31 | .Ar tags | |
32 | file, | |
33 | .Xr ex 1 | |
34 | can quickly locate these object | |
5325ced3 CL |
35 | definitions. Depending on the options provided to |
36 | .Nm ctags , | |
8c5e71ad KB |
37 | objects will consist of subroutines, typedefs, defines, structs, |
38 | enums and unions. | |
a7edb52c CL |
39 | .Bl -tag -width Ds |
40 | .It Fl B | |
41 | use backward searching patterns | |
42 | .Pq Li ?...? . | |
43 | .It Fl F | |
44 | use forward searching patterns | |
45 | .Pq Li /.../ | |
46 | (the default). | |
47 | .It Fl a | |
b5dc1377 CL |
48 | append to |
49 | .Ar tags | |
50 | file. | |
a7edb52c | 51 | .It Fl d |
b5dc1377 | 52 | create tags for |
5325ced3 | 53 | .Li #defines |
b5dc1377 | 54 | that don't take arguments; |
5325ced3 | 55 | .Li #defines |
8c5e71ad | 56 | that take arguments are tagged automatically. |
a7edb52c CL |
57 | .It Fl f |
58 | Places the tag descriptions in a file called | |
59 | .Ar tagsfile . | |
60 | The default behaviour is to place them in a file | |
61 | .Ar tags . | |
62 | .It Fl t | |
8c5e71ad | 63 | create tags for typedefs, structs, unions, and enums. |
a7edb52c | 64 | .It Fl u |
b5dc1377 CL |
65 | update the specified files in the |
66 | .Ar tags | |
67 | file, that is, all | |
8c5e71ad KB |
68 | references to them are deleted, and the new values are appended to the |
69 | file. (Beware: this option is implemented in a way which is rather | |
b5dc1377 CL |
70 | slow; it is usually faster to simply rebuild the |
71 | .Ar tags | |
72 | file.) | |
a7edb52c CL |
73 | .It Fl v |
74 | An index of the form expected by | |
75 | .Xr vgrind 1 | |
76 | is produced on the standard output. This listing | |
77 | contains the object name, file name, and page number (assuming 64 | |
78 | line pages). Since the output will be sorted into lexicographic order, | |
79 | it may be desired to run the output through | |
80 | .Xr sort 1 . | |
81 | Sample use: | |
82 | .Bd -literal -offset indent | |
83 | ctags \-v files \&| sort \-f > index | |
84 | vgrind \-x index | |
85 | .Ed | |
86 | .It Fl w | |
87 | suppress warning diagnostics. | |
88 | .It Fl x | |
89 | .Nm ctags | |
90 | produces a list of object | |
91 | names, the line number and file name on which each is defined, as well | |
92 | as the text of that line and prints this on the standard output. This | |
93 | is a simple index which can be printed out as an off-line readable | |
94 | function index. | |
95 | .El | |
b5dc1377 CL |
96 | .Pp |
97 | Files whose names end in | |
98 | .Nm \&.c | |
99 | or | |
100 | .Nm \&.h | |
101 | are assumed to be C | |
102 | source files and are searched for C style routine and macro definitions. | |
103 | Files whose names end in | |
104 | .Nm \&.y | |
a7edb52c CL |
105 | are assumed to be |
106 | .Tn YACC | |
107 | source files. | |
b5dc1377 CL |
108 | Files whose names end in |
109 | .Nm \&.l | |
110 | are assumed to be lisp files if their | |
111 | first non-blank character is `;', `(', or `[', | |
112 | otherwise, they are | |
113 | treated as lex files. Other files are first examined to see if they | |
114 | contain any Pascal or Fortran routine definitions, and, if not, are | |
115 | searched for C style definitions. | |
116 | .Pp | |
117 | The tag | |
5325ced3 | 118 | .Li main |
b5dc1377 CL |
119 | is treated specially in C programs. The tag formed |
120 | is created by prepending | |
121 | .Ar M | |
122 | to the name of the file, with the | |
123 | trailing | |
124 | .Nm \&.c | |
125 | and any leading pathname components removed. This | |
126 | makes use of | |
127 | .Nm ctags | |
128 | practical in directories with more than one | |
8c5e71ad | 129 | program. |
b5dc1377 CL |
130 | .Pp |
131 | Yacc and lex files each have a special tag. | |
132 | .Ar Yyparse | |
133 | is the start | |
134 | of the second section of the yacc file, and | |
135 | .Ar yylex | |
136 | is the start of | |
137 | the second section of the lex file. | |
138 | .Sh FILES | |
a7edb52c CL |
139 | .Bl -tag -width tags -compact |
140 | .It Pa tags | |
b5dc1377 | 141 | default output tags file |
a7edb52c | 142 | .El |
b5dc1377 CL |
143 | .Sh DIAGNOSTICS |
144 | .Nm Ctags | |
145 | exits with a value of 1 if an error occurred, where | |
28048a77 | 146 | duplicate objects are not considered errors, 0 otherwise. |
b5dc1377 CL |
147 | .Sh SEE ALSO |
148 | .Xr ex 1 , | |
149 | .Xr vi 1 | |
b5dc1377 CL |
150 | .Sh BUGS |
151 | Recognition of | |
152 | .Nm functions , | |
153 | .Nm subroutines | |
154 | and | |
155 | .Nm procedures | |
a7edb52c CL |
156 | for |
157 | .Tn FORTRAN | |
158 | and Pascal is done is a very simpleminded way. No attempt | |
8c5e71ad | 159 | is made to deal with block structure; if you have two Pascal procedures |
b5dc1377 CL |
160 | in different blocks with the same name you lose. |
161 | .Nm Ctags | |
162 | doesn't | |
8c5e71ad | 163 | understand about Pascal types. |
b5dc1377 | 164 | .Pp |
a7edb52c CL |
165 | The method of deciding whether to look for C, Pascal or |
166 | .Tn FORTRAN | |
cab8f024 | 167 | functions is a hack. |
b5dc1377 CL |
168 | .Pp |
169 | .Nm Ctags | |
170 | relies on the input being well formed, and any syntactical | |
8c5e71ad | 171 | errors will completely confuse it. It also finds some legal syntax |
b5dc1377 | 172 | confusing; for example, as it doesn't understand |
a7edb52c | 173 | .Li #ifdef Ns 's , |
8c5e71ad | 174 | (incidentally, that's a feature, not a bug) any code with unbalanced |
b5dc1377 | 175 | braces inside |
a7edb52c | 176 | .Li #ifdef Ns 's |
b5dc1377 | 177 | will cause it to become somewhat disoriented. |
8c5e71ad KB |
178 | In a similar fashion, multiple line changes within a definition will |
179 | cause it to enter the last line of the object, rather than the first, as | |
b5dc1377 | 180 | the searching pattern. The last line of multiple line |
a7edb52c | 181 | .Li typedef Ns 's |
8c5e71ad | 182 | will similarly be noted. |
a7edb52c CL |
183 | .Sh HISTORY |
184 | The | |
185 | .Nm | |
186 | command appeared in | |
187 | .Bx 3.0 . |