Man Pages

ctags(1p) - phpMan ctags(1p) - phpMan

Command: man perldoc info search(apropos)  


CTAGS(1P)                  POSIX Programmer's Manual                 CTAGS(1P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

NAME
       ctags - create a tags file (DEVELOPMENT, FORTRAN)

SYNOPSIS
       ctags [-a][-f tagsfile] pathname ...

       ctags -x pathname ...


DESCRIPTION
       The ctags 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.

       The  ctags utility shall write a tagsfile or an index of objects from C-language or FORTRAN source files speci-
       fied by the pathname operands. The tagsfile 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.

OPTIONS
       The  ctags  utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility
       Syntax Guidelines.

       The following options shall be supported:

       -a     Append to tagsfile.

       -f  tagsfile
              Write the object locator lists into tagsfile instead of the default  file  named  tags  in  the  current
              directory.

       -x     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 tagsfile shall not be  created  when  -x  is
              specified.


OPERANDS
       The following pathname operands are supported:

       file.c Files  with  basenames  ending with the .c suffix shall be treated as C-language source code. Such files
              that are not valid input to c99 produce unspecified results.

       file.h Files with basenames ending with the .h suffix shall be treated as C-language source  code.  Such  files
              that are not valid input to c99 produce unspecified results.

       file.f Files  with  basenames  ending with the .f suffix shall be treated as FORTRAN-language source code. Such
              files that are not valid input to fort77 produce unspecified results.


       The handling of other files is implementation-defined.

STDIN
       See the INPUT FILES section.

INPUT FILES
       The input files shall be text files containing source code in the language indicated by  the  operand  filename
       suffixes.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of ctags:

       LANG   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  prece-
              dence of internationalization variables used to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values of all the other internationalization variables.

       LC_COLLATE

              Determine the order in which output is sorted for the -x option.  The POSIX locale determines the  order
              in which the tagsfile is written.

       LC_CTYPE
              Determine  the locale for the interpretation of sequences of bytes of text data as characters (for exam-
              ple, 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.

       LC_MESSAGES
              Determine the locale that should be used to affect the format and contents of diagnostic messages  writ-
              ten to standard error.

       NLSPATH
              Determine the location of message catalogs for the processing of LC_MESSAGES .


ASYNCHRONOUS EVENTS
       Default.

STDOUT
       The  list  of object name information produced by the -x option shall be written to standard output in the fol-
       lowing format:


              "%s %d %s %s", <object-name>, <line-number>, <filename>, <text>

       where <text> is the text of line <line-number> of file <filename>.

STDERR
       The standard error shall be used only for diagnostic messages.

OUTPUT FILES
       When the -x option is not specified, the format of the output file shall be:


              "%s\t%s\t/%s/\n", <identifier>, <filename>, <pattern>

       where <pattern> is a search pattern that could be used by an editor to find the defining instance  of  <identi-
       fier>  in  <filename> (where defining instance is indicated by the declarations listed in the EXTENDED DESCRIP-
       TION).

       An optional circumflex ( '^' ) can be added as a prefix to <pattern>,  and  an  optional  dollar  sign  can  be
       appended  to  <pattern>  to indicate that the pattern is anchored to the beginning (end) of a line of text. Any
       slash or backslash characters in <pattern> shall be preceded by a backslash character.  The  anchoring  circum-
       flex,  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.

       An alternative format is:


              "%s\t%s\t?%s?\n", <identifier>, <filename>, <pattern>

       which is identical to the first format except that slashes in <pattern> shall not be preceded by escaping back-
       slash characters, and question mark characters in <pattern> shall be preceded by backslash characters.

       A second alternative format is:


              "%s\t%s\t%d\n", <identifier>, <filename>, <lineno>

       where <lineno> is a decimal line number that could be used by an editor to find <identifier> in <filename>.

       Neither alternative format shall be produced by ctags 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 for-
       mat.

       In  any  of these formats, the file shall be sorted by identifier, based on the collation sequence in the POSIX
       locale.

EXTENDED DESCRIPTION
       If the operand identifies C-language source, the ctags utility shall attempt to produce an output line for each
       of the following objects:

        * Function definitions


        * Type definitions


        * Macros with arguments


       It may also produce output for any of the following objects:

        * Function prototypes


        * Structures


        * Unions


        * Global variable definitions


        * Enumeration types


        * Macros without arguments


        * #define statements


        * #line statements


       Any  #if  and  #ifdef statements shall produce no output.  The tag main is treated specially in C programs. The
       tag formed shall be created by prefixing M to the name of the file, with the trailing .c, and leading  pathname
       components (if any) removed.

       On  systems that do not support the C-Language Development Utilities option, ctags 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.

       If the operand identifies FORTRAN source, the ctags utility shall produce an output line for each function def-
       inition. It may also produce output for any of the following objects:

        * Subroutine definitions


        * COMMON statements


        * PARAMETER statements


        * DATA and BLOCK DATA statements


        * Statement numbers


       On systems that do not support the FORTRAN Development Utilities option, ctags 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.

       It is implementation-defined what other objects (including duplicate identifiers) produce output.

EXIT STATUS
       The following exit values shall be returned:

        0     Successful completion.

       >0     An error occurred.


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The output with -x is meant to be a simple index that can be written  out  as  an  off-line  readable  function
       index.  If the input files to ctags (such as .c files) were not created using the same locale as that in effect
       when ctags -x is run, results might not be as expected.

       The description of C-language processing says "attempts to" because the C language  can  be  greatly  confused,
       especially through the use of #defines, and this utility would be of no use if the real C preprocessor were run
       to identify them. The output from ctags may be fooled and incorrect for various constructs.

EXAMPLES
       None.

RATIONALE
       The option list was significantly reduced from that provided by historical implementations. The -F  option  was
       omitted  as  redundant, since it is the default. The -B option was omitted as being of very limited usefulness.
       The -t option was omitted since the recognition of typedefs is now required for C source files. The  -u  option
       was omitted because the update function was judged to be not only inefficient, but also rarely needed.

       An  early  proposal  included a -w option to suppress warning diagnostics.  Since the types of such diagnostics
       could not be described, the option was omitted as being not useful.

       The text for LC_CTYPE 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 differ-
       ent  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.

       The collation sequence of the tags file is not affected by LC_COLLATE because it is typically not used by human
       readers,  but  only  by  programs  such as vi to locate the tag within the source files. Using the POSIX locale
       eliminates some of the problems of coordinating locales between the ctags file creator and the vi file  reader.

       Historically,  the  tags  file  has been used only by ex and vi.  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 vi recognizes either. The ctags 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 cir-
       cumflex 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.

       Historical  implementations  also  understand  the objects used by the languages Pascal and sometimes LISP, and
       they understand the C source output by lex and yacc. The ctags utility is not  required  to  accommodate  these
       languages, although implementors are encouraged to do so.

       The   following   historical  option  was  not  specified,  as  vgrind  is  not  included  in  this  volume  of
       IEEE Std 1003.1-2001:

       -v     If the -v flag is given, an index of the form expected by vgrind 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 sort -f.   Sample
              use:


              ctags -v files | sort -f > index vgrind -x index


       The  special  treatment of the tag main makes the use of ctags practical in directories with more than one pro-
       gram.

FUTURE DIRECTIONS
       None.

SEE ALSO
       c99, fort77, vi

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                            CTAGS(1P)