1 | /* quotearg.h - quote arguments for output |
2 | |
3 | Copyright (C) 1998-2002, 2004, 2006, 2008-2019 Free Software Foundation, |
4 | Inc. |
5 | |
6 | This program is free software: you can redistribute it and/or modify |
7 | it under the terms of the GNU General Public License as published by |
8 | the Free Software Foundation; either version 3 of the License, or |
9 | (at your option) any later version. |
10 | |
11 | This program is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
14 | GNU General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU General Public License |
17 | along with this program. If not, see <https://www.gnu.org/licenses/>. */ |
18 | |
19 | /* Written by Paul Eggert <eggert@twinsun.com> */ |
20 | |
21 | #ifndef QUOTEARG_H_ |
22 | # define QUOTEARG_H_ 1 |
23 | |
24 | # include <stddef.h> |
25 | |
26 | /* Basic quoting styles. For each style, an example is given on the |
27 | input strings "simple", "\0 \t\n'\"\033?""?/\\", and "a:b", using |
28 | quotearg_buffer, quotearg_mem, and quotearg_colon_mem with that |
29 | style and the default flags and quoted characters. Note that the |
30 | examples are shown here as valid C strings rather than what |
31 | displays on a terminal (with "??/" as a trigraph for "\\"). */ |
32 | enum quoting_style |
33 | { |
34 | /* Output names as-is (ls --quoting-style=literal). Can result in |
35 | embedded null bytes if QA_ELIDE_NULL_BYTES is not in |
36 | effect. |
37 | |
38 | quotearg_buffer: |
39 | "simple", "\0 \t\n'\"\033??/\\", "a:b" |
40 | quotearg: |
41 | "simple", " \t\n'\"\033??/\\", "a:b" |
42 | quotearg_colon: |
43 | "simple", " \t\n'\"\033??/\\", "a:b" |
44 | */ |
45 | literal_quoting_style, |
46 | |
47 | /* Quote names for the shell if they contain shell metacharacters |
48 | or would cause ambiguous output (ls --quoting-style=shell). |
49 | Can result in embedded null bytes if QA_ELIDE_NULL_BYTES is not |
50 | in effect. |
51 | |
52 | quotearg_buffer: |
53 | "simple", "'\0 \t\n'\\''\"\033??/\\'", "a:b" |
54 | quotearg: |
55 | "simple", "' \t\n'\\''\"\033??/\\'", "a:b" |
56 | quotearg_colon: |
57 | "simple", "' \t\n'\\''\"\033??/\\'", "'a:b'" |
58 | */ |
59 | shell_quoting_style, |
60 | |
61 | /* Quote names for the shell, even if they would normally not |
62 | require quoting (ls --quoting-style=shell-always). Can result |
63 | in embedded null bytes if QA_ELIDE_NULL_BYTES is not in effect. |
64 | Behaves like shell_quoting_style if QA_ELIDE_OUTER_QUOTES is in |
65 | effect. |
66 | |
67 | quotearg_buffer: |
68 | "'simple'", "'\0 \t\n'\\''\"\033??/\\'", "'a:b'" |
69 | quotearg: |
70 | "'simple'", "' \t\n'\\''\"\033??/\\'", "'a:b'" |
71 | quotearg_colon: |
72 | "'simple'", "' \t\n'\\''\"\033??/\\'", "'a:b'" |
73 | */ |
74 | shell_always_quoting_style, |
75 | |
76 | /* Quote names for the shell if they contain shell metacharacters |
77 | or other problematic characters (ls --quoting-style=shell-escape). |
78 | Non printable characters are quoted using the $'...' syntax, |
79 | which originated in ksh93 and is widely supported by most shells, |
80 | and proposed for inclusion in POSIX. |
81 | |
82 | quotearg_buffer: |
83 | "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\\'", "a:b" |
84 | quotearg: |
85 | "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\\'", "a:b" |
86 | quotearg_colon: |
87 | "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\\'", "'a:b'" |
88 | */ |
89 | shell_escape_quoting_style, |
90 | |
91 | /* Quote names for the shell even if they would normally not |
92 | require quoting (ls --quoting-style=shell-escape). |
93 | Non printable characters are quoted using the $'...' syntax, |
94 | which originated in ksh93 and is widely supported by most shells, |
95 | and proposed for inclusion in POSIX. Behaves like |
96 | shell_escape_quoting_style if QA_ELIDE_OUTER_QUOTES is in effect. |
97 | |
98 | quotearg_buffer: |
99 | "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\'", "a:b" |
100 | quotearg: |
101 | "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\'", "a:b" |
102 | quotearg_colon: |
103 | "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\'", "'a:b'" |
104 | */ |
105 | shell_escape_always_quoting_style, |
106 | |
107 | /* Quote names as for a C language string (ls --quoting-style=c). |
108 | Behaves like c_maybe_quoting_style if QA_ELIDE_OUTER_QUOTES is |
109 | in effect. Split into consecutive strings if |
110 | QA_SPLIT_TRIGRAPHS. |
111 | |
112 | quotearg_buffer: |
113 | "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" |
114 | quotearg: |
115 | "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" |
116 | quotearg_colon: |
117 | "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a\\:b\"" |
118 | */ |
119 | c_quoting_style, |
120 | |
121 | /* Like c_quoting_style except omit the surrounding double-quote |
122 | characters if no quoted characters are encountered. |
123 | |
124 | quotearg_buffer: |
125 | "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "a:b" |
126 | quotearg: |
127 | "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "a:b" |
128 | quotearg_colon: |
129 | "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" |
130 | */ |
131 | c_maybe_quoting_style, |
132 | |
133 | /* Like c_quoting_style except always omit the surrounding |
134 | double-quote characters and ignore QA_SPLIT_TRIGRAPHS |
135 | (ls --quoting-style=escape). |
136 | |
137 | quotearg_buffer: |
138 | "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a:b" |
139 | quotearg: |
140 | "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a:b" |
141 | quotearg_colon: |
142 | "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a\\:b" |
143 | */ |
144 | escape_quoting_style, |
145 | |
146 | /* Like clocale_quoting_style, but use single quotes in the |
147 | default C locale or if the program does not use gettext |
148 | (ls --quoting-style=locale). For UTF-8 locales, quote |
149 | characters will use Unicode. |
150 | |
151 | LC_MESSAGES=C |
152 | quotearg_buffer: |
153 | "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a:b'" |
154 | quotearg: |
155 | "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a:b'" |
156 | quotearg_colon: |
157 | "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a\\:b'" |
158 | |
159 | LC_MESSAGES=pt_PT.utf8 |
160 | quotearg_buffer: |
161 | "\302\253simple\302\273", |
162 | "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" |
163 | quotearg: |
164 | "\302\253simple\302\273", |
165 | "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" |
166 | quotearg_colon: |
167 | "\302\253simple\302\273", |
168 | "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a\\:b\302\273" |
169 | */ |
170 | locale_quoting_style, |
171 | |
172 | /* Like c_quoting_style except use quotation marks appropriate for |
173 | the locale and ignore QA_SPLIT_TRIGRAPHS |
174 | (ls --quoting-style=clocale). |
175 | |
176 | LC_MESSAGES=C |
177 | quotearg_buffer: |
178 | "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" |
179 | quotearg: |
180 | "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" |
181 | quotearg_colon: |
182 | "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a\\:b\"" |
183 | |
184 | LC_MESSAGES=pt_PT.utf8 |
185 | quotearg_buffer: |
186 | "\302\253simple\302\273", |
187 | "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" |
188 | quotearg: |
189 | "\302\253simple\302\273", |
190 | "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" |
191 | quotearg_colon: |
192 | "\302\253simple\302\273", |
193 | "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a\\:b\302\273" |
194 | */ |
195 | clocale_quoting_style, |
196 | |
197 | /* Like clocale_quoting_style except use the custom quotation marks |
198 | set by set_custom_quoting. If custom quotation marks are not |
199 | set, the behavior is undefined. |
200 | |
201 | left_quote = right_quote = "'" |
202 | quotearg_buffer: |
203 | "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a:b'" |
204 | quotearg: |
205 | "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a:b'" |
206 | quotearg_colon: |
207 | "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a\\:b'" |
208 | |
209 | left_quote = "(" and right_quote = ")" |
210 | quotearg_buffer: |
211 | "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a:b)" |
212 | quotearg: |
213 | "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a:b)" |
214 | quotearg_colon: |
215 | "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a\\:b)" |
216 | |
217 | left_quote = ":" and right_quote = " " |
218 | quotearg_buffer: |
219 | ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a:b " |
220 | quotearg: |
221 | ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a:b " |
222 | quotearg_colon: |
223 | ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a\\:b " |
224 | |
225 | left_quote = "\"'" and right_quote = "'\"" |
226 | Notice that this is treated as a single level of quotes or two |
227 | levels where the outer quote need not be escaped within the inner |
228 | quotes. For two levels where the outer quote must be escaped |
229 | within the inner quotes, you must use separate quotearg |
230 | invocations. |
231 | quotearg_buffer: |
232 | "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a:b'\"" |
233 | quotearg: |
234 | "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a:b'\"" |
235 | quotearg_colon: |
236 | "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a\\:b'\"" |
237 | */ |
238 | custom_quoting_style |
239 | }; |
240 | |
241 | /* Flags for use in set_quoting_flags. */ |
242 | enum quoting_flags |
243 | { |
244 | /* Always elide null bytes from styles that do not quote them, |
245 | even when the length of the result is available to the |
246 | caller. */ |
247 | QA_ELIDE_NULL_BYTES = 0x01, |
248 | |
249 | /* Omit the surrounding quote characters if no escaped characters |
250 | are encountered. Note that if no other character needs |
251 | escaping, then neither does the escape character. */ |
252 | QA_ELIDE_OUTER_QUOTES = 0x02, |
253 | |
254 | /* In the c_quoting_style and c_maybe_quoting_style, split ANSI |
255 | trigraph sequences into concatenated strings (for example, |
256 | "?""?/" rather than "??/", which could be confused with |
257 | "\\"). */ |
258 | QA_SPLIT_TRIGRAPHS = 0x04 |
259 | }; |
260 | |
261 | /* For now, --quoting-style=literal is the default, but this may change. */ |
262 | # ifndef DEFAULT_QUOTING_STYLE |
263 | # define DEFAULT_QUOTING_STYLE literal_quoting_style |
264 | # endif |
265 | |
266 | /* Names of quoting styles and their corresponding values. */ |
267 | extern char const *const quoting_style_args[]; |
268 | extern enum quoting_style const quoting_style_vals[]; |
269 | |
270 | struct quoting_options; |
271 | |
272 | /* The functions listed below set and use a hidden variable |
273 | that contains the default quoting style options. */ |
274 | |
275 | /* Allocate a new set of quoting options, with contents initially identical |
276 | to O if O is not null, or to the default if O is null. |
277 | It is the caller's responsibility to free the result. */ |
278 | struct quoting_options *clone_quoting_options (struct quoting_options *o); |
279 | |
280 | /* Get the value of O's quoting style. If O is null, use the default. */ |
281 | enum quoting_style get_quoting_style (struct quoting_options const *o); |
282 | |
283 | /* In O (or in the default if O is null), |
284 | set the value of the quoting style to S. */ |
285 | void set_quoting_style (struct quoting_options *o, enum quoting_style s); |
286 | |
287 | /* In O (or in the default if O is null), |
288 | set the value of the quoting options for character C to I. |
289 | Return the old value. Currently, the only values defined for I are |
290 | 0 (the default) and 1 (which means to quote the character even if |
291 | it would not otherwise be quoted). C must never be a digit or a |
292 | letter that has special meaning after a backslash (for example, "\t" |
293 | for tab). */ |
294 | int set_char_quoting (struct quoting_options *o, char c, int i); |
295 | |
296 | /* In O (or in the default if O is null), |
297 | set the value of the quoting options flag to I, which can be a |
298 | bitwise combination of enum quoting_flags, or 0 for default |
299 | behavior. Return the old value. */ |
300 | int set_quoting_flags (struct quoting_options *o, int i); |
301 | |
302 | /* In O (or in the default if O is null), |
303 | set the value of the quoting style to custom_quoting_style, |
304 | set the left quote to LEFT_QUOTE, and set the right quote to |
305 | RIGHT_QUOTE. Each of LEFT_QUOTE and RIGHT_QUOTE must be |
306 | null-terminated and can be the empty string. Because backslashes are |
307 | used for escaping, it does not make sense for RIGHT_QUOTE to contain |
308 | a backslash. RIGHT_QUOTE must not begin with a digit or a letter |
309 | that has special meaning after a backslash (for example, "\t" for |
310 | tab). */ |
311 | void set_custom_quoting (struct quoting_options *o, |
312 | char const *left_quote, |
313 | char const *right_quote); |
314 | |
315 | /* Place into buffer BUFFER (of size BUFFERSIZE) a quoted version of |
316 | argument ARG (of size ARGSIZE), using O to control quoting. |
317 | If O is null, use the default. |
318 | Terminate the output with a null character, and return the written |
319 | size of the output, not counting the terminating null. |
320 | If BUFFERSIZE is too small to store the output string, return the |
321 | value that would have been returned had BUFFERSIZE been large enough. |
322 | If ARGSIZE is -1, use the string length of the argument for ARGSIZE. |
323 | On output, BUFFER might contain embedded null bytes if ARGSIZE was |
324 | not -1, the style of O does not use backslash escapes, and the |
325 | flags of O do not request elision of null bytes.*/ |
326 | size_t quotearg_buffer (char *buffer, size_t buffersize, |
327 | char const *arg, size_t argsize, |
328 | struct quoting_options const *o); |
329 | |
330 | /* Like quotearg_buffer, except return the result in a newly allocated |
331 | buffer. It is the caller's responsibility to free the result. The |
332 | result will not contain embedded null bytes. */ |
333 | char *quotearg_alloc (char const *arg, size_t argsize, |
334 | struct quoting_options const *o); |
335 | |
336 | /* Like quotearg_alloc, except that the length of the result, |
337 | excluding the terminating null byte, is stored into SIZE if it is |
338 | non-NULL. The result might contain embedded null bytes if ARGSIZE |
339 | was not -1, SIZE was not NULL, the style of O does not use |
340 | backslash escapes, and the flags of O do not request elision of |
341 | null bytes.*/ |
342 | char *quotearg_alloc_mem (char const *arg, size_t argsize, |
343 | size_t *size, struct quoting_options const *o); |
344 | |
345 | /* Use storage slot N to return a quoted version of the string ARG. |
346 | Use the default quoting options. |
347 | The returned value points to static storage that can be |
348 | reused by the next call to this function with the same value of N. |
349 | N must be nonnegative. The output of all functions in the |
350 | quotearg_n family are guaranteed to not contain embedded null |
351 | bytes.*/ |
352 | char *quotearg_n (int n, char const *arg); |
353 | |
354 | /* Equivalent to quotearg_n (0, ARG). */ |
355 | char *quotearg (char const *arg); |
356 | |
357 | /* Use storage slot N to return a quoted version of the argument ARG |
358 | of size ARGSIZE. This is like quotearg_n (N, ARG), except it can |
359 | quote null bytes. */ |
360 | char *quotearg_n_mem (int n, char const *arg, size_t argsize); |
361 | |
362 | /* Equivalent to quotearg_n_mem (0, ARG, ARGSIZE). */ |
363 | char *quotearg_mem (char const *arg, size_t argsize); |
364 | |
365 | /* Use style S and storage slot N to return a quoted version of the string ARG. |
366 | This is like quotearg_n (N, ARG), except that it uses S with no other |
367 | options to specify the quoting method. */ |
368 | char *quotearg_n_style (int n, enum quoting_style s, char const *arg); |
369 | |
370 | /* Use style S and storage slot N to return a quoted version of the |
371 | argument ARG of size ARGSIZE. This is like quotearg_n_style |
372 | (N, S, ARG), except it can quote null bytes. */ |
373 | char *quotearg_n_style_mem (int n, enum quoting_style s, |
374 | char const *arg, size_t argsize); |
375 | |
376 | /* Equivalent to quotearg_n_style (0, S, ARG). */ |
377 | char *quotearg_style (enum quoting_style s, char const *arg); |
378 | |
379 | /* Equivalent to quotearg_n_style_mem (0, S, ARG, ARGSIZE). */ |
380 | char *quotearg_style_mem (enum quoting_style s, |
381 | char const *arg, size_t argsize); |
382 | |
383 | /* Like quotearg (ARG), except also quote any instances of CH. |
384 | See set_char_quoting for a description of acceptable CH values. */ |
385 | char *quotearg_char (char const *arg, char ch); |
386 | |
387 | /* Like quotearg_char (ARG, CH), except it can quote null bytes. */ |
388 | char *quotearg_char_mem (char const *arg, size_t argsize, char ch); |
389 | |
390 | /* Equivalent to quotearg_char (ARG, ':'). */ |
391 | char *quotearg_colon (char const *arg); |
392 | |
393 | /* Like quotearg_colon (ARG), except it can quote null bytes. */ |
394 | char *quotearg_colon_mem (char const *arg, size_t argsize); |
395 | |
396 | /* Like quotearg_n_style, except with ':' quoting enabled. */ |
397 | char *quotearg_n_style_colon (int n, enum quoting_style s, char const *arg); |
398 | |
399 | /* Like quotearg_n_style (N, S, ARG) but with S as custom_quoting_style |
400 | with left quote as LEFT_QUOTE and right quote as RIGHT_QUOTE. See |
401 | set_custom_quoting for a description of acceptable LEFT_QUOTE and |
402 | RIGHT_QUOTE values. */ |
403 | char *quotearg_n_custom (int n, char const *left_quote, |
404 | char const *right_quote, char const *arg); |
405 | |
406 | /* Like quotearg_n_custom (N, LEFT_QUOTE, RIGHT_QUOTE, ARG) except it |
407 | can quote null bytes. */ |
408 | char *quotearg_n_custom_mem (int n, char const *left_quote, |
409 | char const *right_quote, |
410 | char const *arg, size_t argsize); |
411 | |
412 | /* Equivalent to quotearg_n_custom (0, LEFT_QUOTE, RIGHT_QUOTE, ARG). */ |
413 | char *quotearg_custom (char const *left_quote, char const *right_quote, |
414 | char const *arg); |
415 | |
416 | /* Equivalent to quotearg_n_custom_mem (0, LEFT_QUOTE, RIGHT_QUOTE, ARG, |
417 | ARGSIZE). */ |
418 | char *quotearg_custom_mem (char const *left_quote, |
419 | char const *right_quote, |
420 | char const *arg, size_t argsize); |
421 | |
422 | /* Free any dynamically allocated memory. */ |
423 | void quotearg_free (void); |
424 | |
425 | #endif /* !QUOTEARG_H_ */ |
426 | |