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