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: head/usr.bin/ctags/ctags.1 216370 2010-12-11 08:32:16Z joel $
  30 .\"
  31 .Dd May 6, 2016
  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 BFTadtuwvx
  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 a
  80 Append to
  81 .Pa tags
  82 file.
  83 .It Fl d
  84 Create tags for
  85 .Li #defines
  86 that do not take arguments;
  87 .Li #defines
  88 that take arguments are tagged automatically.
  89 .It Fl f
  90 Place the tag descriptions in a file called
  91 .Ar tagsfile .
  92 The default behaviour is to place them in a file called
  93 .Pa tags .
  94 .It Fl t
  95 Create tags for typedefs, structs, unions, and enums (default).
  96 .It Fl T
  97 Do not create tags for typedefs, structs, unions, and enums.
  98 .It Fl u
  99 Update the specified files in the
 100 .Pa tags
 101 file, that is, all
 102 references to them are deleted, and the new values are appended to the
 103 file.
 104 (Beware: this option is implemented in a way which is rather
 105 slow; it is usually faster to simply rebuild the
 106 .Pa tags
 107 file.)
 108 .It Fl v
 109 An index of the form expected by
 110 .Xr vgrind 1
 111 is produced on the standard output.
 112 This listing
 113 contains the object name, file name, and page number (assuming 64
 114 line pages).
 115 Since the output will be sorted into lexicographic order,
 116 it may be desired to run the output through
 117 .Xr sort 1 .
 118 Sample use:
 119 .Bd -literal -offset indent
 120 ctags -v files | sort -f > index
 121 vgrind -x index
 122 .Ed
 123 .It Fl w
 124 Suppress warning diagnostics.
 125 .It Fl x
 126 .Nm
 127 produces a list of object
 128 names, the line number and file name on which each is defined, as well
 129 as the text of that line and prints this on the standard output.
 130 This
 131 is a simple index which can be printed out as an off-line readable
 132 function index.
 133 .El
 134 .Pp
 135 Files whose names end in
 136 .Pa .c
 137 or
 138 .Pa .h
 139 are assumed to be C
 140 source files and are searched for C style routine and macro definitions.
 141 Files whose names end in
 142 .Pa .y
 143 are assumed to be
 144 .Xr yacc 1
 145 source files.
 146 Files whose names end in
 147 .Pa .l
 148 are assumed to be Lisp files if their
 149 first non-blank character is
 150 .Ql \&; ,
 151 .Ql \&( ,
 152 or
 153 .Ql \&[ ,
 154 otherwise, they are
 155 treated as
 156 .Xr lex 1
 157 files.
 158 Other files are first examined to see if they
 159 contain any Pascal or Fortran routine definitions, and, if not, are
 160 searched for C style definitions.
 161 .Pp
 162 The tag
 163 .Dq Li main
 164 is treated specially in C programs.
 165 The tag formed
 166 is created by prepending
 167 .Ql M
 168 to the name of the file, with the
 169 trailing
 170 .Pa .c
 171 and any leading pathname components removed.
 172 This makes use of
 173 .Nm
 174 practical in directories with more than one
 175 program.
 176 .Pp
 177 The
 178 .Xr yacc 1
 179 and
 180 .Xr lex 1
 181 files each have a special tag.
 182 .Dq Li yyparse
 183 is the start
 184 of the second section of the
 185 .Xr yacc 1
 186 file, and
 187 .Dq Li yylex
 188 is the start of
 189 the second section of the
 190 .Xr lex 1
 191 file.
 192 .Sh FILES
 193 .Bl -tag -width ".Pa tags" -compact
 194 .It Pa tags
 195 default output tags file
 196 .El
 197 .Sh EXIT STATUS
 198 .Ex -std
 199 Duplicate objects are not considered errors.
 200 .Sh COMPATIBILITY
 201 The
 202 .Fl t
 203 option is a no-op for compatibility with previous versions of
 204 .Nm
 205 that did not create tags for typedefs, enums, structs and unions
 206 by default.
 207 .Sh SEE ALSO
 208 .Xr ex 1 ,
 209 .Xr vi 1
 210 .Sh STANDARDS
 211 The
 212 .Nm
 213 utility conforms to
 214 .St -p1003.1-2008 .
 215 .Sh HISTORY
 216 The
 217 .Nm
 218 utility appeared in
 219 .Bx 3.0 .
 220 .Sh BUGS
 221 Recognition of functions, subroutines and procedures
 222 for Fortran and Pascal is done in a very simpleminded way.
 223 No attempt
 224 is made to deal with block structure; if you have two Pascal procedures
 225 in different blocks with the same name you lose.
 226 The
 227 .Nm
 228 utility does not
 229 understand about Pascal types.
 230 .Pp
 231 The method of deciding whether to look for C, Pascal or
 232 Fortran
 233 functions is a hack.
 234 .Pp
 235 The
 236 .Nm
 237 utility relies on the input being well formed, and any syntactical
 238 errors will completely confuse it.
 239 It also finds some legal syntax
 240 confusing; for example, since it does not understand
 241 .Li #ifdef Ns 's
 242 (incidentally, that is a feature, not a bug), any code with unbalanced
 243 braces inside
 244 .Li #ifdef Ns 's
 245 will cause it to become somewhat disoriented.
 246 In a similar fashion, multiple line changes within a definition will
 247 cause it to enter the last line of the object, rather than the first, as
 248 the searching pattern.
 249 The last line of multiple line
 250 .Li typedef Ns 's
 251 will similarly be noted.