Commit | Line | Data |
---|---|---|
cab8f024 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
28048a77 | 5 | .\" @(#)ctags.1 6.4 (Berkeley) %G% |
cab8f024 | 6 | .\" |
1d61bde9 | 7 | .TH CTAGS 1 "" |
cab8f024 KM |
8 | .UC 4 |
9 | .SH NAME | |
10 | ctags \- create a tags file | |
11 | .SH SYNOPSIS | |
12 | .B ctags | |
13 | [ | |
8c5e71ad | 14 | .B \-BFadtuwvx |
54053103 | 15 | ] [ |
8c5e71ad | 16 | .B \-f |
54053103 | 17 | .I tagsfile |
cab8f024 KM |
18 | ] |
19 | name ... | |
20 | .SH DESCRIPTION | |
8c5e71ad KB |
21 | \fICtags\fP makes a tags file for \fIex\fP(1) from the specified C, |
22 | Pascal, Fortran, YACC, lex, and lisp sources. A tags file gives the | |
23 | locations of specified objects in a group of files. Each line of the | |
24 | tags file contains the object name, the file in which it is defined, | |
25 | and a search pattern for the object definition, separated by white-space. | |
26 | Using the \fItags\fP file, \fIex\fP(1) can quickly locate these object | |
27 | definitions. Depending on the options provided to \fIctags\fP, | |
28 | objects will consist of subroutines, typedefs, defines, structs, | |
29 | enums and unions. | |
cab8f024 | 30 | .PP |
28048a77 KB |
31 | Yacc and lex files each have a special tag. \fIYyparse\fP is the start |
32 | of the second section of the yacc file, and \fIyylex\fP is the start of | |
33 | the second section of the lex file. | |
34 | .PP | |
8c5e71ad KB |
35 | If the \fB-x\fP flag is given, \fIctags\fP produces a list of object |
36 | names, the line number and file name on which each is defined, as well | |
37 | as the text of that line and prints this on the standard output. This | |
38 | is a simple index which can be printed out as an off-line readable | |
39 | function index. | |
cab8f024 | 40 | .PP |
8c5e71ad KB |
41 | If the \fB-v\fP flag is given, an index of the form expected by |
42 | \fIvgrind\fP(1) is produced on the standard output. This listing | |
43 | contains the object name, file name, and page number (assuming 64 | |
44 | line pages). Since the output will be sorted into lexicographic order, | |
45 | it may be desired to run the output through \fBsort -f\fP. | |
cab8f024 KM |
46 | Sample use: |
47 | .nf | |
48 | ctags \-v files | sort \-f > index | |
49 | vgrind \-x index | |
50 | .fi | |
51 | .PP | |
8c5e71ad KB |
52 | Normally \fIctags\fP places the tag descriptions in a file called |
53 | \fItags\fP; this may be overridden with the \fB-f\fP option. | |
54053103 | 54 | .PP |
8c5e71ad KB |
55 | Files whose names end in \fB.c\fP or \fB.h\fP are assumed to be C |
56 | source files and are searched for C style routine and macro definitions. | |
57 | Files whose names end in \fB.y\fP are assumed to be YACC source files. | |
58 | Files whose names end in \fB.l\fP are assumed to be lisp files if their | |
59 | first non-blank character is `;', `(', or `[', otherwise, they are | |
60 | treated as lex files. Other files are first examined to see if they | |
61 | contain any Pascal or Fortran routine definitions, and, if not, are | |
62 | searched for C style definitions. | |
cab8f024 KM |
63 | .PP |
64 | Other options are: | |
65 | .TP 5 | |
5d15751e | 66 | .B \-F |
8c5e71ad | 67 | use forward searching patterns (/.../) (the default). |
5d15751e KM |
68 | .TP 5 |
69 | .B \-B | |
70 | use backward searching patterns (?...?). | |
71 | .TP 5 | |
72 | .B \-a | |
8c5e71ad KB |
73 | append to \fItags\fP file. |
74 | .TP 5 | |
75 | .B \-d | |
76 | create tags for \fI#defines\fP that don't take arguments; \fI#defines\fP | |
77 | that take arguments are tagged automatically. | |
5d15751e KM |
78 | .TP 5 |
79 | .B \-t | |
8c5e71ad | 80 | create tags for typedefs, structs, unions, and enums. |
5d15751e | 81 | .TP 5 |
cab8f024 | 82 | .B \-w |
8c5e71ad | 83 | suppress warning diagnostics. |
cab8f024 KM |
84 | .TP 5 |
85 | .B \-u | |
8c5e71ad KB |
86 | update the specified files in the \fItags\fP file, that is, all |
87 | references to them are deleted, and the new values are appended to the | |
88 | file. (Beware: this option is implemented in a way which is rather | |
89 | slow; it is usually faster to simply rebuild the \fItags\fP file.) | |
cab8f024 | 90 | .PP |
8c5e71ad KB |
91 | The tag \fImain\fP is treated specially in C programs. The tag formed |
92 | is created by prepending \fIM\fP to the name of the file, with the | |
93 | trailing \fB.c\fP and any leading pathname components removed. This | |
94 | makes use of \fIctags\fP practical in directories with more than one | |
95 | program. | |
cab8f024 KM |
96 | .SH FILES |
97 | .DT | |
8c5e71ad | 98 | tags default output tags file |
28048a77 KB |
99 | .SH DIAGNOSTICS |
100 | \fICtags\fP exits with a value of 1 if an error occurred, where | |
101 | duplicate objects are not considered errors, 0 otherwise. | |
cab8f024 KM |
102 | .SH SEE ALSO |
103 | ex(1), vi(1) | |
104 | .SH AUTHOR | |
8c5e71ad KB |
105 | Ken Arnold; FORTRAN added by Jim Kleckner; Bill Joy added Pascal and |
106 | \fB-x\fP, replacing \fIcxref\fP; C typedefs added by Ed Pelegri-Llopart. | |
cab8f024 KM |
107 | .SH BUGS |
108 | Recognition of \fBfunctions\fR, \fBsubroutines\fR and \fBprocedures\fR | |
8c5e71ad KB |
109 | for FORTRAN and Pascal is done is a very simpleminded way. No attempt |
110 | is made to deal with block structure; if you have two Pascal procedures | |
111 | in different blocks with the same name you lose. \fICtags\fP doesn't | |
112 | understand about Pascal types. | |
cab8f024 | 113 | .PP |
8c5e71ad | 114 | The method of deciding whether to look for C, Pascal or FORTRAN |
cab8f024 | 115 | functions is a hack. |
5d15751e | 116 | .PP |
8c5e71ad KB |
117 | \fICtags\fP relies on the input being well formed, and any syntactical |
118 | errors will completely confuse it. It also finds some legal syntax | |
119 | confusing; for example, as it doesn't understand \fI#ifdef\fP's, | |
120 | (incidentally, that's a feature, not a bug) any code with unbalanced | |
121 | braces inside \fI#ifdef\fP's will cause it to become somewhat disoriented. | |
122 | In a similar fashion, multiple line changes within a definition will | |
123 | cause it to enter the last line of the object, rather than the first, as | |
124 | the searching pattern. The last line of multiple line \fItypedef\fP's | |
125 | will similarly be noted. |