CTAGS(1P)

📦 version 2017a, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, nixpkgs unstable, opensuse-leap 16.0

💖 CTAGS(1P) 💖

POSIX Programmer's Manual — like, the actual official one, bestie. Sit down, grab a boba, we're doing this. 🧋

🌸 PROLOG 🌸

Okay so real talk first: this page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may be different (so go check the matching Linux manual page for the deets on Linux behavior, mmkay?), or honestly the interface might not even be implemented on Linux at all. 🙈 Not my rules, I just work here.

✨ NAME ✨

ctags — create a tags file. And yes it's filed under DEVELOPMENT, FORTRAN. She contains multitudes. 💅

🎀 SYNOPSIS 🎀

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

Two whole moods. Pick one. 🦋

💜 DESCRIPTION 💜

So here's the tea: ctags shall be provided on systems that support the Software Development Utilities option, and either or both of the C-Language Development Utilities option and the FORTRAN Development Utilities option. On other systems? It's optional. She's a guest star, not a series regular. ⭐

The ctags utility shall write a tagsfile — or an index of objects — from C-language or FORTRAN source files, and those source files come from the pathname operands, periodt.

That tagsfile shall list the locators of language-specific objects inside the source files. A locator is literally just three things: a name, a pathname, and either a search pattern or a line number that you can use to go hunt down the object definition. 💅

And which objects get recognized? That's the whole EXTENDED DESCRIPTION section, bestie, we'll get there. No skipping ahead. 👑

🔥 OPTIONS 🔥

The ctags utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines. Rules are rules. ✨

The following options shall be supported:

  • -a — Append to tagsfile. Like, don't overwrite her, just add to the pile. 🫶
  • -f tagsfile — Write the object locator lists into tagsfile instead of the default file named tags in the current directory. You get to pick the name, main character behavior. 👑
  • -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. And a tagsfile shall NOT be created when -x is specified. Not one. None. Zero. 💀

🌈 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. Now, if those files are not valid input to c99, you get unspecified results. So like… don't. 😭
  • file.h — Files with basenames ending with the .h suffix shall be treated as C-language source code. Same deal: files that aren't 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. And if they're not valid input to fort77? You guessed it: unspecified results. 🦋

The handling of other files is implementation-defined. Mystery. Intrigue. It's giving "figure it out." 💅

🍓 STDIN 🍓

See the INPUT FILES section. Yeah, we're pointing you down the hall. 🫶

🌸 INPUT FILES 🌸

The input files shall be text files containing source code in the language indicated by the operand filename suffixes. So the suffix is doing the talking. Slay. ✨

💖 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 POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.) She's the backup dancer that fills in when nobody else shows. 💃
  • LC_ALL — If set to a non-empty string value, override the values of all the other internationalization variables. She overrides everything. Main character energy fr fr. 👑
  • 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. Sorting drama, but make it locale-aware. 🎀
  • LC_CTYPE — 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). And heads up: 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 written to standard error. So your error messages can be ✨aesthetic✨ and in your language.
  • NLSPATH — Determine the location of message catalogs for the processing of LC_MESSAGES. She knows where the message catalogs live. 🗺️

🦋 ASYNCHRONOUS EVENTS 🦋

Default. That's it. That's the section. 💅

⭐ STDOUT ⭐

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

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

where <text> is the text of line <line-number> of file <filename>. Yes bestie, the whole line. The receipts. 🧾

💀 STDERR 💀

The standard error shall be used only for diagnostic messages. She's not here for small talk. 🙈

👑 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 <identifier> in <filename> (where defining instance is indicated by the declarations listed in the EXTENDED DESCRIPTION). So it's a little treasure map for your editor. 🗺️

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 <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. Escaping is serious business, don't skip it. 💅

An alternative format is:

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

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

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>. Just the number, no pattern, no drama. 🔢

Neither alternative format shall be produced by ctags when it is used as described by POSIX.1‐2008, but the standard utilities that process tags files shall be able to process those formats as well as the first format. So she won't make them, but she'll absolutely read them. Versatile. 🌈

In any of these formats, the file shall be sorted by identifier, based on the collation sequence in the POSIX locale. Sorted. Organized. That's the energy. ✨

🌈 EXTENDED DESCRIPTION 🌈

Okay bestie, this is the big one. Lock in. 🔒

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. Sorry preprocessor girlies, she's not doing it. 💀

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. So like, src/thing.c → Mthing. Iconic little quirk. 👑

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. She should tell you what's wrong. Rude if she doesn't. 😤

If the operand identifies FORTRAN source, the ctags utility shall produce an output line for each function definition. 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. Same energy as above, FORTRAN edition. 🦋

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

💜 EXIT STATUS 💜

The following exit values shall be returned:

  • 0 — Successful completion. We ate. 🍽️✨
  • >0 — An error occurred. It's giving "something went wrong." 😭

🎀 CONSEQUENCES OF ERRORS 🎀

Default.

The following sections are informative. (Yes, that means the vibe shifts, bestie — the next parts are the helpful little extras, not the rules-rules.) 📝

🫶 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. Locale mismatch = chaos. Keep your locales consistent, bestie. 🌸

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. So yeah — she can get tricked. She's doing her best. 🥺 No cap.

⭐ EXAMPLES ⭐

None.

…and that's part 1, bestie. Part 2 is right behind this one, so don't go anywhere. 💖

🌸 RATIONALE 🌸

okay bestie, let's unpack why this option list looks the way it does. The whole thing got a major glow-down from historical implementations. Like, not every legacy flag made the cut, and that's on purpose. 💅

  • -F — omitted. It was redundant because it's already the default. Periodt.
  • -B — omitted. It had very limited usefulness, so bye. 👋
  • -t — omitted. Because recognizing typedefs is now required for C source files, so it's just built in.
  • -u — omitted. The update function was judged to be not only inefficient, but also rarely needed. So it got ghosted. 💀

An early proposal included a -w option to suppress warning diagnostics. But since the types of such diagnostics could not be described, the option was omitted as being not useful. No -w for you. 🙈

Then there's the LC_CTYPE text about compatibility with the C locale. It 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 POSIX.1‐2017 is that any time that locales do not match — preparing a file for one locale and processing it in another — the results are suspect. So keep your locales consistent, bestie. No cap. 🫶

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. Slay. ✨

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 <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. So watch those anchors, okay? 🎀

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. Cute. 🌈

The following historical option was not specified, as vgrind is not included in this volume of POSIX.1‐2017:

  • -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 program. Iconic. 👑

🔮 FUTURE DIRECTIONS 🔮

None.

Literally none. The future is a mystery, but this section is not. 💀

👀 SEE ALSO 👀

  • c99
  • fort77
  • vi

Also, from The Base Definitions volume of POSIX.1‐2017: Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines.

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

xoxo, this manual page was served to you by IEEE/The Open Group, dated 2017, and it's literally CTAGS(1P). Stay iconic, bestie. 💖✨🦋

📦 where this page comes from