Annotation of src/usr.bin/ctags/ctags.1, Revision 1.23
1.23 ! millert 1: .\" $OpenBSD: ctags.1,v 1.22 2010/10/19 16:54:15 jmc Exp $
1.1 deraadt 2: .\" $NetBSD: ctags.1,v 1.4 1995/03/26 20:14:04 glass Exp $
3: .\"
4: .\" Copyright (c) 1987, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.12 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)ctags.1 8.1 (Berkeley) 6/6/93
32: .\"
1.23 ! millert 33: .Dd $Mdocdate: October 19 2010 $
1.1 deraadt 34: .Dt CTAGS 1
1.5 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm ctags
38: .Nd create a tags file
39: .Sh SYNOPSIS
40: .Nm ctags
1.23 ! millert 41: .Op Fl aBdFuvwx
1.1 deraadt 42: .Op Fl f Ar tagsfile
1.14 jmc 43: .Ar
1.1 deraadt 44: .Sh DESCRIPTION
1.6 aaron 45: .Nm
1.23 ! millert 46: makes a tags file from the specified, C Pascal, Fortran,
1.1 deraadt 47: .Tn YACC ,
1.23 ! millert 48: lex, and Lisp sources.
1.1 deraadt 49: A tags file gives the locations of specified objects in a group of files.
50: Each line of the tags file contains the object name, the file in which it
51: is defined, and a search pattern for the object definition, separated by
1.8 aaron 52: whitespace.
1.9 aaron 53: .Pp
1.1 deraadt 54: Using the
55: .Ar tags
56: file,
1.23 ! millert 57: a text editor such as
1.1 deraadt 58: .Xr ex 1
1.23 ! millert 59: or
! 60: .Xr vi 1
1.1 deraadt 61: can quickly locate these object definitions.
1.23 ! millert 62: Indexed objects include subroutines, typedefs, defines, structs,
1.3 aaron 63: enums, and unions.
1.9 aaron 64: .Pp
65: The options are as follows:
1.1 deraadt 66: .Bl -tag -width Ds
67: .It Fl a
1.3 aaron 68: Append to
1.1 deraadt 69: .Ar tags
70: file.
1.14 jmc 71: .It Fl B
72: Use backward searching patterns
73: .Pq Li ?...? .
1.1 deraadt 74: .It Fl d
1.3 aaron 75: Create tags for
1.1 deraadt 76: .Li #defines
77: that don't take arguments;
78: .Li #defines
79: that take arguments are tagged automatically.
1.14 jmc 80: .It Fl F
81: Use forward searching patterns
82: .Pq Li /.../
83: (the default).
1.7 deraadt 84: .It Fl f Ar tagsfile
1.1 deraadt 85: Places the tag descriptions in a file called
86: .Ar tagsfile .
87: The default behaviour is to place them in a file called
88: .Ar tags .
89: .It Fl u
1.3 aaron 90: Update the specified files in the
1.1 deraadt 91: .Ar tags
92: file, that is, all
93: references to them are deleted, and the new values are appended to the
1.9 aaron 94: file.
95: (Beware: this option is implemented in a way which is rather
1.1 deraadt 96: slow; it is usually faster to simply rebuild the
97: .Ar tags
98: file.)
99: .It Fl v
1.22 jmc 100: An index of the form expected by vgrind
1.9 aaron 101: is produced on the standard output.
102: This listing contains the object name, file name, and page number (assuming
103: 64 line pages).
104: Since the output will be sorted into lexicographic order,
1.1 deraadt 105: it may be desired to run the output through
106: .Xr sort 1 .
107: Sample use:
108: .Bd -literal -offset indent
1.11 mpech 109: $ ctags \-v files \&| sort \-f > index
110: $ vgrind \-x index
1.1 deraadt 111: .Ed
112: .It Fl w
1.3 aaron 113: Suppress warning diagnostics.
1.1 deraadt 114: .It Fl x
1.6 aaron 115: .Nm
1.1 deraadt 116: produces a list of object
117: names, the line number and file name on which each is defined, as well
1.9 aaron 118: as the text of that line and prints this on the standard output.
119: This is a simple index which can be printed out as an off-line readable
1.1 deraadt 120: function index.
121: .El
122: .Pp
123: Files whose names end in
1.9 aaron 124: .Dq \&.c
1.1 deraadt 125: or
1.9 aaron 126: .Dq \&.h
1.1 deraadt 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
1.9 aaron 130: .Dq \&.y
1.1 deraadt 131: are assumed to be
132: .Tn YACC
133: source files.
134: Files whose names end in
1.9 aaron 135: .Dq \&.l
1.23 ! millert 136: are assumed to be Lisp files if their
1.9 aaron 137: first non-blank character is
138: .Ql \&; ,
1.19 schwarze 139: .Ql \&( ,
1.9 aaron 140: or
1.19 schwarze 141: .Ql \&[ ,
1.1 deraadt 142: otherwise, they are
1.9 aaron 143: treated as lex files.
144: Other files are first examined to see if they
1.1 deraadt 145: contain any Pascal or Fortran routine definitions, and, if not, are
146: searched for C style definitions.
147: .Pp
148: The tag
149: .Li main
1.9 aaron 150: is treated specially in C programs.
151: The tag formed is created by prepending
152: .Sq M
1.1 deraadt 153: to the name of the file, with the
154: trailing
1.9 aaron 155: .Dq \&.c
156: and any leading pathname components removed.
157: This makes use of
1.6 aaron 158: .Nm
1.9 aaron 159: practical in directories with more than one program.
1.1 deraadt 160: .Pp
161: Yacc and lex files each have a special tag.
162: .Ar Yyparse
163: is the start
164: of the second section of the yacc file, and
165: .Ar yylex
166: is the start of
167: the second section of the lex file.
168: .Sh FILES
169: .Bl -tag -width tags -compact
170: .It Pa tags
171: default output tags file
172: .El
1.20 jmc 173: .Sh EXIT STATUS
174: .Ex -std ctags
1.21 jmc 175: .Pp
176: Duplicate objects are not considered errors.
1.1 deraadt 177: .Sh SEE ALSO
178: .Xr ex 1 ,
179: .Xr vi 1
1.15 jmc 180: .Sh STANDARDS
181: The
182: .Nm
183: utility is compliant with the
1.17 jmc 184: .St -p1003.1-2008
1.18 jmc 185: specification,
186: though its presence is optional.
1.15 jmc 187: .Pp
188: The flags
1.23 ! millert 189: .Op Fl BdFuvw
1.15 jmc 190: are extensions to that specification.
1.10 aaron 191: .Sh HISTORY
192: The
193: .Nm
194: command appeared in
195: .Bx 3.0 .
1.1 deraadt 196: .Sh BUGS
197: Recognition of
1.6 aaron 198: .Nm functions ,
1.10 aaron 199: .Nm subroutines ,
1.1 deraadt 200: and
201: .Nm procedures
202: for
203: .Tn FORTRAN
1.9 aaron 204: and Pascal is done in a very simple-minded way.
205: No attempt
1.1 deraadt 206: is made to deal with block structure; if you have two Pascal procedures
207: in different blocks with the same name you lose.
1.6 aaron 208: .Nm
1.1 deraadt 209: doesn't
210: understand about Pascal types.
211: .Pp
212: The method of deciding whether to look for C, Pascal or
213: .Tn FORTRAN
214: functions is a hack.
215: .Pp
1.6 aaron 216: .Nm
1.1 deraadt 217: relies on the input being well formed, and any syntactical
1.9 aaron 218: errors will completely confuse it.
219: It also finds some legal syntax confusing; for example,
220: since it doesn't understand
1.1 deraadt 221: .Li #ifdef Ns 's
222: (incidentally, that's a feature, not a bug), any code with unbalanced
223: braces inside
224: .Li #ifdef Ns 's
225: will cause it to become somewhat disoriented.
226: In a similar fashion, multiple line changes within a definition will
227: cause it to enter the last line of the object, rather than the first, as
1.9 aaron 228: the searching pattern.
229: The last line of multiple line
1.1 deraadt 230: .Li typedef Ns 's
231: will similarly be noted.
![[BACK]](/icons/back.gif){kind=icon}
Return to ctags.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ctags