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