mirror of https://github.com/mkerrisk/man-pages
415 lines
13 KiB
Groff
415 lines
13 KiB
Groff
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "CTAGS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" ctags
|
||
|
.SH NAME
|
||
|
ctags \- create a tags file (\fBDEVELOPMENT\fP, \fBFORTRAN\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fBctags\fP \fB[\fP\fB-a\fP\fB][\fP\fB-f\fP \fItagsfile\fP\fB]\fP
|
||
|
\fIpathname\fP \fB...
|
||
|
.br
|
||
|
.sp
|
||
|
ctags -x\fP \fIpathname\fP \fB... \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIctags\fP utility shall be provided on systems that support
|
||
|
the User Portability Utilities option, the Software
|
||
|
Development Utilities option, and either or both of the C-Language
|
||
|
Development Utilities option and FORTRAN Development Utilities
|
||
|
option. On other systems, it is optional.
|
||
|
.LP
|
||
|
The \fIctags\fP utility shall write a \fItagsfile\fP or an index of
|
||
|
objects from C-language or FORTRAN source files specified
|
||
|
by the \fIpathname\fP operands. The \fItagsfile\fP shall list the
|
||
|
locators of language-specific objects within the source files.
|
||
|
A locator consists of a name, pathname, and either a search pattern
|
||
|
or a line number that can be used in searching for the object
|
||
|
definition. The objects that shall be recognized are specified in
|
||
|
the EXTENDED DESCRIPTION section.
|
||
|
.SH OPTIONS
|
||
|
.LP
|
||
|
The \fIctags\fP utility shall conform to the Base Definitions volume
|
||
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
||
|
.LP
|
||
|
The following options shall be supported:
|
||
|
.TP 7
|
||
|
\fB-a\fP
|
||
|
Append to \fItagsfile\fP.
|
||
|
.TP 7
|
||
|
\fB-f\ \fP \fItagsfile\fP
|
||
|
Write the object locator lists into \fItagsfile\fP instead of the
|
||
|
default file named \fBtags\fP in the current
|
||
|
directory.
|
||
|
.TP 7
|
||
|
\fB-x\fP
|
||
|
Produce a list of object names, the line number, and filename in which
|
||
|
each is defined, as well as the text of that line, and
|
||
|
write this to the standard output. A \fItagsfile\fP shall not be created
|
||
|
when \fB-x\fP is specified.
|
||
|
.sp
|
||
|
.SH OPERANDS
|
||
|
.LP
|
||
|
The following \fIpathname\fP operands are supported:
|
||
|
.TP 7
|
||
|
\fIfile\fP\fB.c\fP
|
||
|
Files with basenames ending with the \fB.c\fP suffix shall be treated
|
||
|
as C-language source code. Such files that are not valid
|
||
|
input to \fIc99\fP produce unspecified results.
|
||
|
.TP 7
|
||
|
\fIfile\fP\fB.h\fP
|
||
|
Files with basenames ending with the \fB.h\fP suffix shall be treated
|
||
|
as C-language source code. Such files that are not valid
|
||
|
input to \fIc99\fP produce unspecified results.
|
||
|
.TP 7
|
||
|
\fIfile\fP\fB.f\fP
|
||
|
Files with basenames ending with the \fB.f\fP suffix shall be treated
|
||
|
as FORTRAN-language source code. Such files that are not
|
||
|
valid input to \fIfort77\fP produce unspecified results.
|
||
|
.sp
|
||
|
.LP
|
||
|
The handling of other files is implementation-defined.
|
||
|
.SH STDIN
|
||
|
.LP
|
||
|
See the INPUT FILES section.
|
||
|
.SH INPUT FILES
|
||
|
.LP
|
||
|
The input files shall be text files containing source code in the
|
||
|
language indicated by the operand filename suffixes.
|
||
|
.SH ENVIRONMENT VARIABLES
|
||
|
.LP
|
||
|
The following environment variables shall affect the execution of
|
||
|
\fIctags\fP:
|
||
|
.TP 7
|
||
|
\fILANG\fP
|
||
|
Provide a default value for the internationalization variables that
|
||
|
are unset or null. (See the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
||
|
for
|
||
|
the precedence of internationalization variables used to determine
|
||
|
the values of locale categories.)
|
||
|
.TP 7
|
||
|
\fILC_ALL\fP
|
||
|
If set to a non-empty string value, override the values of all the
|
||
|
other internationalization variables.
|
||
|
.TP 7
|
||
|
\fILC_COLLATE\fP
|
||
|
.sp
|
||
|
Determine the order in which output is sorted for the \fB-x\fP option.
|
||
|
The POSIX locale determines the order in which the
|
||
|
\fItagsfile\fP is written.
|
||
|
.TP 7
|
||
|
\fILC_CTYPE\fP
|
||
|
Determine the locale for the interpretation of sequences of bytes
|
||
|
of text data as characters (for example, single-byte as
|
||
|
opposed to multi-byte characters in arguments and input files). When
|
||
|
processing C-language source code, if the locale is not
|
||
|
compatible with the C locale described by the ISO\ C standard, the
|
||
|
results are unspecified.
|
||
|
.TP 7
|
||
|
\fILC_MESSAGES\fP
|
||
|
Determine the locale that should be used to affect the format and
|
||
|
contents of diagnostic messages written to standard
|
||
|
error.
|
||
|
.TP 7
|
||
|
\fINLSPATH\fP
|
||
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
||
|
\&.\fP
|
||
|
.sp
|
||
|
.SH ASYNCHRONOUS EVENTS
|
||
|
.LP
|
||
|
Default.
|
||
|
.SH STDOUT
|
||
|
.LP
|
||
|
The list of object name information produced by the \fB-x\fP option
|
||
|
shall be written to standard output in the following
|
||
|
format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s %d %s %s", <\fP\fIobject-name\fP\fB>, <\fP\fIline-number\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fItext\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
where <\fItext\fP> is the text of line <\fIline-number\fP> of file
|
||
|
<\fIfilename\fP>.
|
||
|
.SH STDERR
|
||
|
.LP
|
||
|
The standard error shall be used only for diagnostic messages.
|
||
|
.SH OUTPUT FILES
|
||
|
.LP
|
||
|
When the \fB-x\fP option is not specified, the format of the output
|
||
|
file shall be:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s\\t%s\\t/%s/\\n", <\fP\fIidentifier\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fIpattern\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
where <\fIpattern\fP> is a search pattern that could be used by an
|
||
|
editor to find the defining instance of
|
||
|
<\fIidentifier\fP> in <\fIfilename\fP> (where \fIdefining instance\fP
|
||
|
is indicated by the declarations listed in the
|
||
|
EXTENDED DESCRIPTION).
|
||
|
.LP
|
||
|
An optional circumflex ( \fB'^'\fP ) can be added as a prefix to <\fIpattern\fP>,
|
||
|
and an optional dollar sign can be
|
||
|
appended to <\fIpattern\fP> to indicate that the pattern is anchored
|
||
|
to the beginning (end) of a line of text. Any slash or
|
||
|
backslash characters in <\fIpattern\fP> shall be preceded by a backslash
|
||
|
character. The anchoring circumflex, dollar sign,
|
||
|
and escaping backslash characters shall not be considered part of
|
||
|
the search pattern. All other characters in the search pattern
|
||
|
shall be considered literal characters.
|
||
|
.br
|
||
|
.LP
|
||
|
An alternative format is:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s\\t%s\\t?%s?\\n", <\fP\fIidentifier\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fIpattern\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
which is identical to the first format except that slashes in <\fIpattern\fP>
|
||
|
shall not be preceded by escaping backslash
|
||
|
characters, and question mark characters in <\fIpattern\fP> shall
|
||
|
be preceded by backslash characters.
|
||
|
.LP
|
||
|
A second alternative format is:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s\\t%s\\t%d\\n", <\fP\fIidentifier\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fIlineno\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
where <\fIlineno\fP> is a decimal line number that could be used by
|
||
|
an editor to find <\fIidentifier\fP> in
|
||
|
<\fIfilename\fP>.
|
||
|
.LP
|
||
|
Neither alternative format shall be produced by \fIctags\fP when it
|
||
|
is used as described by IEEE\ Std\ 1003.1-2001, but
|
||
|
the standard utilities that process tags files shall be able to process
|
||
|
those formats as well as the first format.
|
||
|
.LP
|
||
|
In any of these formats, the file shall be sorted by identifier, based
|
||
|
on the collation sequence in the POSIX locale.
|
||
|
.SH EXTENDED DESCRIPTION
|
||
|
.LP
|
||
|
If the operand identifies C-language source, the \fIctags\fP utility
|
||
|
shall attempt to produce an output line for each of the
|
||
|
following objects:
|
||
|
.IP " *" 3
|
||
|
Function definitions
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Type definitions
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Macros with arguments
|
||
|
.LP
|
||
|
.LP
|
||
|
It may also produce output for any of the following objects:
|
||
|
.IP " *" 3
|
||
|
Function prototypes
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Structures
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Unions
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Global variable definitions
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Enumeration types
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Macros without arguments
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
\fB#define\fP statements
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
\fB#line\fP statements
|
||
|
.LP
|
||
|
.LP
|
||
|
Any \fB#if\fP and \fB#ifdef\fP statements shall produce no output.
|
||
|
The tag \fBmain\fP is treated specially in C programs. The
|
||
|
tag formed shall be created by prefixing \fBM\fP to the name of the
|
||
|
file, with the trailing \fB.c\fP, and leading pathname
|
||
|
components (if any) removed.
|
||
|
.LP
|
||
|
On systems that do not support the C-Language Development Utilities
|
||
|
option, \fIctags\fP produces unspecified results for
|
||
|
C-language source code files. It should write to standard error a
|
||
|
message identifying this condition and cause a non-zero exit
|
||
|
status to be produced.
|
||
|
.LP
|
||
|
If the operand identifies FORTRAN source, the \fIctags\fP utility
|
||
|
shall produce an output line for each function definition. It
|
||
|
may also produce output for any of the following objects:
|
||
|
.IP " *" 3
|
||
|
Subroutine definitions
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
COMMON statements
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
PARAMETER statements
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
DATA and BLOCK DATA statements
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Statement numbers
|
||
|
.LP
|
||
|
.LP
|
||
|
On systems that do not support the FORTRAN Development Utilities option,
|
||
|
\fIctags\fP produces unspecified results for FORTRAN
|
||
|
source code files. It should write to standard error a message identifying
|
||
|
this condition and cause a non-zero exit status to be
|
||
|
produced.
|
||
|
.LP
|
||
|
It is implementation-defined what other objects (including duplicate
|
||
|
identifiers) produce output.
|
||
|
.SH EXIT STATUS
|
||
|
.LP
|
||
|
The following exit values shall be returned:
|
||
|
.TP 7
|
||
|
\ 0
|
||
|
Successful completion.
|
||
|
.TP 7
|
||
|
>0
|
||
|
An error occurred.
|
||
|
.sp
|
||
|
.SH CONSEQUENCES OF ERRORS
|
||
|
.LP
|
||
|
Default.
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
The output with \fB-x\fP is meant to be a simple index that can be
|
||
|
written out as an off-line readable function index. If the
|
||
|
input files to \fIctags\fP (such as \fB.c\fP files) were not created
|
||
|
using the same locale as that in effect when \fIctags\fP
|
||
|
\fB-x\fP is run, results might not be as expected.
|
||
|
.LP
|
||
|
The description of C-language processing says "attempts to" because
|
||
|
the C language can be greatly confused, especially through
|
||
|
the use of \fB#define\fPs, and this utility would be of no use if
|
||
|
the real C preprocessor were run to identify them. The output
|
||
|
from \fIctags\fP may be fooled and incorrect for various constructs.
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
The option list was significantly reduced from that provided by historical
|
||
|
implementations. The \fB-F\fP option was omitted as
|
||
|
redundant, since it is the default. The \fB-B\fP option was omitted
|
||
|
as being of very limited usefulness. The \fB-t\fP option was
|
||
|
omitted since the recognition of \fBtypedef\fPs is now required for
|
||
|
C source files. The \fB-u\fP option was omitted because the
|
||
|
update function was judged to be not only inefficient, but also rarely
|
||
|
needed.
|
||
|
.LP
|
||
|
An early proposal included a \fB-w\fP option to suppress warning diagnostics.
|
||
|
Since the types of such diagnostics could not be
|
||
|
described, the option was omitted as being not useful.
|
||
|
.LP
|
||
|
The text for \fILC_CTYPE\fP about compatibility with the C locale
|
||
|
acknowledges that the ISO\ C standard imposes
|
||
|
requirements on the locale used to process C source. This could easily
|
||
|
be a superset of that known as "the C locale" by way of
|
||
|
implementation extensions, or one of a few alternative locales for
|
||
|
systems supporting different codesets. No statement is made for
|
||
|
FORTRAN because the ANSI\ X3.9-1978 standard (FORTRAN 77) does not
|
||
|
(yet) define a similar locale concept. However, a general
|
||
|
rule in this volume of IEEE\ Std\ 1003.1-2001 is that any time that
|
||
|
locales do not match (preparing a file for one locale
|
||
|
and processing it in another), the results are suspect.
|
||
|
.LP
|
||
|
The collation sequence of the tags file is not affected by \fILC_COLLATE\fP
|
||
|
because it is typically not used by human readers,
|
||
|
but only by programs such as \fIvi\fP to locate the tag within the
|
||
|
source files. Using the
|
||
|
POSIX locale eliminates some of the problems of coordinating locales
|
||
|
between the \fIctags\fP file creator and the \fIvi\fP file reader.
|
||
|
.LP
|
||
|
Historically, the tags file has been used only by \fIex\fP and \fIvi\fP.
|
||
|
However, the format of the tags file has been published to encourage
|
||
|
other programs to use
|
||
|
the tags in new ways. The format allows either patterns or line numbers
|
||
|
to find the identifiers because the historical \fIvi\fP recognizes
|
||
|
either. The \fIctags\fP utility does not produce the format using
|
||
|
line numbers
|
||
|
because it is not useful following any source file changes that add
|
||
|
or delete lines. The documented search patterns match
|
||
|
historical practice. It should be noted that literal leading circumflex
|
||
|
or trailing dollar-sign characters in the search pattern
|
||
|
will only behave correctly if anchored to the beginning of the line
|
||
|
or end of the line by an additional circumflex or dollar-sign
|
||
|
character.
|
||
|
.LP
|
||
|
Historical implementations also understand the objects used by the
|
||
|
languages Pascal and sometimes LISP, and they understand the
|
||
|
C source output by \fIlex\fP and \fIyacc\fP. The
|
||
|
\fIctags\fP utility is not required to accommodate these languages,
|
||
|
although implementors are encouraged to do so.
|
||
|
.LP
|
||
|
The following historical option was not specified, as \fIvgrind\fP
|
||
|
is not included in this volume of
|
||
|
IEEE\ Std\ 1003.1-2001:
|
||
|
.TP 7
|
||
|
\fB-v\fP
|
||
|
If the \fB-v\fP flag is given, an index of the form expected by \fIvgrind\fP
|
||
|
is produced on the standard output. This listing
|
||
|
contains the function name, filename, and page number (assuming 64-line
|
||
|
pages). Since the output is sorted into lexicographic
|
||
|
order, it may be desired to run the output through \fIsort\fP \fB-f\fP.
|
||
|
Sample use:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBctags -v files | sort -f > index vgrind -x index
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.sp
|
||
|
.LP
|
||
|
The special treatment of the tag \fBmain\fP makes the use of \fIctags\fP
|
||
|
practical in directories with more than one
|
||
|
program.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIc99\fP , \fIfort77\fP , \fIvi\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|