usr.bin/ctags/ctags.1

   1 .\" Copyright (c) 1987, 1990, 1993
   2 .\"     The Regents of the University of California.  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     8.1 (Berkeley) 6/6/93
  33 .\" $FreeBSD: src/usr.bin/ctags/ctags.1,v 1.5.2.6 2002/07/30 01:06:31 tjr Exp $
  34 .\"
  35 .Dd June 6, 1993
  36 .Dt CTAGS 1
  37 .Os
  38 .Sh NAME
  39 .Nm ctags
  40 .Nd create a
  41 .Pa tags
  42 file
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Op Fl BFadtuwvx
  46 .Op Fl f Ar tagsfile
  47 .Ar name ...
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility makes a
  52 .Pa tags
  53 file for
  54 .Xr ex 1
  55 from the specified C,
  56 Pascal, Fortran,
  57 .Xr yacc 1 ,
  58 .Xr lex 1 ,
  59 and Lisp sources.
  60 A tags file gives the locations of specified objects in a group of files.
  61 Each line of the tags file contains the object name, the file in which it
  62 is defined, and a search pattern for the object definition, separated by
  63 white-space.
  64 Using the
  65 .Pa tags
  66 file,
  67 .Xr ex 1
  68 can quickly locate these object definitions.
  69 Depending upon the options provided to
  70 .Nm ,
  71 objects will consist of subroutines, typedefs, defines, structs,
  72 enums and unions.
  73 .Pp
  74 The following options are available:
  75 .Bl -tag -width indent
  76 .It Fl B
  77 Use backward searching patterns
  78 .Pq Li ?...? .
  79 .It Fl F
  80 Use forward searching patterns
  81 .Pq Li /.../
  82 (the default).
  83 .It Fl a
  84 Append to
  85 .Pa tags
  86 file.
  87 .It Fl d
  88 Create tags for
  89 .Li #defines
  90 that do not take arguments;
  91 .Li #defines
  92 that take arguments are tagged automatically.
  93 .It Fl f
  94 Place the tag descriptions in a file called
  95 .Ar tagsfile .
  96 The default behaviour is to place them in a file called
  97 .Pa tags .
  98 .It Fl t
  99 Create tags for typedefs, structs, unions, and enums.
 100 .It Fl u
 101 Update the specified files in the
 102 .Pa tags
 103 file, that is, all
 104 references to them are deleted, and the new values are appended to the
 105 file.
 106 (Beware: this option is implemented in a way which is rather
 107 slow; it is usually faster to simply rebuild the
 108 .Pa tags
 109 file.)
 110 .It Fl v
 111 An index of the form expected by
 112 .Xr vgrind 1
 113 is produced on the standard output.
 114 This listing
 115 contains the object name, file name, and page number (assuming 64
 116 line pages).
 117 Since the output will be sorted into lexicographic order,
 118 it may be desired to run the output through
 119 .Xr sort 1 .
 120 Sample use:
 121 .Bd -literal -offset indent
 122 ctags -v files | sort -f > index
 123 vgrind -x index
 124 .Ed
 125 .It Fl w
 126 Suppress warning diagnostics.
 127 .It Fl x
 128 .Nm
 129 produces a list of object
 130 names, the line number and file name on which each is defined, as well
 131 as the text of that line and prints this on the standard output.
 132 This
 133 is a simple index which can be printed out as an off-line readable
 134 function index.
 135 .El
 136 .Pp
 137 Files whose names end in
 138 .Pa .c
 139 or
 140 .Pa .h
 141 are assumed to be C
 142 source files and are searched for C style routine and macro definitions.
 143 Files whose names end in
 144 .Pa .y
 145 are assumed to be
 146 .Xr yacc 1
 147 source files.
 148 Files whose names end in
 149 .Pa .l
 150 are assumed to be Lisp files if their
 151 first non-blank character is
 152 .Ql \&; ,
 153 .Ql \&( ,
 154 or
 155 .Ql \&[ ,
 156 otherwise, they are
 157 treated as
 158 .Xr lex 1
 159 files.
 160 Other files are first examined to see if they
 161 contain any Pascal or Fortran routine definitions, and, if not, are
 162 searched for C style definitions.
 163 .Pp
 164 The tag
 165 .Dq Li main
 166 is treated specially in C programs.
 167 The tag formed
 168 is created by prepending
 169 .Ql M
 170 to the name of the file, with the
 171 trailing
 172 .Pa .c
 173 and any leading pathname components removed.
 174 This makes use of
 175 .Nm
 176 practical in directories with more than one
 177 program.
 178 .Pp
 179 .Xr yacc 1
 180 and
 181 .Xr lex 1
 182 files each have a special tag.
 183 .Dq Li yyparse
 184 is the start
 185 of the second section of the
 186 .Xr yacc 1
 187 file, and
 188 .Dq Li yylex
 189 is the start of
 190 the second section of the
 191 .Xr lex 1
 192 file.
 193 .Sh FILES
 194 .Bl -tag -width ".Pa tags" -compact
 195 .It Pa tags
 196 default output tags file
 197 .El
 198 .Sh DIAGNOSTICS
 199 The
 200 .Nm
 201 utility exits with a value of 1 if an error occurred, 0 otherwise.
 202 Duplicate objects are not considered errors.
 203 .Sh SEE ALSO
 204 .Xr ex 1 ,
 205 .Xr vi 1
 206 .Sh HISTORY
 207 The
 208 .Nm
 209 utility appeared in
 210 .Bx 3.0 .
 211 .Sh BUGS
 212 Recognition of functions, subroutines and procedures
 213 for Fortran and Pascal is done in a very simpleminded way.
 214 No attempt
 215 is made to deal with block structure; if you have two Pascal procedures
 216 in different blocks with the same name you lose.
 217 The
 218 .Nm
 219 utility does not
 220 understand about Pascal types.
 221 .Pp
 222 The method of deciding whether to look for C, Pascal or
 223 Fortran
 224 functions is a hack.
 225 .Pp
 226 The
 227 .Nm
 228 utility relies on the input being well formed, and any syntactical
 229 errors will completely confuse it.
 230 It also finds some legal syntax
 231 confusing; for example, since it does not understand
 232 .Li #ifdef Ns 's
 233 (incidentally, that is a feature, not a bug), any code with unbalanced
 234 braces inside
 235 .Li #ifdef Ns 's
 236 will cause it to become somewhat disoriented.
 237 In a similar fashion, multiple line changes within a definition will
 238 cause it to enter the last line of the object, rather than the first, as
 239 the searching pattern.
 240 The last line of multiple line
 241 .Li typedef Ns 's
 242 will similarly be noted.