glib/gshell.c

   1 /* gshell.c - Shell-related utilities
   2  *
   3  *  Copyright 2000 Red Hat, Inc.
   4  *  g_execvpe implementation based on GNU libc execvp:
   5  *   Copyright 1991, 92, 95, 96, 97, 98, 99 Free Software Foundation, Inc.
   6  *
   7  * GLib is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * GLib is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with GLib; see the file COPYING.LIB.  If not, write
  19  * to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include "config.h"
  24
  25 #include <string.h>
  26
  27 #include "gshell.h"
  28
  29 #include "gslist.h"
  30 #include "gstrfuncs.h"
  31 #include "gstring.h"
  32 #include "gtestutils.h"
  33 #include "glibintl.h"
  34
  35 /**
  36  * SECTION:shell
  37  * @title: Shell-related Utilities
  38  * @short_description: shell-like commandline handling
  39  **/
  40
  41 /**
  42  * G_SHELL_ERROR:
  43  *
  44  * Error domain for shell functions. Errors in this domain will be from
  45  * the #GShellError enumeration. See #GError for information on error
  46  * domains.
  47  **/
  48
  49 /**
  50  * GShellError:
  51  * @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting.
  52  * @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty.
  53  * @G_SHELL_ERROR_FAILED: Some other error.
  54  *
  55  * Error codes returned by shell functions.
  56  **/
  57 GQuark
  58 g_shell_error_quark (void)
  59 {
  60   return g_quark_from_static_string ("g-shell-error-quark");
  61 }
  62
  63 /* Single quotes preserve the literal string exactly. escape
  64  * sequences are not allowed; not even \' - if you want a '
  65  * in the quoted text, you have to do something like 'foo'\''bar'
  66  *
  67  * Double quotes allow $ ` " \ and newline to be escaped with backslash.
  68  * Otherwise double quotes preserve things literally.
  69  */
  70
  71 static gboolean
  72 unquote_string_inplace (gchar* str, gchar** end, GError** err)
  73 {
  74   gchar* dest;
  75   gchar* s;
  76   gchar quote_char;
  77
  78   g_return_val_if_fail(end != NULL, FALSE);
  79   g_return_val_if_fail(err == NULL || *err == NULL, FALSE);
  80   g_return_val_if_fail(str != NULL, FALSE);
  81
  82   dest = s = str;
  83
  84   quote_char = *s;
  85
  86   if (!(*s == '"' || *s == '\''))
  87     {
  88       g_set_error_literal (err,
  89                            G_SHELL_ERROR,
  90                            G_SHELL_ERROR_BAD_QUOTING,
  91                            _("Quoted text doesn't begin with a quotation mark"));
  92       *end = str;
  93       return FALSE;
  94     }
  95
  96   /* Skip the initial quote mark */
  97   ++s;
  98
  99   if (quote_char == '"')
 100     {
 101       while (*s)
 102         {
 103           g_assert(s > dest); /* loop invariant */
 104
 105           switch (*s)
 106             {
 107             case '"':
 108               /* End of the string, return now */
 109               *dest = '\0';
 110               ++s;
 111               *end = s;
 112               return TRUE;
 113               break;
 114
 115             case '\\':
 116               /* Possible escaped quote or \ */
 117               ++s;
 118               switch (*s)
 119                 {
 120                 case '"':
 121                 case '\\':
 122                 case '`':
 123                 case '$':
 124                 case '\n':
 125                   *dest = *s;
 126                   ++s;
 127                   ++dest;
 128                   break;
 129
 130                 default:
 131                   /* not an escaped char */
 132                   *dest = '\\';
 133                   ++dest;
 134                   /* ++s already done. */
 135                   break;
 136                 }
 137               break;
 138
 139             default:
 140               *dest = *s;
 141               ++dest;
 142               ++s;
 143               break;
 144             }
 145
 146           g_assert(s > dest); /* loop invariant */
 147         }
 148     }
 149   else
 150     {
 151       while (*s)
 152         {
 153           g_assert(s > dest); /* loop invariant */
 154
 155           if (*s == '\'')
 156             {
 157               /* End of the string, return now */
 158               *dest = '\0';
 159               ++s;
 160               *end = s;
 161               return TRUE;
 162             }
 163           else
 164             {
 165               *dest = *s;
 166               ++dest;
 167               ++s;
 168             }
 169
 170           g_assert(s > dest); /* loop invariant */
 171         }
 172     }
 173
 174   /* If we reach here this means the close quote was never encountered */
 175
 176   *dest = '\0';
 177
 178   g_set_error_literal (err,
 179                        G_SHELL_ERROR,
 180                        G_SHELL_ERROR_BAD_QUOTING,
 181                        _("Unmatched quotation mark in command line or other shell-quoted text"));
 182   *end = s;
 183   return FALSE;
 184 }
 185
 186 /**
 187  * g_shell_quote:
 188  * @unquoted_string: a literal string
 189  *
 190  * Quotes a string so that the shell (/bin/sh) will interpret the
 191  * quoted string to mean @unquoted_string. If you pass a filename to
 192  * the shell, for example, you should first quote it with this
 193  * function.  The return value must be freed with g_free(). The
 194  * quoting style used is undefined (single or double quotes may be
 195  * used).
 196  *
 197  * Return value: quoted string
 198  **/
 199 gchar*
 200 g_shell_quote (const gchar *unquoted_string)
 201 {
 202   /* We always use single quotes, because the algorithm is cheesier.
 203    * We could use double if we felt like it, that might be more
 204    * human-readable.
 205    */
 206
 207   const gchar *p;
 208   GString *dest;
 209
 210   g_return_val_if_fail (unquoted_string != NULL, NULL);
 211
 212   dest = g_string_new ("'");
 213
 214   p = unquoted_string;
 215
 216   /* could speed this up a lot by appending chunks of text at a
 217    * time.
 218    */
 219   while (*p)
 220     {
 221       /* Replace literal ' with a close ', a \', and a open ' */
 222       if (*p == '\'')
 223         g_string_append (dest, "'\\''");
 224       else
 225         g_string_append_c (dest, *p);
 226
 227       ++p;
 228     }
 229
 230   /* close the quote */
 231   g_string_append_c (dest, '\'');
 232
 233   return g_string_free (dest, FALSE);
 234 }
 235
 236 /**
 237  * g_shell_unquote:
 238  * @quoted_string: shell-quoted string
 239  * @error: error return location or NULL
 240  *
 241  * Unquotes a string as the shell (/bin/sh) would. Only handles
 242  * quotes; if a string contains file globs, arithmetic operators,
 243  * variables, backticks, redirections, or other special-to-the-shell
 244  * features, the result will be different from the result a real shell
 245  * would produce (the variables, backticks, etc. will be passed
 246  * through literally instead of being expanded). This function is
 247  * guaranteed to succeed if applied to the result of
 248  * g_shell_quote(). If it fails, it returns %NULL and sets the
 249  * error. The @quoted_string need not actually contain quoted or
 250  * escaped text; g_shell_unquote() simply goes through the string and
 251  * unquotes/unescapes anything that the shell would. Both single and
 252  * double quotes are handled, as are escapes including escaped
 253  * newlines. The return value must be freed with g_free(). Possible
 254  * errors are in the #G_SHELL_ERROR domain.
 255  *
 256  * Shell quoting rules are a bit strange. Single quotes preserve the
 257  * literal string exactly. escape sequences are not allowed; not even
 258  * \' - if you want a ' in the quoted text, you have to do something
 259  * like 'foo'\''bar'.  Double quotes allow $, `, ", \, and newline to
 260  * be escaped with backslash. Otherwise double quotes preserve things
 261  * literally.
 262  *
 263  * Return value: an unquoted string
 264  **/
 265 gchar*
 266 g_shell_unquote (const gchar *quoted_string,
 267                  GError     **error)
 268 {
 269   gchar *unquoted;
 270   gchar *end;
 271   gchar *start;
 272   GString *retval;
 273
 274   g_return_val_if_fail (quoted_string != NULL, NULL);
 275
 276   unquoted = g_strdup (quoted_string);
 277
 278   start = unquoted;
 279   end = unquoted;
 280   retval = g_string_new (NULL);
 281
 282   /* The loop allows cases such as
 283    * "foo"blah blah'bar'woo foo"baz"la la la\'\''foo'
 284    */
 285   while (*start)
 286     {
 287       /* Append all non-quoted chars, honoring backslash escape
 288        */
 289
 290       while (*start && !(*start == '"' || *start == '\''))
 291         {
 292           if (*start == '\\')
 293             {
 294               /* all characters can get escaped by backslash,
 295                * except newline, which is removed if it follows
 296                * a backslash outside of quotes
 297                */
 298
 299               ++start;
 300               if (*start)
 301                 {
 302                   if (*start != '\n')
 303                     g_string_append_c (retval, *start);
 304                   ++start;
 305                 }
 306             }
 307           else
 308             {
 309               g_string_append_c (retval, *start);
 310               ++start;
 311             }
 312         }
 313
 314       if (*start)
 315         {
 316           if (!unquote_string_inplace (start, &end, error))
 317             {
 318               goto error;
 319             }
 320           else
 321             {
 322               g_string_append (retval, start);
 323               start = end;
 324             }
 325         }
 326     }
 327
 328   g_free (unquoted);
 329   return g_string_free (retval, FALSE);
 330
 331  error:
 332   g_assert (error == NULL || *error != NULL);
 333
 334   g_free (unquoted);
 335   g_string_free (retval, TRUE);
 336   return NULL;
 337 }
 338
 339 /* g_parse_argv() does a semi-arbitrary weird subset of the way
 340  * the shell parses a command line. We don't do variable expansion,
 341  * don't understand that operators are tokens, don't do tilde expansion,
 342  * don't do command substitution, no arithmetic expansion, IFS gets ignored,
 343  * don't do filename globs, don't remove redirection stuff, etc.
 344  *
 345  * READ THE UNIX98 SPEC on "Shell Command Language" before changing
 346  * the behavior of this code.
 347  *
 348  * Steps to parsing the argv string:
 349  *
 350  *  - tokenize the string (but since we ignore operators,
 351  *    our tokenization may diverge from what the shell would do)
 352  *    note that tokenization ignores the internals of a quoted
 353  *    word and it always splits on spaces, not on IFS even
 354  *    if we used IFS. We also ignore "end of input indicator"
 355  *    (I guess this is control-D?)
 356  *
 357  *    Tokenization steps, from UNIX98 with operator stuff removed,
 358  *    are:
 359  *
 360  *    1) "If the current character is backslash, single-quote or
 361  *        double-quote (\, ' or ") and it is not quoted, it will affect
 362  *        quoting for subsequent characters up to the end of the quoted
 363  *        text. The rules for quoting are as described in Quoting
 364  *        . During token recognition no substitutions will be actually
 365  *        performed, and the result token will contain exactly the
 366  *        characters that appear in the input (except for newline
 367  *        character joining), unmodified, including any embedded or
 368  *        enclosing quotes or substitution operators, between the quote
 369  *        mark and the end of the quoted text. The token will not be
 370  *        delimited by the end of the quoted field."
 371  *
 372  *    2) "If the current character is an unquoted newline character,
 373  *        the current token will be delimited."
 374  *
 375  *    3) "If the current character is an unquoted blank character, any
 376  *        token containing the previous character is delimited and the
 377  *        current character will be discarded."
 378  *
 379  *    4) "If the previous character was part of a word, the current
 380  *        character will be appended to that word."
 381  *
 382  *    5) "If the current character is a "#", it and all subsequent
 383  *        characters up to, but excluding, the next newline character
 384  *        will be discarded as a comment. The newline character that
 385  *        ends the line is not considered part of the comment. The
 386  *        "#" starts a comment only when it is at the beginning of a
 387  *        token. Since the search for the end-of-comment does not
 388  *        consider an escaped newline character specially, a comment
 389  *        cannot be continued to the next line."
 390  *
 391  *    6) "The current character will be used as the start of a new word."
 392  *
 393  *
 394  *  - for each token (word), perform portions of word expansion, namely
 395  *    field splitting (using default whitespace IFS) and quote
 396  *    removal.  Field splitting may increase the number of words.
 397  *    Quote removal does not increase the number of words.
 398  *
 399  *   "If the complete expansion appropriate for a word results in an
 400  *   empty field, that empty field will be deleted from the list of
 401  *   fields that form the completely expanded command, unless the
 402  *   original word contained single-quote or double-quote characters."
 403  *    - UNIX98 spec
 404  *
 405  *
 406  */
 407
 408 static inline void
 409 ensure_token (GString **token)
 410 {
 411   if (*token == NULL)
 412     *token = g_string_new (NULL);
 413 }
 414
 415 static void
 416 delimit_token (GString **token,
 417                GSList **retval)
 418 {
 419   if (*token == NULL)
 420     return;
 421
 422   *retval = g_slist_prepend (*retval, g_string_free (*token, FALSE));
 423
 424   *token = NULL;
 425 }
 426
 427 static GSList*
 428 tokenize_command_line (const gchar *command_line,
 429                        GError **error)
 430 {
 431   gchar current_quote;
 432   const gchar *p;
 433   GString *current_token = NULL;
 434   GSList *retval = NULL;
 435   gboolean quoted;
 436
 437   current_quote = '\0';
 438   quoted = FALSE;
 439   p = command_line;
 440
 441   while (*p)
 442     {
 443       if (current_quote == '\\')
 444         {
 445           if (*p == '\n')
 446             {
 447               /* we append nothing; backslash-newline become nothing */
 448             }
 449           else
 450             {
 451               /* we append the backslash and the current char,
 452                * to be interpreted later after tokenization
 453                */
 454               ensure_token (&current_token);
 455               g_string_append_c (current_token, '\\');
 456               g_string_append_c (current_token, *p);
 457             }
 458
 459           current_quote = '\0';
 460         }
 461       else if (current_quote == '#')
 462         {
 463           /* Discard up to and including next newline */
 464           while (*p && *p != '\n')
 465             ++p;
 466
 467           current_quote = '\0';
 468
 469           if (*p == '\0')
 470             break;
 471         }
 472       else if (current_quote)
 473         {
 474           if (*p == current_quote &&
 475               /* check that it isn't an escaped double quote */
 476               !(current_quote == '"' && quoted))
 477             {
 478               /* close the quote */
 479               current_quote = '\0';
 480             }
 481
 482           /* Everything inside quotes, and the close quote,
 483            * gets appended literally.
 484            */
 485
 486           ensure_token (&current_token);
 487           g_string_append_c (current_token, *p);
 488         }
 489       else
 490         {
 491           switch (*p)
 492             {
 493             case '\n':
 494               delimit_token (&current_token, &retval);
 495               break;
 496
 497             case ' ':
 498             case '\t':
 499               /* If the current token contains the previous char, delimit
 500                * the current token. A nonzero length
 501                * token should always contain the previous char.
 502                */
 503               if (current_token &&
 504                   current_token->len > 0)
 505                 {
 506                   delimit_token (&current_token, &retval);
 507                 }
 508
 509               /* discard all unquoted blanks (don't add them to a token) */
 510               break;
 511
 512
 513               /* single/double quotes are appended to the token,
 514                * escapes are maybe appended next time through the loop,
 515                * comment chars are never appended.
 516                */
 517
 518             case '\'':
 519             case '"':
 520               ensure_token (&current_token);
 521               g_string_append_c (current_token, *p);
 522
 523               /* FALL THRU */
 524
 525             case '#':
 526             case '\\':
 527               current_quote = *p;
 528               break;
 529
 530             default:
 531               /* Combines rules 4) and 6) - if we have a token, append to it,
 532                * otherwise create a new token.
 533                */
 534               ensure_token (&current_token);
 535               g_string_append_c (current_token, *p);
 536               break;
 537             }
 538         }
 539
 540       /* We need to count consecutive backslashes mod 2,
 541        * to detect escaped doublequotes.
 542        */
 543       if (*p != '\\')
 544         quoted = FALSE;
 545       else
 546         quoted = !quoted;
 547
 548       ++p;
 549     }
 550
 551   delimit_token (&current_token, &retval);
 552
 553   if (current_quote)
 554     {
 555       if (current_quote == '\\')
 556         g_set_error (error,
 557                      G_SHELL_ERROR,
 558                      G_SHELL_ERROR_BAD_QUOTING,
 559                      _("Text ended just after a '\\' character."
 560                        " (The text was '%s')"),
 561                      command_line);
 562       else
 563         g_set_error (error,
 564                      G_SHELL_ERROR,
 565                      G_SHELL_ERROR_BAD_QUOTING,
 566                      _("Text ended before matching quote was found for %c."
 567                        " (The text was '%s')"),
 568                      current_quote, command_line);
 569
 570       goto error;
 571     }
 572
 573   if (retval == NULL)
 574     {
 575       g_set_error_literal (error,
 576                            G_SHELL_ERROR,
 577                            G_SHELL_ERROR_EMPTY_STRING,
 578                            _("Text was empty (or contained only whitespace)"));
 579
 580       goto error;
 581     }
 582
 583   /* we appended backward */
 584   retval = g_slist_reverse (retval);
 585
 586   return retval;
 587
 588  error:
 589   g_assert (error == NULL || *error != NULL);
 590
 591   g_slist_free_full (retval, g_free);
 592
 593   return NULL;
 594 }
 595
 596 /**
 597  * g_shell_parse_argv:
 598  * @command_line: command line to parse
 599  * @argcp: (out): return location for number of args
 600  * @argvp: (out) (array length=argcp zero-terminated=1): return location for array of args
 601  * @error: return location for error
 602  *
 603  * Parses a command line into an argument vector, in much the same way
 604  * the shell would, but without many of the expansions the shell would
 605  * perform (variable expansion, globs, operators, filename expansion,
 606  * etc. are not supported). The results are defined to be the same as
 607  * those you would get from a UNIX98 /bin/sh, as long as the input
 608  * contains none of the unsupported shell expansions. If the input
 609  * does contain such expansions, they are passed through
 610  * literally. Possible errors are those from the #G_SHELL_ERROR
 611  * domain. Free the returned vector with g_strfreev().
 612  *
 613  * Return value: %TRUE on success, %FALSE if error set
 614  **/
 615 gboolean
 616 g_shell_parse_argv (const gchar *command_line,
 617                     gint        *argcp,
 618                     gchar     ***argvp,
 619                     GError     **error)
 620 {
 621   /* Code based on poptParseArgvString() from libpopt */
 622   gint argc = 0;
 623   gchar **argv = NULL;
 624   GSList *tokens = NULL;
 625   gint i;
 626   GSList *tmp_list;
 627
 628   g_return_val_if_fail (command_line != NULL, FALSE);
 629
 630   tokens = tokenize_command_line (command_line, error);
 631   if (tokens == NULL)
 632     return FALSE;
 633
 634   /* Because we can't have introduced any new blank space into the
 635    * tokens (we didn't do any new expansions), we don't need to
 636    * perform field splitting. If we were going to honor IFS or do any
 637    * expansions, we would have to do field splitting on each word
 638    * here. Also, if we were going to do any expansion we would need to
 639    * remove any zero-length words that didn't contain quotes
 640    * originally; but since there's no expansion we know all words have
 641    * nonzero length, unless they contain quotes.
 642    *
 643    * So, we simply remove quotes, and don't do any field splitting or
 644    * empty word removal, since we know there was no way to introduce
 645    * such things.
 646    */
 647
 648   argc = g_slist_length (tokens);
 649   argv = g_new0 (gchar*, argc + 1);
 650   i = 0;
 651   tmp_list = tokens;
 652   while (tmp_list)
 653     {
 654       argv[i] = g_shell_unquote (tmp_list->data, error);
 655
 656       /* Since we already checked that quotes matched up in the
 657        * tokenizer, this shouldn't be possible to reach I guess.
 658        */
 659       if (argv[i] == NULL)
 660         goto failed;
 661
 662       tmp_list = g_slist_next (tmp_list);
 663       ++i;
 664     }
 665
 666   g_slist_free_full (tokens, g_free);
 667
 668   if (argcp)
 669     *argcp = argc;
 670
 671   if (argvp)
 672     *argvp = argv;
 673   else
 674     g_strfreev (argv);
 675
 676   return TRUE;
 677
 678  failed:
 679
 680   g_assert (error == NULL || *error != NULL);
 681   g_strfreev (argv);
 682   g_slist_free_full (tokens, g_free);
 683
 684   return FALSE;
 685 }