git.gag.com Git - debian/tar/blob - gnu/quotearg.h

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