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