diff options
author | cwt <cwt@FreeBSD.org> | 1997-08-16 04:13:58 +0000 |
---|---|---|
committer | cwt <cwt@FreeBSD.org> | 1997-08-16 04:13:58 +0000 |
commit | 9061d030a863ba8f4459b970cbd9de2e54ce2769 (patch) | |
tree | f1b6c84881f3a8f4bc5ae8ef2f59326c6076e13d /contrib/global/gctags/gctags.1 | |
download | FreeBSD-src-9061d030a863ba8f4459b970cbd9de2e54ce2769.zip FreeBSD-src-9061d030a863ba8f4459b970cbd9de2e54ce2769.tar.gz |
Import global v2.0 as contributed software. We will maintain it this
way, retiring the sources from usr.bin/global shortly.
Reviewed by: jdp
Discussed-with: obrien
Diffstat (limited to 'contrib/global/gctags/gctags.1')
-rw-r--r-- | contrib/global/gctags/gctags.1 | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/contrib/global/gctags/gctags.1 b/contrib/global/gctags/gctags.1 new file mode 100644 index 0000000..2d55d52 --- /dev/null +++ b/contrib/global/gctags/gctags.1 @@ -0,0 +1,237 @@ +.\" Copyright (c) 1987, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)gctags.1 8.1 (Berkeley) 6/6/93 +.\" +.Dd April 21, 1997 +.Dt GCTAGS 1 +.Os BSD 4 +.Sh NAME +.Nm gctags +.Nd create a tags file (special command for GLOBAL) +.Sh SYNOPSIS +.Nm gctags +.Op Fl BDFadertuwvx +.Op Fl f Ar tagsfile +.Ar name ... +.Sh DESCRIPTION +.Nm Gctags +makes a tags file for +.Xr ex 1 +from the specified C, +Pascal, Fortran, +.Tn YACC , +lex, lisp and assembler sources. +A tags file gives the locations of specified objects in a group of files. +Each line of the tags file contains the object name, the file in which it +is defined, and a search pattern for the object definition, separated by +white-space. +Using the +.Ar tags +file, +.Xr ex 1 +can quickly locate these object definitions. +Depending upon the options provided to +.Nm gctags , +objects will consist of subroutines, typedefs, defines, structs, +enums and unions. +.Bl -tag -width Ds +.It Fl B +use backward searching patterns +.Pq Li ?...? . +.It Fl D +allow duplicate object names. +.It Fl F +use forward searching patterns +.Pq Li /.../ +(the default). +.It Fl a +append to +.Ar tags +file. +.It Fl d +create tags for +.Li #defines +that don't take arguments; +.Li #defines +that take arguments are tagged automatically. +.It Fl e +force a function to end when reach a '}' at the first column. (C source only) +.It Fl f +place the tag descriptions in a file called +.Ar tagsfile . +The default behavior is to place them in a file called +.Ar tags . +.It Fl r +locate function references instead of function definitions. GTAGS file is +needed at the current directory. (C source only) +.It Fl t +create tags for typedefs, structs, unions, and enums. +.It Fl u +update the specified files in the +.Ar tags +file, that is, all +references to them are deleted, and the new values are appended to the +file. (Beware: this option is implemented in a way which is rather +slow; it is usually faster to simply rebuild the +.Ar tags +file.) +.It Fl v +An index of the form expected by +.Xr vgrind 1 +is produced on the standard output. This listing +contains the object name, file name, and page number (assuming 64 +line pages). Since the output will be sorted into lexicographic order, +it may be desired to run the output through +.Xr sort 1 . +Sample use: +.Bd -literal -offset indent +gctags \-v files \&| sort \-f > index +vgrind \-x index +.Ed +.It Fl w +suppress warning diagnostics. +.It Fl x +.Nm gctags +produces a list of object +names, the line number and file name on which each is defined, as well +as the text of that line and prints this on the standard output. This +is a simple index which can be printed out as an off-line readable +function index. +.El +.Pp +Files whose names end in +.Nm \&.c +or +.Nm \&.h +are assumed to be C +source files and are searched for C style routine and macro definitions. +Files whose names end in +.Nm \&.y +are assumed to be +.Tn YACC +source files. +Files whose names end in +.Nm \&.l +are assumed to be lisp files if their +first non-blank character is `;', `(', or `[', +otherwise, they are +treated as lex files. +Files whose names end in +.Nm \&.s +or +.Nm \&.S +are assumed to be Assembler +source files. Other files are first examined to see if they +contain any Pascal or Fortran routine definitions, and, if not, are +searched for C style definitions. +.Pp +The tag +.Li main +is treated specially in C programs. The tag formed +is created by prepending +.Ar M +to the name of the file, with the +trailing +.Nm \&.c +and any leading pathname components removed. This +makes use of +.Nm gctags +practical in directories with more than one +program. +.Pp +Yacc and lex files each have a special tag. +.Ar Yyparse +is the start +of the second section of the yacc file, and +.Ar yylex +is the start of +the second section of the lex file. +.Sh FILES +.Bl -tag -width tags -compact +.It Pa tags +default output tags file +.It Pa GTAGS +tags file for GLOBAL +.El +.Sh DIAGNOSTICS +.Nm Gctags +exits with a value of 1 if an error occurred, 0 otherwise. +Duplicate objects are not considered errors. +.Sh SEE ALSO +.Xr btreeop 1 , +.Xr ex 1 , +.Xr global 1 , +.Xr gtags 1 , +.Xr htags 1 , +.Xr vi 1 . +.Sh BUGS +.Pp +Recognition of +.Nm functions , +.Nm subroutines +and +.Nm procedures +for +.Tn FORTRAN +and Pascal is done is a very simpleminded way. No attempt +is made to deal with block structure; if you have two Pascal procedures +in different blocks with the same name you lose. +.Nm Gctags +doesn't +understand about Pascal types. +.Pp +The method of deciding whether to look for C, Pascal or +.Tn FORTRAN +functions is a hack. +.Pp +.Nm Gctags +relies on the input being well formed, and any syntactical +errors will completely confuse it. It also finds some legal syntax +confusing; for example, since it doesn't understand +.Li #ifdef Ns 's +(incidentally, that's a feature, not a bug), any code with unbalanced +braces inside +.Li #ifdef Ns 's +will cause it to become somewhat disoriented. +In a similar fashion, multiple line changes within a definition will +cause it to enter the last line of the object, rather than the first, as +the searching pattern. The last line of multiple line +.Li typedef Ns 's +will similarly be noted. +.Pp +Assembler support is far from completeness. It extracts only ENTRY() +and ALTENTRY() from source file. Probably valid only for FreeBSD and Linux +kernel source. +.Sh HISTORY +The +.Nm +command appeared in FreeBSD 2.2. |