Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
ctags.html (20355B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>ctags</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/csplit.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cut.html" accesskey="N">Next >>></a></td>
19 </tr>
20 </table>
21 <hr align="left" width="100%"></div>
22 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
23 <center><font size="2">The Open Group Base Specifications Issue 8<br>
24 IEEE Std 1003.1-2024<br>
25 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
26 <hr size="2" noshade>
27 <a name="top" id="top"></a> <a name="ctags" id="ctags"></a> <a name="tag_20_27" id="tag_20_27"></a><!-- ctags -->
28 <h4 class="mansect"><a name="tag_20_27_01" id="tag_20_27_01"></a>NAME</h4>
29 <blockquote>ctags — create a tags file (<b>DEVELOPMENT</b>)</blockquote>
30 <h4 class="mansect"><a name="tag_20_27_02" id="tag_20_27_02"></a>SYNOPSIS</h4>
31 <blockquote class="synopsis">
32 <div class="box"><code><tt><sup>[<a href="javascript:open_code('CD%20SD')">CD SD</a>]</sup> <img src="../images/opt-start.gif" alt=
33 "[Option Start]" border="0"> ctags</tt> <b>[</b><tt>-a</tt><b>] [</b><tt>-f</tt> <i>tagsfile</i><b>]</b> <i>pathname</i><tt>...<br>
34 <br>
35 ctags -x</tt> <i>pathname</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
36 <tt><br></tt></blockquote>
37 <h4 class="mansect"><a name="tag_20_27_03" id="tag_20_27_03"></a>DESCRIPTION</h4>
38 <blockquote>
39 <p>The <i>ctags</i> utility shall write a <i>tagsfile</i> or an index of objects from C-language source files specified by the
40 <i>pathname</i> operands. The <i>tagsfile</i> shall list the locators of C-language objects within the source files. A locator
41 consists of a name, pathname, and either a search pattern or a line number that can be used in searching for the object definition.
42 The objects that shall be recognized are specified in the EXTENDED DESCRIPTION section.</p>
43 </blockquote>
44 <h4 class="mansect"><a name="tag_20_27_04" id="tag_20_27_04"></a>OPTIONS</h4>
45 <blockquote>
46 <p>The <i>ctags</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
47 Guidelines</i></a> .</p>
48 <p>The following options shall be supported:</p>
49 <dl compact>
50 <dd></dd>
51 <dt><b>-a</b></dt>
52 <dd>Append to <i>tagsfile</i>.</dd>
53 <dt><b>-f </b><i>tagsfile</i></dt>
54 <dd>Write the object locator lists into <i>tagsfile</i> instead of the default file named <b>tags</b> in the current
55 directory.</dd>
56 <dt><b>-x</b></dt>
57 <dd>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
58 write this to the standard output. A <i>tagsfile</i> shall not be created when <b>-x</b> is specified.</dd>
59 </dl>
60 </blockquote>
61 <h4 class="mansect"><a name="tag_20_27_05" id="tag_20_27_05"></a>OPERANDS</h4>
62 <blockquote>
63 <p>The following <i>pathname</i> operands are supported:</p>
64 <dl compact>
65 <dd></dd>
66 <dt><i>file</i><b>.c</b></dt>
67 <dd>Files with basenames ending with the <b>.c</b> suffix shall be treated as C-language source code. Such files that are not valid
68 input to <a href="../utilities/c17.html"><i>c17</i></a> produce unspecified results.</dd>
69 <dt><i>file</i><b>.h</b></dt>
70 <dd>Files with basenames ending with the <b>.h</b> suffix shall be treated as C-language source code. Such files that are not valid
71 input to <a href="../utilities/c17.html"><i>c17</i></a> produce unspecified results.</dd>
72 </dl>
73 <p>The handling of other files is implementation-defined.</p>
74 </blockquote>
75 <h4 class="mansect"><a name="tag_20_27_06" id="tag_20_27_06"></a>STDIN</h4>
76 <blockquote>
77 <p>See the INPUT FILES section.</p>
78 </blockquote>
79 <h4 class="mansect"><a name="tag_20_27_07" id="tag_20_27_07"></a>INPUT FILES</h4>
80 <blockquote>
81 <p>The input files shall be text files containing C-language source code.</p>
82 </blockquote>
83 <h4 class="mansect"><a name="tag_20_27_08" id="tag_20_27_08"></a>ENVIRONMENT VARIABLES</h4>
84 <blockquote>
85 <p>The following environment variables shall affect the execution of <i>ctags</i>:</p>
86 <dl compact>
87 <dd></dd>
88 <dt><i>LANG</i></dt>
89 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
90 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
91 variables used to determine the values of locale categories.)</dd>
92 <dt><i>LC_ALL</i></dt>
93 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
94 <dt><i>LC_COLLATE</i></dt>
95 <dd><br>
96 Determine the order in which output is sorted for the <b>-x</b> option. The POSIX locale determines the order in which the
97 <i>tagsfile</i> is written.</dd>
98 <dt><i>LC_CTYPE</i></dt>
99 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
100 opposed to multi-byte characters in arguments and input files). If the locale is not compatible with the C locale described by the
101 ISO C standard, the results are unspecified.</dd>
102 <dt><i>LC_MESSAGES</i></dt>
103 <dd><br>
104 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
105 <dt><i>NLSPATH</i></dt>
106 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
107 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
108 "0"></dd>
109 </dl>
110 </blockquote>
111 <h4 class="mansect"><a name="tag_20_27_09" id="tag_20_27_09"></a>ASYNCHRONOUS EVENTS</h4>
112 <blockquote>
113 <p>Default.</p>
114 </blockquote>
115 <h4 class="mansect"><a name="tag_20_27_10" id="tag_20_27_10"></a>STDOUT</h4>
116 <blockquote>
117 <p>The list of object name information produced by the <b>-x</b> option shall be written to standard output in the following
118 format:</p>
119 <pre>
120 <tt>"%s %d %s %s", <</tt><i>object-name</i><tt>>, <</tt><i>line-number</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>text</i><tt>>
121 </tt></pre>
122 <p>where <<i>text</i>> is the text of line <<i>line-number</i>> of file <<i>filename</i>>.</p>
123 </blockquote>
124 <h4 class="mansect"><a name="tag_20_27_11" id="tag_20_27_11"></a>STDERR</h4>
125 <blockquote>
126 <p>The standard error shall be used only for diagnostic messages.</p>
127 </blockquote>
128 <h4 class="mansect"><a name="tag_20_27_12" id="tag_20_27_12"></a>OUTPUT FILES</h4>
129 <blockquote>
130 <p>When the <b>-x</b> option is not specified, the format of the output file shall be:</p>
131 <pre>
132 <tt>"%s\t%s\t/%s/\n", <</tt><i>identifier</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>pattern</i><tt>>
133 </tt></pre>
134 <p>where <<i>pattern</i>> is a search pattern that could be used by an editor to find the defining instance of
135 <<i>identifier</i>> in <<i>filename</i>> (where <i>defining instance</i> is indicated by the declarations listed in the
136 EXTENDED DESCRIPTION).</p>
137 <p>An optional <circumflex> (<tt>'^'</tt>) can be added as a prefix to <<i>pattern</i>>, and an optional
138 <dollar-sign> can be appended to <<i>pattern</i>> to indicate that the pattern is anchored to the beginning (end) of a
139 line of text. Any <slash> or <backslash> characters in <<i>pattern</i>> shall be preceded by a <backslash>
140 character. The anchoring <circumflex>, <dollar-sign>, and escaping <backslash> characters shall not be considered
141 part of the search pattern. All other characters in the search pattern shall be considered literal characters.<br></p>
142 <p>An alternative format is:</p>
143 <pre>
144 <tt>"%s\t%s\t?%s?\n", <</tt><i>identifier</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>pattern</i><tt>>
145 </tt></pre>
146 <p>which is identical to the first format except that <slash> characters in <<i>pattern</i>> shall not be preceded by
147 escaping <backslash> characters, and <question-mark> characters in <<i>pattern</i>> shall be preceded by
148 <backslash> characters.</p>
149 <p>A second alternative format is:</p>
150 <pre>
151 <tt>"%s\t%s\t%d\n", <</tt><i>identifier</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>lineno</i><tt>>
152 </tt></pre>
153 <p>where <<i>lineno</i>> is a decimal line number that could be used by an editor to find <<i>identifier</i>> in
154 <<i>filename</i>>.</p>
155 <p>Neither alternative format shall be produced by <i>ctags</i> when it is used as described by POSIX.1-2024, but the standard
156 utilities that process tags files shall be able to process those formats as well as the first format.</p>
157 <p>In any of these formats, the file shall be sorted by identifier, based on the collation sequence in the POSIX locale.</p>
158 </blockquote>
159 <h4 class="mansect"><a name="tag_20_27_13" id="tag_20_27_13"></a>EXTENDED DESCRIPTION</h4>
160 <blockquote>
161 <p>The <i>ctags</i> utility shall attempt to produce an output line for each of the following objects:</p>
162 <ul>
163 <li>
164 <p>Function definitions</p>
165 </li>
166 <li>
167 <p>Type definitions</p>
168 </li>
169 <li>
170 <p>Macros with arguments</p>
171 </li>
172 </ul>
173 <p>It may also produce output for any of the following objects:</p>
174 <ul>
175 <li>
176 <p>Function prototypes</p>
177 </li>
178 <li>
179 <p>Structures</p>
180 </li>
181 <li>
182 <p>Unions</p>
183 </li>
184 <li>
185 <p>Global variable definitions</p>
186 </li>
187 <li>
188 <p>Enumeration types</p>
189 </li>
190 <li>
191 <p>Macros without arguments</p>
192 </li>
193 <li>
194 <p><b>#define</b> statements</p>
195 </li>
196 <li>
197 <p><b>#line</b> statements</p>
198 </li>
199 </ul>
200 <p>Any <b>#if</b> and <b>#ifdef</b> statements shall produce no output. The tag <b>main</b> is treated specially in C programs. The
201 tag formed shall be created by prefixing <b>M</b> to the name of the file, with the trailing <b>.c</b>, and leading pathname
202 components (if any) removed.</p>
203 <p>It is implementation-defined what other objects (including duplicate identifiers) produce output.</p>
204 <p>On systems that do not support the C-Language Development Utilities option, if <i>ctags</i> is supported it produces unspecified
205 results for C-language source code files. It should write to standard error a message identifying this condition and cause a
206 non-zero exit status to be produced.</p>
207 </blockquote>
208 <h4 class="mansect"><a name="tag_20_27_14" id="tag_20_27_14"></a>EXIT STATUS</h4>
209 <blockquote>
210 <p>The following exit values shall be returned:</p>
211 <dl compact>
212 <dd></dd>
213 <dt> 0</dt>
214 <dd>Successful completion.</dd>
215 <dt>>0</dt>
216 <dd>An error occurred.</dd>
217 </dl>
218 </blockquote>
219 <h4 class="mansect"><a name="tag_20_27_15" id="tag_20_27_15"></a>CONSEQUENCES OF ERRORS</h4>
220 <blockquote>
221 <p>Default.</p>
222 </blockquote>
223 <hr>
224 <div class="box"><em>The following sections are informative.</em></div>
225 <h4 class="mansect"><a name="tag_20_27_16" id="tag_20_27_16"></a>APPLICATION USAGE</h4>
226 <blockquote>
227 <p>The output with <b>-x</b> is meant to be a simple index that can be written out as an off-line readable function index. If the
228 input files to <i>ctags</i> (such as <b>.c</b> files) were not created using the same locale as that in effect when <i>ctags</i>
229 <b>-x</b> is run, results might not be as expected.</p>
230 <p>The description of C-language processing says "attempts to" because the C language can be greatly confused, especially through
231 the use of <b>#define</b>s, and this utility would be of no use if the real C preprocessor were run to identify them. The output
232 from <i>ctags</i> may be fooled and incorrect for various constructs.</p>
233 </blockquote>
234 <h4 class="mansect"><a name="tag_20_27_17" id="tag_20_27_17"></a>EXAMPLES</h4>
235 <blockquote>
236 <p>None.</p>
237 </blockquote>
238 <h4 class="mansect"><a name="tag_20_27_18" id="tag_20_27_18"></a>RATIONALE</h4>
239 <blockquote>
240 <p>The option list was significantly reduced from that provided by historical implementations. The <b>-F</b> option was omitted as
241 redundant, since it is the default. The <b>-B</b> option was omitted as being of very limited usefulness. The <b>-t</b> option was
242 omitted since the recognition of <b>typedef</b>s is now required for C source files. The <b>-u</b> option was omitted because the
243 update function was judged to be not only inefficient, but also rarely needed.</p>
244 <p>An early proposal included a <b>-w</b> option to suppress warning diagnostics. Since the types of such diagnostics could not be
245 described, the option was omitted as being not useful.</p>
246 <p>The text for <i>LC_CTYPE</i> about compatibility with the C locale acknowledges that the ISO C standard imposes
247 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
248 implementation extensions, or one of a few alternative locales for systems supporting different codesets.</p>
249 <p>The collation sequence of the tags file is not affected by <i>LC_COLLATE</i> because it is typically not used by human readers,
250 but only by programs such as <a href="../utilities/vi.html"><i>vi</i></a> to locate the tag within the source files. Using the
251 POSIX locale eliminates some of the problems of coordinating locales between the <i>ctags</i> file creator and the <a href=
252 "../utilities/vi.html"><i>vi</i></a> file reader.</p>
253 <p>Historically, the tags file has been used only by <a href="../utilities/ex.html"><i>ex</i></a> and <a href=
254 "../utilities/vi.html"><i>vi</i></a>. However, the format of the tags file has been published to encourage other programs to use
255 the tags in new ways. The format allows either patterns or line numbers to find the identifiers because the historical <a href=
256 "../utilities/vi.html"><i>vi</i></a> recognizes either. The <i>ctags</i> utility does not produce the format using line numbers
257 because it is not useful following any source file changes that add or delete lines. The documented search patterns match
258 historical practice. It should be noted that literal leading <circumflex> or trailing <dollar-sign> characters in the
259 search pattern will only behave correctly if anchored to the beginning of the line or end of the line by an additional
260 <circumflex> or <dollar-sign> character.</p>
261 <p>Historical implementations also understand the objects used by the languages FORTRAN, Pascal, and sometimes LISP, and they
262 understand the C source output by <a href="../utilities/lex.html"><i>lex</i></a> and <a href=
263 "../utilities/yacc.html"><i>yacc</i></a>. The <i>ctags</i> utility is not required to accommodate these languages, although
264 implementors are encouraged to do so.</p>
265 <p>The following historical option was not specified, as <i>vgrind</i> is not included in this volume of POSIX.1-2024:</p>
266 <dl compact>
267 <dd></dd>
268 <dt><b>-v</b></dt>
269 <dd>If the <b>-v</b> flag is given, an index of the form expected by <i>vgrind</i> is produced on the standard output. This listing
270 contains the function name, filename, and page number (assuming 64-line pages). Since the output is sorted into lexicographic
271 order, it may be desired to run the output through <a href="../utilities/sort.html"><i>sort</i></a> <b>-f</b>. Sample use:
272 <pre>
273 <tt>ctags -v files | sort -f > index
274 vgrind -x index
275 </tt></pre></dd>
276 </dl>
277 <p>The special treatment of the tag <b>main</b> makes the use of <i>ctags</i> practical in directories with more than one
278 program.</p>
279 </blockquote>
280 <h4 class="mansect"><a name="tag_20_27_19" id="tag_20_27_19"></a>FUTURE DIRECTIONS</h4>
281 <blockquote>
282 <p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline>
283 character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to
284 treat this as an error. A future version of this standard may require implementations to treat this as an error.</p>
285 <p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a
286 <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require
287 implementations to treat this as an error.</p>
288 </blockquote>
289 <h4 class="mansect"><a name="tag_20_27_20" id="tag_20_27_20"></a>SEE ALSO</h4>
290 <blockquote>
291 <p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/vi.html#"><i>vi</i></a></p>
292 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
293 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
294 </blockquote>
295 <h4 class="mansect"><a name="tag_20_27_21" id="tag_20_27_21"></a>CHANGE HISTORY</h4>
296 <blockquote>
297 <p>First released in Issue 4.</p>
298 </blockquote>
299 <h4 class="mansect"><a name="tag_20_27_22" id="tag_20_27_22"></a>Issue 5</h4>
300 <blockquote>
301 <p>The FUTURE DIRECTIONS section is added.</p>
302 </blockquote>
303 <h4 class="mansect"><a name="tag_20_27_23" id="tag_20_27_23"></a>Issue 6</h4>
304 <blockquote>
305 <p>This utility is marked as part of the User Portability Utilities option.</p>
306 <p>The OUTPUT FILES section is changed to align with the IEEE P1003.2b draft standard.</p>
307 <p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
308 <p>IEEE PASC Interpretation 1003.2 #168 is applied, changing "create" to "write" in the DESCRIPTION.</p>
309 </blockquote>
310 <h4 class="mansect"><a name="tag_20_27_24" id="tag_20_27_24"></a>Issue 7</h4>
311 <blockquote>
312 <p>The <i>ctags</i> utility is no longer dependent on support for the User Portability Utilities option.</p>
313 <p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p>
314 </blockquote>
315 <h4 class="mansect"><a name="tag_20_27_25" id="tag_20_27_25"></a>Issue 8</h4>
316 <blockquote>
317 <p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p>
318 <ol type="a">
319 <li>
320 <p>Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value of a
321 <newline> character when <newline> is a terminator or separator in the output format being used.</p>
322 </li>
323 <li>
324 <p>Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> character.</p>
325 </li>
326 </ol>
327 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
328 <p>Austin Group Defect 1312 is applied, inserting a missing line break in the example commands in the RATIONALE section.</p>
329 <p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p>
330 </blockquote>
331 <div class="box"><em>End of informative text.</em></div>
332 <hr>
333 <p> </p>
334 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
335 <hr size="2" noshade>
336 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
337 POSIX™ is a Trademark of The IEEE.<br>
338 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
339 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
340 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
341 ]</font></center>
342 <hr size="2" noshade>
343 <div class="NAVHEADER">
344 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
345 <tr class="nav">
346 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/csplit.html" accesskey="P"><<<
347 Previous</a></td>
348 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
349 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cut.html" accesskey="N">Next >>></a></td>
350 </tr>
351 </table>
352 <hr align="left" width="100%"></div>
353 </body>
354 </html>