dhcpd-pools  2.28
ISC dhcpd lease usage analyser
quotearg.h
Go to the documentation of this file.
1 /* quotearg.h - quote arguments for output
2 
3  Copyright (C) 1998-2002, 2004, 2006, 2008-2015 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 <http://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 "\\"). */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
239  };
240 
241 /* Flags for use in set_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. */
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. */
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  "\\"). */
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. */
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_ */
void set_quoting_style(struct quoting_options *o, enum quoting_style s)
Definition: quotearg.c:131
Definition: quotearg.c:55
char * quotearg_char(char const *arg, char ch)
Definition: quotearg.c:940
char * quotearg_n_style_colon(int n, enum quoting_style s, char const *arg)
Definition: quotearg.c:958
char const *const quoting_style_args[]
Definition: quotearg.c:75
Definition: quotearg.h:247
char * quotearg_n_mem(int n, char const *arg, size_t argsize)
Definition: quotearg.c:886
Definition: quotearg.h:170
Definition: quotearg.h:59
int set_char_quoting(struct quoting_options *o, char c, int i)
Definition: quotearg.c:142
char const * left_quote
Definition: quotearg.c:68
void quotearg_free(void)
Definition: quotearg.c:791
Definition: quotearg.h:105
char * quotearg_n_style(int n, enum quoting_style s, char const *arg)
Definition: quotearg.c:904
Definition: quotearg.h:252
int set_quoting_flags(struct quoting_options *o, int i)
Definition: quotearg.c:158
Definition: quotearg.h:258
struct quoting_options * clone_quoting_options(struct quoting_options *o)
Definition: quotearg.c:112
void set_custom_quoting(struct quoting_options *o, char const *left_quote, char const *right_quote)
Definition: quotearg.c:169
char * quotearg_style_mem(enum quoting_style s, char const *arg, size_t argsize)
Definition: quotearg.c:925
char * quotearg_mem(char const *arg, size_t argsize)
Definition: quotearg.c:898
char * quotearg_style(enum quoting_style s, char const *arg)
Definition: quotearg.c:919
Definition: quotearg.h:74
Definition: quotearg.h:119
char * quotearg_alloc(char const *arg, size_t argsize, struct quoting_options const *o)
Definition: quotearg.c:742
char const * right_quote
Definition: quotearg.c:71
char * quotearg_n_style_mem(int n, enum quoting_style s, char const *arg, size_t argsize)
Definition: quotearg.c:911
Definition: quotearg.h:45
char * quotearg_custom_mem(char const *left_quote, char const *right_quote, char const *arg, size_t argsize)
Definition: quotearg.c:992
quoting_style
Definition: quotearg.h:32
char * quotearg(char const *arg)
Definition: quotearg.c:892
Definition: quotearg.h:238
quoting_flags
Definition: quotearg.h:242
Definition: quotearg.h:144
char * quotearg_n(int n, char const *arg)
Definition: quotearg.c:880
char * quotearg_colon_mem(char const *arg, size_t argsize)
Definition: quotearg.c:952
Definition: quotearg.h:195
char * quotearg_n_custom_mem(int n, char const *left_quote, char const *right_quote, char const *arg, size_t argsize)
Definition: quotearg.c:975
char * quotearg_char_mem(char const *arg, size_t argsize, char ch)
Definition: quotearg.c:931
enum quoting_style get_quoting_style(struct quoting_options const *o)
Definition: quotearg.c:123
size_t quotearg_buffer(char *buffer, size_t buffersize, char const *arg, size_t argsize, struct quoting_options const *o)
Definition: quotearg.c:727
Definition: quotearg.h:89
char * quotearg_custom(char const *left_quote, char const *right_quote, char const *arg)
Definition: quotearg.c:985
char * quotearg_alloc_mem(char const *arg, size_t argsize, size_t *size, struct quoting_options const *o)
Definition: quotearg.c:755
Definition: quotearg.h:131
char * quotearg_n_custom(int n, char const *left_quote, char const *right_quote, char const *arg)
Definition: quotearg.c:967
enum quoting_style const quoting_style_vals[]
Definition: quotearg.c:91
char * quotearg_colon(char const *arg)
Definition: quotearg.c:946