Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
xgettext.html (19845B)
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>xgettext</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/xargs.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/yacc.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="xgettext" id="xgettext"></a> <a name="tag_20_153" id="tag_20_153"></a><!-- xgettext -->
28 <h4 class="mansect"><a name="tag_20_153_01" id="tag_20_153_01"></a>NAME</h4>
29 <blockquote>xgettext — extract <i>gettext</i> call strings from C-language source files (DEVELOPMENT)</blockquote>
30 <h4 class="mansect"><a name="tag_20_153_02" id="tag_20_153_02"></a>SYNOPSIS</h4>
31 <blockquote class="synopsis">
32 <div class="box"><code><tt><sup>[<a href="javascript:open_code('CD')">CD</a>]</sup> <img src="../images/opt-start.gif" alt=
33 "[Option Start]" border="0"> xgettext</tt> <b>[</b><tt>-j</tt><b>] [</b><tt>-n</tt><b>] [</b><tt>-d</tt> <i>default-domain</i><b>]
34 [</b><tt>-K</tt> <i>keyword-spec</i><b>]</b><tt>...<br>
35 </tt> <b>[</b><tt>-p</tt> <i>pathname</i><b>]</b> <i>file</i><tt>...<br>
36 <br>
37 xgettext -a</tt> <b>[</b><tt>-n</tt><b>] [</b><tt>-d</tt> <i>default-domain</i><b>] [</b><tt>-p</tt> <i>pathname</i><b>]<br></b>
38 <tt> </tt> <b>[</b><tt>-x</tt> <i>exclude-file</i><b>]</b> <i>file</i><tt>... <img src=
39 "../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
40 <tt><br></tt></blockquote>
41 <h4 class="mansect"><a name="tag_20_153_03" id="tag_20_153_03"></a>DESCRIPTION</h4>
42 <blockquote>
43 <p>The <i>xgettext</i> utility shall automate the creation of portable messages object source files (dot-po files). A dot-po file
44 shall contain copies of string literals that are found in C-language source code in files specified by <i>file</i> operands. The
45 dot-po file can be used as input to the <a href="../utilities/msgfmt.html"><i>msgfmt</i></a> utility, to produce a messages object
46 file that can be used by applications.</p>
47 <p>The <i>xgettext</i> utility shall write <i>msgid</i> argument strings that are passed as string literals in <a href=
48 "../functions/gettext.html"><i>gettext</i>()</a>, <a href="../functions/gettext_l.html"><i>gettext_l</i>()</a>, <a href=
49 "../functions/ngettext.html"><i>ngettext</i>()</a>, and <a href="../functions/ngettext_l.html"><i>ngettext_l</i>()</a> calls in
50 C-language source code to the default output file; this file shall be named <b>messages.po</b> unless it is changed by the
51 <b>-d</b> option. The <i>xgettext</i> utility shall also write <i>msgid</i> argument strings that are passed as string literals in
52 <a href="../functions/dcgettext.html"><i>dcgettext</i>()</a>, <a href="../functions/dcgettext_l.html"><i>dcgettext_l</i>()</a>,
53 <a href="../functions/dcngettext.html"><i>dcngettext</i>()</a>, <a href="../functions/dcngettext_l.html"><i>dcngettext_l</i>()</a>,
54 <a href="../functions/dgettext.html"><i>dgettext</i>()</a>, <a href="../functions/dgettext_l.html"><i>dgettext_l</i>()</a>,
55 <a href="../functions/dngettext.html"><i>dngettext</i>()</a>, and <a href="../functions/dngettext_l.html"><i>dngettext_l</i>()</a>
56 calls either to the default output file or to the output file <i>domainname</i><b>.po</b> where <i>domainname</i> is the first
57 parameter to the call; it is implementation-defined which of those output files is used. A <b>msgid</b> directive shall precede
58 each <i>msgid</i> argument string. For the functions that have a <i>msgid_plural</i> argument, a <b>msgid_plural</b> directive
59 followed by that argument string shall also be written directly after the corresponding <b>msgid</b> directive. A <b>msgstr</b>
60 directive or <b>msgstr[</b><i>index</i><b>]</b> directives with an empty string shall be written after the corresponding
61 <b>msgid</b> or <b>msgid_plural</b> directive, respectively. The function names that <i>xgettext</i> searches for can be changed
62 using the <b>-K</b> option.</p>
63 <p>The first directive in each created dot-po file shall be a <b>domain</b> directive giving the associated domain name, except
64 that this directive is optional in the default output file.</p>
65 <p>If the <b>-p</b> <i>pathname</i> option is specified, <i>xgettext</i> shall create the dot-po files in the <i>pathname</i>
66 directory. Otherwise, the dot-po files shall be created in the current working directory.</p>
67 <p>The <b>msgid</b> values shall be in the same order that the strings are extracted from each <i>file</i> and subsections with
68 duplicate <b>msgid</b> values shall be written to the dot-po files as comment lines.</p>
69 </blockquote>
70 <h4 class="mansect"><a name="tag_20_153_04" id="tag_20_153_04"></a>OPTIONS</h4>
71 <blockquote>
72 <p>The <i>xgettext</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
73 Guidelines</i></a> .</p>
74 <p>The following options shall be supported:</p>
75 <dl compact>
76 <dd></dd>
77 <dt><b>-a</b></dt>
78 <dd>Extract all strings, not just those found in calls to <i>gettext</i> family functions. Only one dot-po file shall be
79 created.</dd>
80 <dt><b>-d </b><i>default-domain</i></dt>
81 <dd><br>
82 Name the default output file <i>default-domain</i><b>.po</b> instead of <b>messages.po</b>.</dd>
83 <dt><b>-j</b></dt>
84 <dd>Join messages from C-language source files with existing dot-po files. For each dot-po file that <i>xgettext</i> writes
85 messages to, if the file does not exist, it shall be created. New messages shall be appended but any subsections with duplicate
86 <b>msgid</b> values except the first (including <b>msgid</b> values found in an existing dot-po file) shall either be commented out
87 or omitted in the resulting dot-po file; if omitted, a warning message may be written to standard error. Domain directives in the
88 existing dot-po files shall be ignored; the assumption is that all previous <b>msgid</b> values belong to the same domain. The
89 behavior is unspecified if an existing dot-po file was not created by <i>xgettext</i> or has been modified by another
90 application.</dd>
91 <dt><b>-K </b><i>keyword-spec</i></dt>
92 <dd><br>
93 Specify an additional keyword to be looked for:
94 <ul>
95 <li>
96 <p>If <i>keyword-spec</i> is an empty string, this shall disable the use of default keywords for the <i>gettext</i> family of
97 functions.</p>
98 </li>
99 <li>
100 <p>If <i>keyword-spec</i> is a C identifier, <i>xgettext</i> shall look for strings in the first argument of each call to the
101 function or macro <i>keyword-spec</i>.</p>
102 </li>
103 <li>
104 <p>If <i>keyword-spec</i> is of the form <i>id</i>:<i>argnum</i> then <i>xgettext</i> shall treat the <i>argnum</i>-th argument of
105 a call to the function or macro <i>id</i> as the <i>msgid</i> argument, where <i>argnum</i> 1 is the first argument.</p>
106 </li>
107 <li>
108 <p>If <i>keyword-spec</i> is of the form <i>id</i>:<i>argnum1</i>,<i>argnum2</i> then <i>xgettext</i> shall treat strings in the
109 <i>argnum1</i>-th argument and in the <i>argnum2</i>-th argument of a call to the function or macro <i>id</i> as the <i>msgid</i>
110 and <i>msgid_plural</i> arguments, respectively.</p>
111 </li>
112 </ul>
113 <p>For all mentioned forms, the application shall ensure that if <i>argnum2</i> is given, it is not equal to <i>argnum1</i>. All
114 numeric values shall be converted as specified in item 6 in XBD <a href="../basedefs/V1_chap12.html#tag_12_01"><i>12.1 Utility
115 Argument Syntax</i></a> .</p>
116 </dd>
117 <dt><b>-n</b></dt>
118 <dd>Add comment lines to the output file indicating pathnames and line numbers in the source files where each extracted string is
119 encountered. These lines shall appear before each <b>msgid</b> directive. Such comments should have the format:
120 <pre>
121 <tt>#: </tt><i>pathname1</i><tt>:</tt><i>linenumber1 </i><b>[</b><i>pathname2</i><tt>:</tt><i>linenumber2</i><tt>...</tt><b>]</b><tt>
122 </tt></pre></dd>
123 <dt><b>-p </b><i>pathname</i></dt>
124 <dd><br>
125 Create output files in the directory specified by <i>pathname</i> instead of in the current working directory.</dd>
126 <dt><b>-x </b><i>exclude-file</i></dt>
127 <dd><br>
128 Specify a file containing strings that shall not be extracted from the input files. The format of <i>exclude-file</i> is identical
129 to that of a dot-po file. However, only statements containing <b>msgid</b> directives in <i>exclude-file</i> shall be used. All
130 other statements shall be ignored.</dd>
131 </dl>
132 </blockquote>
133 <h4 class="mansect"><a name="tag_20_153_05" id="tag_20_153_05"></a>OPERANDS</h4>
134 <blockquote>
135 <p>The following operand shall be supported:</p>
136 <dl compact>
137 <dd></dd>
138 <dt><i>file</i></dt>
139 <dd>A pathname of an input file containing C-language source code. If <tt>'-'</tt> is specified for an instance of <i>file</i>, the
140 standard input shall be used.</dd>
141 </dl>
142 </blockquote>
143 <h4 class="mansect"><a name="tag_20_153_06" id="tag_20_153_06"></a>STDIN</h4>
144 <blockquote>
145 <p>The standard input shall not be used unless a <i>file</i> operand is specified as <tt>'-'</tt>.</p>
146 </blockquote>
147 <h4 class="mansect"><a name="tag_20_153_07" id="tag_20_153_07"></a>INPUT FILES</h4>
148 <blockquote>
149 <p>The input files specified as <i>file</i> operands shall be C-language source files. The input file specified as the
150 option-argument for the <b>-x</b> option shall be a dot-po file in the format specified as input for the <a href=
151 "../utilities/msgfmt.html"><i>msgfmt</i></a> utility.</p>
152 </blockquote>
153 <h4 class="mansect"><a name="tag_20_153_08" id="tag_20_153_08"></a>ENVIRONMENT VARIABLES</h4>
154 <blockquote>
155 <p>The following environment variables shall affect the execution of <i>xgettext</i>:</p>
156 <dl compact>
157 <dd></dd>
158 <dt><i>LANG</i></dt>
159 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
160 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
161 variables used to determine the values of locale categories.)</dd>
162 <dt><i>LANGUAGE</i></dt>
163 <dd>Determine the location of messages objects <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
164 "../images/opt-start.gif" alt="[Option Start]" border="0"> if <i>NLSPATH</i> is not set or the evaluation of <i>NLSPATH</i>
165 did not lead to a suitable messages object being found. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
166 <dt><i>LC_ALL</i></dt>
167 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
168 <dt><i>LC_CTYPE</i></dt>
169 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
170 opposed to multi-byte characters in arguments and input files).</dd>
171 <dt><i>LC_MESSAGES</i></dt>
172 <dd><br>
173 Determine the locale name used to locate messages objects, and the locale that should be used to affect the format and contents of
174 diagnostic messages written to standard error.</dd>
175 <dt><i>NLSPATH</i></dt>
176 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
177 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
178 "0"></dd>
179 </dl>
180 </blockquote>
181 <h4 class="mansect"><a name="tag_20_153_09" id="tag_20_153_09"></a>ASYNCHRONOUS EVENTS</h4>
182 <blockquote>
183 <p>Default.</p>
184 </blockquote>
185 <h4 class="mansect"><a name="tag_20_153_10" id="tag_20_153_10"></a>STDOUT</h4>
186 <blockquote>
187 <p>The standard output shall not be used.</p>
188 </blockquote>
189 <h4 class="mansect"><a name="tag_20_153_11" id="tag_20_153_11"></a>STDERR</h4>
190 <blockquote>
191 <p>The standard error shall be used for diagnostic messages and may be used for warning messages.</p>
192 </blockquote>
193 <h4 class="mansect"><a name="tag_20_153_12" id="tag_20_153_12"></a>OUTPUT FILES</h4>
194 <blockquote>
195 <p>The output files shall be dot-po files in the format specified as input for the <a href=
196 "../utilities/msgfmt.html"><i>msgfmt</i></a> utility. It is unspecified whether each output file includes a header (<b>msgid</b>
197 <tt>""</tt>) before the content derived from the input C-language source files.</p>
198 </blockquote>
199 <h4 class="mansect"><a name="tag_20_153_13" id="tag_20_153_13"></a>EXTENDED DESCRIPTION</h4>
200 <blockquote>
201 <p>None.</p>
202 </blockquote>
203 <h4 class="mansect"><a name="tag_20_153_14" id="tag_20_153_14"></a>EXIT STATUS</h4>
204 <blockquote>
205 <p>The following exit values shall be returned:</p>
206 <dl compact>
207 <dd></dd>
208 <dt> 0</dt>
209 <dd>Successful completion.</dd>
210 <dt>>0</dt>
211 <dd>An error occurred.</dd>
212 </dl>
213 </blockquote>
214 <h4 class="mansect"><a name="tag_20_153_15" id="tag_20_153_15"></a>CONSEQUENCES OF ERRORS</h4>
215 <blockquote>
216 <p>Default.</p>
217 </blockquote>
218 <hr>
219 <div class="box"><em>The following sections are informative.</em></div>
220 <h4 class="mansect"><a name="tag_20_153_16" id="tag_20_153_16"></a>APPLICATION USAGE</h4>
221 <blockquote>
222 <p>Implementations differ as to whether they write all output to the default output file or split the output into separate
223 per-domain files. Portable applications can either ensure that each C-language source file contains calls to <i>gettext</i> family
224 functions for only a single domain, or force all output to be to the default output file by using the <b>-K</b> option to override
225 the default keywords.</p>
226 <p>Some implementations of <i>xgettext</i> are not able to extract cast strings (unless <b>-a</b> is used), for example casts of
227 literal strings to <b>(const char *)</b>. Use of a cast is unnecessary anyway, since the prototypes in <a href=
228 "../basedefs/libintl.h.html"><i><libintl.h></i></a> already specify this type.</p>
229 <p>The <i>xgettext</i> utility is not required to handle C preprocessor directives. Therefore if, for example, calls to
230 <i>gettext</i> family functions are wrapped by macros, they might not be found unless the <b>-K</b> option is used to tell
231 <i>xgettext</i> to look for the macro calls.</p>
232 </blockquote>
233 <h4 class="mansect"><a name="tag_20_153_17" id="tag_20_153_17"></a>EXAMPLES</h4>
234 <blockquote>
235 <p><b>Example 1</b></p>
236 <p>The following example shows how <b>-K</b> can be used to force all output to be to the default output file:</p>
237 <pre>
238 <tt>xgettext -K "" -K gettext:1 -K dgettext:2 -K dcgettext:2 \
239 -K ngettext:1,2 -K dngettext:2,3 -K dcngettext:2,3 source.c
240 </tt></pre>
241 <p>By overriding the default keywords using the <b>-K</b> option as above, the <i>xgettext</i> utility is directed to ignore the
242 <i>domainname</i> arguments to the <a href="../functions/dgettext.html"><i>dgettext</i>()</a>, <a href=
243 "../functions/dcgettext.html"><i>dcgettext</i>()</a>, <a href="../functions/dngettext.html"><i>dngettext</i>()</a>, and <a href=
244 "../functions/dcngettext.html"><i>dcngettext</i>()</a> functions. Thus, the utility treats the functions as their respective
245 equivalent without the <i>d</i> prefix, ignoring the <i>domainname</i> argument and writing generated output to the default output
246 file, <b>messages.po</b>. Additional <b>-K</b> options would be needed for the variants of the functions with an <i>_l</i> suffix
247 if they are used.</p>
248 <p><b>Example 2</b></p>
249 <p>If the source uses a macro definition such as:</p>
250 <pre>
251 <tt>#define i18n gettext
252 </tt></pre>
253 <p>the use of:</p>
254 <pre>
255 <tt>xgettext -K i18n:1 source.c
256 </tt></pre>
257 <p>will pick up <b>msgid</b> values from a line such as:</p>
258 <pre>
259 <tt>fprintf(stdout, i18n("The value is %s"), value1);
260 </tt></pre></blockquote>
261 <h4 class="mansect"><a name="tag_20_153_18" id="tag_20_153_18"></a>RATIONALE</h4>
262 <blockquote>
263 <p>The <b>-K</b> option is based on the <b>-k</b> option of GNU <i>xgettext</i>; the only difference is that GNU's <b>-k</b> takes
264 an optional option-argument whereas <b>-K</b> in this standard has a mandatory option-argument in order to comply with the syntax
265 guidelines.</p>
266 <p>The standard developers considered including functionality equivalent to the <b>-c</b>, <b>-m</b>, and <b>-M</b> options in
267 existing implementations. However, those letters could not be used as the syntax differed between implementations. The usual
268 solution of adding an uppercase equivalent of lowercase options with the standard syntax instead was not possible, for obvious
269 reasons for <b>-m</b> and <b>-M</b>, and as <b>-C</b> was already in use for another purpose in one implementation.</p>
270 <p>The <b>-s</b> option is not included as it has been deprecated in at least one implementation because it has been found to
271 deprive translators of valuable context.</p>
272 </blockquote>
273 <h4 class="mansect"><a name="tag_20_153_19" id="tag_20_153_19"></a>FUTURE DIRECTIONS</h4>
274 <blockquote>
275 <p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a
276 <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require
277 implementations to treat this as an error.</p>
278 <p>A future version of this standard may change the description of the <b>-n</b> option to mandate the given comment format (by
279 using "shall" instead of "should").</p>
280 </blockquote>
281 <h4 class="mansect"><a name="tag_20_153_20" id="tag_20_153_20"></a>SEE ALSO</h4>
282 <blockquote>
283 <p><a href="../utilities/gettext.html#tag_20_54"><i>gettext</i></a> , <a href="../utilities/msgfmt.html#"><i>msgfmt</i></a></p>
284 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
285 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
286 <p>XSH <a href="../functions/gettext.html#tag_17_238"><i>gettext</i></a></p>
287 </blockquote>
288 <h4 class="mansect"><a name="tag_20_153_21" id="tag_20_153_21"></a>CHANGE HISTORY</h4>
289 <blockquote>
290 <p>First released in Issue 8.</p>
291 </blockquote>
292 <div class="box"><em>End of informative text.</em></div>
293 <hr>
294 <p> </p>
295 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
296 <hr size="2" noshade>
297 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
298 POSIX™ is a Trademark of The IEEE.<br>
299 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
300 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
301 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
302 ]</font></center>
303 <hr size="2" noshade>
304 <div class="NAVHEADER">
305 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
306 <tr class="nav">
307 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xargs.html" accesskey="P"><<<
308 Previous</a></td>
309 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
310 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/yacc.html" accesskey="N">Next >>></a></td>
311 </tr>
312 </table>
313 <hr align="left" width="100%"></div>
314 </body>
315 </html>