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