usr.bin/ctags/ctags.1

   1 .\"     $NetBSD: ctags.1,v 1.14 2003/02/25 10:35:39 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1987, 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)ctags.1     8.1 (Berkeley) 6/6/93
  31 .\"
  32 .Dd June 6, 1993
  33 .Dt CTAGS 1
  34 .Os
  35 .Sh NAME
  36 .Nm ctags
  37 .Nd create a tags file
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl BFadtuwvx
  41 .Op Fl f Ar tagsfile
  42 .Ar name ...
  43 .Sh DESCRIPTION
  44 .Nm
  45 makes a tags file for
  46 .Xr ex 1
  47 from the specified C,
  48 Pascal, Fortran,
  49 .Tn YACC ,
  50 lex, and lisp sources.
  51 A tags file gives the locations of specified objects in a group of files.
  52 Each line of the tags file contains the object name, the file in which it
  53 is defined, and a search pattern for the object definition, separated by
  54 white-space.
  55 Using the
  56 .Ar tags
  57 file,
  58 .Xr ex 1
  59 can quickly locate these object definitions.
  60 Depending upon the options provided to
  61 .Nm ,
  62 objects will consist of subroutines, typedefs, defines, structs,
  63 enums and unions.
  64 .Bl -tag -width Ds
  65 .It Fl B
  66 use backward searching patterns
  67 .Pq Li ?...? .
  68 .It Fl F
  69 use forward searching patterns
  70 .Pq Li /.../
  71 (the default).
  72 .It Fl a
  73 append to
  74 .Ar tags
  75 file.
  76 .It Fl d
  77 create tags for
  78 .Li #defines
  79 that don't take arguments;
  80 .Li #defines
  81 that take arguments are tagged automatically.
  82 .It Fl f
  83 Places the tag descriptions in a file called
  84 .Ar tagsfile .
  85 The default behaviour is to place them in a file called
  86 .Ar tags .
  87 .It Fl t
  88 create tags for typedefs, structs, unions, and enums.
  89 .It Fl u
  90 update the specified files in the
  91 .Ar tags
  92 file, that is, all
  93 references to them are deleted, and the new values are appended to the
  94 file.
  95 (Beware: this option is implemented in a way which is rather
  96 slow; it is usually faster to simply rebuild the
  97 .Ar tags
  98 file.)
  99 .It Fl v
 100 An index of the form expected by
 101 .Xr vgrind 1
 102 is produced on the standard output.
 103 This listing
 104 contains the object name, file name, and page number (assuming 64
 105 line pages).
 106 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 \*[Gt] 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.
 121 This
 122 is a simple index which can be printed out as an off-line readable
 123 function index.
 124 .El
 125 .Pp
 126 Files whose names end in
 127 .Sq \&.c
 128 or
 129 .Sq \&.h
 130 are assumed to be C
 131 source files and are searched for C style routine and macro definitions.
 132 Files whose names end in
 133 .Sq \&.y
 134 are assumed to be
 135 .Tn YACC
 136 source files.
 137 Files whose names end in
 138 .Sq \&.l
 139 are assumed to be lisp files if their
 140 first non-blank character is
 141 .Sq \&; ,
 142 .Sq \&( ,
 143 or
 144 .Sq \&[ ,
 145 otherwise, they are
 146 treated as lex files.
 147 Other files are first examined to see if they
 148 contain any Pascal or Fortran routine definitions, and, if not, are
 149 searched for C style definitions.
 150 .Pp
 151 The tag
 152 .Li main
 153 is treated specially in C programs.
 154 The tag formed
 155 is created by prepending
 156 .Ar M
 157 to the name of the file, with the
 158 trailing
 159 .Sq \&.c
 160 and any leading pathname components removed.
 161 This
 162 makes use of
 163 .Nm
 164 practical in directories with more than one
 165 program.
 166 .Pp
 167 Yacc and lex files each have a special tag.
 168 .Ar Yyparse
 169 is the start
 170 of the second section of the yacc file, and
 171 .Ar yylex
 172 is the start of
 173 the second section of the lex file.
 174 .Sh EXIT STATUS
 175 .Nm
 176 exits with a value of 1 if an error occurred, 0 otherwise.
 177 Duplicate objects are not considered errors.
 178 .Sh FILES
 179 .Bl -tag -width tags -compact
 180 .It Pa tags
 181 default output tags file
 182 .El
 183 .Sh SEE ALSO
 184 .Xr ex 1 ,
 185 .Xr vi 1
 186 .Sh HISTORY
 187 The
 188 .Nm
 189 command appeared in
 190 .Bx 3.0 .
 191 .Sh BUGS
 192 Recognition of
 193 .Em functions  ,
 194 .Em subroutines
 195 and
 196 .Em procedures
 197 for
 198 .Tn FORTRAN
 199 and Pascal is done in a very simpleminded way.
 200 No attempt
 201 is made to deal with block structure; if you have two Pascal procedures
 202 in different blocks with the same name you lose.
 203 .Nm
 204 doesn't
 205 understand about Pascal types.
 206 .Pp
 207 The method of deciding whether to look for C, Pascal or
 208 .Tn FORTRAN
 209 functions is a hack.
 210 .Pp
 211 .Nm
 212 relies on the input being well formed, and any syntactical
 213 errors will completely confuse it.
 214 It also finds some legal syntax
 215 confusing; for example, since it doesn't understand
 216 .Li #ifdef Ns 's
 217 (incidentally, that's a feature, not a bug), any code with unbalanced
 218 braces inside
 219 .Li #ifdef Ns 's
 220 will cause it to become somewhat disoriented.
 221 In a similar fashion, multiple line changes within a definition will
 222 cause it to enter the last line of the object, rather than the first, as
 223 the searching pattern.
 224 The last line of multiple line
 225 .Li typedef Ns 's
 226 will similarly be noted.