Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1987, 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)ctags.1 6.8 (Berkeley) 4/24/91 | |
33 | .\" | |
34 | .Dd April 24, 1991 | |
35 | .Dt CTAGS 1 | |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm ctags | |
39 | .Nd create a tags file | |
40 | .Sh SYNOPSIS | |
41 | .Nm ctags | |
42 | .Op Fl BFadtuwvx | |
43 | .Op Fl f Ar tagsfile | |
44 | .Ar name ... | |
45 | .Sh DESCRIPTION | |
46 | .Nm Ctags | |
47 | makes a tags file for | |
48 | .Xr ex 1 | |
49 | from the specified C, | |
50 | Pascal, Fortran, | |
51 | .Tn YACC , | |
52 | lex, and lisp sources. A tags file gives the | |
53 | locations of specified objects in a group of files. Each line of the | |
54 | tags file contains the object name, the file in which it is defined, | |
55 | and a search pattern for the object definition, separated by white-space. | |
56 | Using the | |
57 | .Ar tags | |
58 | file, | |
59 | .Xr ex 1 | |
60 | can quickly locate these object | |
61 | definitions. Depending on the options provided to | |
62 | .Nm ctags , | |
63 | objects will consist of subroutines, typedefs, defines, structs, | |
64 | enums and unions. | |
65 | .Bl -tag -width Ds | |
66 | .It Fl B | |
67 | use backward searching patterns | |
68 | .Pq Li ?...? . | |
69 | .It Fl F | |
70 | use forward searching patterns | |
71 | .Pq Li /.../ | |
72 | (the default). | |
73 | .It Fl a | |
74 | append to | |
75 | .Ar tags | |
76 | file. | |
77 | .It Fl d | |
78 | create tags for | |
79 | .Li #defines | |
80 | that don't take arguments; | |
81 | .Li #defines | |
82 | that take arguments are tagged automatically. | |
83 | .It Fl f | |
84 | Places the tag descriptions in a file called | |
85 | .Ar tagsfile . | |
8f8a9528 | 86 | The default behavior is to place them in a file |
15637ed4 RG |
87 | .Ar tags . |
88 | .It Fl t | |
89 | create tags for typedefs, structs, unions, and enums. | |
90 | .It Fl u | |
91 | update the specified files in the | |
92 | .Ar tags | |
93 | file, that is, all | |
94 | references to them are deleted, and the new values are appended to the | |
95 | file. (Beware: this option is implemented in a way which is rather | |
96 | slow; it is usually faster to simply rebuild the | |
97 | .Ar tags | |
98 | file.) | |
99 | .It Fl v | |
100 | An index of the form expected by | |
101 | .Xr vgrind 1 | |
102 | is produced on the standard output. This listing | |
103 | contains the object name, file name, and page number (assuming 64 | |
104 | line pages). Since the output will be sorted into lexicographic order, | |
105 | it may be desired to run the output through | |
106 | .Xr sort 1 . | |
107 | Sample use: | |
108 | .Bd -literal -offset indent | |
109 | ctags \-v files \&| sort \-f > index | |
110 | vgrind \-x index | |
111 | .Ed | |
112 | .It Fl w | |
113 | suppress warning diagnostics. | |
114 | .It Fl x | |
115 | .Nm ctags | |
116 | produces a list of object | |
117 | names, the line number and file name on which each is defined, as well | |
118 | as the text of that line and prints this on the standard output. This | |
119 | is a simple index which can be printed out as an off-line readable | |
120 | function index. | |
121 | .El | |
122 | .Pp | |
123 | Files whose names end in | |
124 | .Nm \&.c | |
125 | or | |
126 | .Nm \&.h | |
127 | are assumed to be C | |
128 | source files and are searched for C style routine and macro definitions. | |
129 | Files whose names end in | |
130 | .Nm \&.y | |
131 | are assumed to be | |
132 | .Tn YACC | |
133 | source files. | |
134 | Files whose names end in | |
135 | .Nm \&.l | |
136 | are assumed to be lisp files if their | |
137 | first non-blank character is `;', `(', or `[', | |
138 | otherwise, they are | |
139 | treated as lex files. Other files are first examined to see if they | |
140 | contain any Pascal or Fortran routine definitions, and, if not, are | |
141 | searched for C style definitions. | |
142 | .Pp | |
143 | The tag | |
144 | .Li main | |
145 | is treated specially in C programs. The tag formed | |
146 | is created by prepending | |
147 | .Ar M | |
148 | to the name of the file, with the | |
149 | trailing | |
150 | .Nm \&.c | |
151 | and any leading pathname components removed. This | |
152 | makes use of | |
153 | .Nm ctags | |
154 | practical in directories with more than one | |
155 | program. | |
156 | .Pp | |
157 | Yacc and lex files each have a special tag. | |
158 | .Ar Yyparse | |
159 | is the start | |
160 | of the second section of the yacc file, and | |
161 | .Ar yylex | |
162 | is the start of | |
163 | the second section of the lex file. | |
164 | .Sh FILES | |
165 | .Bl -tag -width tags -compact | |
166 | .It Pa tags | |
167 | default output tags file | |
168 | .El | |
169 | .Sh DIAGNOSTICS | |
170 | .Nm Ctags | |
171 | exits with a value of 1 if an error occurred, where | |
172 | duplicate objects are not considered errors, 0 otherwise. | |
173 | .Sh SEE ALSO | |
174 | .Xr ex 1 , | |
175 | .Xr vi 1 | |
176 | .Sh BUGS | |
177 | Recognition of | |
178 | .Nm functions , | |
179 | .Nm subroutines | |
180 | and | |
181 | .Nm procedures | |
182 | for | |
183 | .Tn FORTRAN | |
184 | and Pascal is done is a very simpleminded way. No attempt | |
185 | is made to deal with block structure; if you have two Pascal procedures | |
186 | in different blocks with the same name you lose. | |
187 | .Nm Ctags | |
188 | doesn't | |
189 | understand about Pascal types. | |
190 | .Pp | |
191 | The method of deciding whether to look for C, Pascal or | |
192 | .Tn FORTRAN | |
193 | functions is a hack. | |
194 | .Pp | |
195 | .Nm Ctags | |
196 | relies on the input being well formed, and any syntactical | |
197 | errors will completely confuse it. It also finds some legal syntax | |
198 | confusing; for example, as it doesn't understand | |
199 | .Li #ifdef Ns 's , | |
200 | (incidentally, that's a feature, not a bug) any code with unbalanced | |
201 | braces inside | |
202 | .Li #ifdef Ns 's | |
203 | will cause it to become somewhat disoriented. | |
204 | In a similar fashion, multiple line changes within a definition will | |
205 | cause it to enter the last line of the object, rather than the first, as | |
206 | the searching pattern. The last line of multiple line | |
207 | .Li typedef Ns 's | |
208 | will similarly be noted. | |
209 | .Sh HISTORY | |
210 | The | |
211 | .Nm | |
212 | command appeared in | |
213 | .Bx 3.0 . |