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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)ctags.1     8.1 (Berkeley) 6/6/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 23, 2023
  32 .Dt CTAGS 1
  33 .Os
  34 .Sh NAME
  35 .Nm ctags
  36 .Nd create a
  37 .Pa tags
  38 file
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl BFTaduwvx
  42 .Op Fl f Ar tagsfile
  43 .Ar
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility makes a
  48 .Pa tags
  49 file for
  50 .Xr ex 1
  51 from the specified C,
  52 Pascal, Fortran,
  53 .Xr yacc 1 ,
  54 .Xr lex 1 ,
  55 and Lisp sources.
  56 A tags file gives the locations of specified objects in a group of files.
  57 Each line of the tags file contains the object name, the file in which it
  58 is defined, and a search pattern for the object definition, separated by
  59 white-space.
  60 Using the
  61 .Pa tags
  62 file,
  63 .Xr ex 1
  64 can quickly locate these object definitions.
  65 Depending upon the options provided to
  66 .Nm ,
  67 objects will consist of subroutines, typedefs, defines, structs,
  68 enums and unions.
  69 .Pp
  70 The following options are available:
  71 .Bl -tag -width indent
  72 .It Fl B
  73 Use backward searching patterns
  74 .Pq Li ?...? .
  75 .It Fl F
  76 Use forward searching patterns
  77 .Pq Li /.../
  78 (the default).
  79 .It Fl T
  80 Do not create tags for typedefs, structs, unions, and enums.
  81 .It Fl a
  82 Append to
  83 .Pa tags
  84 file.
  85 .It Fl d
  86 Create tags for
  87 .Li #defines
  88 that do not take arguments;
  89 .Li #defines
  90 that take arguments are tagged automatically.
  91 .It Fl f
  92 Place the tag descriptions in a file called
  93 .Ar tagsfile .
  94 The default behaviour is to place them in a file called
  95 .Pa tags .
  96 If
  97 .Ar tagsfile
  98 is
  99 .Dq - ,
 100 the tags will be written to standard output instead.
 101 .It Fl u
 102 Update the specified files in the
 103 .Pa tags
 104 file, that is, all
 105 references to them are deleted, and the new values are appended to the
 106 file.
 107 This is ignored if the tags file does not exist or is not a regular
 108 file (e.g.
 109 .Fl f Ns -
 110 was used to write to standard output).
 111 .Pp
 112 Beware: this option is implemented in a way which is rather
 113 slow; it is usually faster to simply rebuild the
 114 .Pa tags
 115 file.
 116 .It Fl v
 117 An index of the form expected by
 118 .Xr vgrind 1
 119 is produced on the standard output.
 120 This listing
 121 contains the object name, file name, and page number (assuming 64
 122 line pages).
 123 Since the output will be sorted into lexicographic order,
 124 it may be desired to run the output through
 125 .Xr sort 1 .
 126 Sample use:
 127 .Bd -literal -offset indent
 128 ctags -v files | sort -f > index
 129 vgrind -x index
 130 .Ed
 131 .It Fl w
 132 Suppress warning diagnostics.
 133 .It Fl x
 134 .Nm
 135 produces a list of object
 136 names, the line number and file name on which each is defined, as well
 137 as the text of that line and prints this on the standard output.
 138 This
 139 is a simple index which can be printed out as an off-line readable
 140 function index.
 141 .El
 142 .Pp
 143 Files whose names end in
 144 .Pa .c
 145 or
 146 .Pa .h
 147 are assumed to be C
 148 source files and are searched for C style routine and macro definitions.
 149 Files whose names end in
 150 .Pa .y
 151 are assumed to be
 152 .Xr yacc 1
 153 source files.
 154 Files whose names end in
 155 .Pa .l
 156 are assumed to be Lisp files if their
 157 first non-blank character is
 158 .Ql \&; ,
 159 .Ql \&( ,
 160 or
 161 .Ql \&[ ,
 162 otherwise, they are
 163 treated as
 164 .Xr lex 1
 165 files.
 166 Other files are first examined to see if they
 167 contain any Pascal or Fortran routine definitions, and, if not, are
 168 searched for C style definitions.
 169 .Pp
 170 The tag
 171 .Dq Li main
 172 is treated specially in C programs.
 173 The tag formed
 174 is created by prepending
 175 .Ql M
 176 to the name of the file, with the
 177 trailing
 178 .Pa .c
 179 and any leading pathname components removed.
 180 This makes use of
 181 .Nm
 182 practical in directories with more than one
 183 program.
 184 .Pp
 185 The
 186 .Xr yacc 1
 187 and
 188 .Xr lex 1
 189 files each have a special tag.
 190 .Dq Li yyparse
 191 is the start
 192 of the second section of the
 193 .Xr yacc 1
 194 file, and
 195 .Dq Li yylex
 196 is the start of
 197 the second section of the
 198 .Xr lex 1
 199 file.
 200 .Sh FILES
 201 .Bl -tag -width ".Pa tags" -compact
 202 .It Pa tags
 203 default output tags file
 204 .El
 205 .Sh EXIT STATUS
 206 The
 207 .Nm
 208 utility exits with a value of 1 if an error occurred, 0 otherwise.
 209 Duplicate objects are not considered errors.
 210 .Sh COMPATIBILITY
 211 The
 212 .Fl t
 213 option is a no-op for compatibility with previous versions of
 214 .Nm
 215 that did not create tags for typedefs, enums, structs and unions
 216 by default.
 217 .Sh SEE ALSO
 218 .Xr ex 1 ,
 219 .Xr vi 1
 220 .Sh STANDARDS
 221 The
 222 .Nm
 223 utility conforms to
 224 .St -p1003.1-2001 .
 225 .Sh HISTORY
 226 The
 227 .Nm
 228 utility appeared in
 229 .Bx 3.0 .
 230 .Sh BUGS
 231 Recognition of functions, subroutines and procedures
 232 for Fortran and Pascal is done in a very simpleminded way.
 233 No attempt
 234 is made to deal with block structure; if you have two Pascal procedures
 235 in different blocks with the same name you lose.
 236 The
 237 .Nm
 238 utility does not
 239 understand about Pascal types.
 240 .Pp
 241 The method of deciding whether to look for C, Pascal or
 242 Fortran
 243 functions is a hack.
 244 .Pp
 245 The
 246 .Nm
 247 utility relies on the input being well formed, and any syntactical
 248 errors will completely confuse it.
 249 It also finds some legal syntax
 250 confusing; for example, since it does not understand
 251 .Li #ifdef Ns 's
 252 (incidentally, that is a feature, not a bug), any code with unbalanced
 253 braces inside
 254 .Li #ifdef Ns 's
 255 will cause it to become somewhat disoriented.
 256 In a similar fashion, multiple line changes within a definition will
 257 cause it to enter the last line of the object, rather than the first, as
 258 the searching pattern.
 259 The last line of multiple line
 260 .Li typedef Ns 's
 261 will similarly be noted.