path: root/man1p/ctags.1p

.\" 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 .