diff options
Diffstat (limited to 'man1p/ctags.1p')
| -rw-r--r-- | man1p/ctags.1p | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/man1p/ctags.1p b/man1p/ctags.1p new file mode 100644 index 000000000..14526c528 --- /dev/null +++ b/man1p/ctags.1p @@ -0,0 +1,414 @@ +.\" 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 . |