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$
  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 BFTaduwvx
  46 .Op Fl f Ar tagsfile
  47 .Ar
  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 T
  84 Do not create tags for typedefs, structs, unions, and enums.
  85 .It Fl a
  86 Append to
  87 .Pa tags
  88 file.
  89 .It Fl d
  90 Create tags for
  91 .Li #defines
  92 that do not take arguments;
  93 .Li #defines
  94 that take arguments are tagged automatically.
  95 .It Fl f
  96 Place the tag descriptions in a file called
  97 .Ar tagsfile .
  98 The default behaviour is to place them in a file called
  99 .Pa tags .
 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 The
 180 .Xr yacc 1
 181 and
 182 .Xr lex 1
 183 files each have a special tag.
 184 .Dq Li yyparse
 185 is the start
 186 of the second section of the
 187 .Xr yacc 1
 188 file, and
 189 .Dq Li yylex
 190 is the start of
 191 the second section of the
 192 .Xr lex 1
 193 file.
 194 .Sh FILES
 195 .Bl -tag -width ".Pa tags" -compact
 196 .It Pa tags
 197 default output tags file
 198 .El
 199 .Sh EXIT STATUS
 200 The
 201 .Nm
 202 utility exits with a value of 1 if an error occurred, 0 otherwise.
 203 Duplicate objects are not considered errors.
 204 .Sh COMPATIBILITY
 205 The
 206 .Fl t
 207 option is a no-op for compatibility with previous versions of
 208 .Nm
 209 that did not create tags for typedefs, enums, structs and unions
 210 by default.
 211 .Sh SEE ALSO
 212 .Xr ex 1 ,
 213 .Xr vi 1
 214 .Sh STANDARDS
 215 The
 216 .Nm
 217 utility conforms to
 218 .St -p1003.1-2001 .
 219 .Sh HISTORY
 220 The
 221 .Nm
 222 utility appeared in
 223 .Bx 3.0 .
 224 .Sh BUGS
 225 Recognition of functions, subroutines and procedures
 226 for Fortran and Pascal is done in a very simpleminded way.
 227 No attempt
 228 is made to deal with block structure; if you have two Pascal procedures
 229 in different blocks with the same name you lose.
 230 The
 231 .Nm
 232 utility does not
 233 understand about Pascal types.
 234 .Pp
 235 The method of deciding whether to look for C, Pascal or
 236 Fortran
 237 functions is a hack.
 238 .Pp
 239 The
 240 .Nm
 241 utility relies on the input being well formed, and any syntactical
 242 errors will completely confuse it.
 243 It also finds some legal syntax
 244 confusing; for example, since it does not understand
 245 .Li #ifdef Ns 's
 246 (incidentally, that is a feature, not a bug), any code with unbalanced
 247 braces inside
 248 .Li #ifdef Ns 's
 249 will cause it to become somewhat disoriented.
 250 In a similar fashion, multiple line changes within a definition will
 251 cause it to enter the last line of the object, rather than the first, as
 252 the searching pattern.
 253 The last line of multiple line
 254 .Li typedef Ns 's
 255 will similarly be noted.