glib/gshell.c - third_party/glib - Git at Google

 /* gshell.c - Shell-related utilities
  *
  *  Copyright 2000 Red Hat, Inc.
  *  g_execvpe implementation based on GNU libc execvp:
  *   Copyright 1991, 92, 95, 96, 97, 98, 99 Free Software Foundation, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public License
  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  */

 #include "config.h"

 #include <string.h>

 #include "gshell.h"

 #include "gslist.h"
 #include "gstrfuncs.h"
 #include "gstring.h"
 #include "gtestutils.h"
 #include "glibintl.h"
 #include "gthread.h"

 /**
  * SECTION:shell
  * @title: Shell-related Utilities
  * @short_description: shell-like commandline handling
  *
  * GLib provides the functions g_shell_quote() and g_shell_unquote()
  * to handle shell-like quoting in strings. The function g_shell_parse_argv()
  * parses a string similar to the way a POSIX shell (/bin/sh) would.
  *
  * Note that string handling in shells has many obscure and historical
  * corner-cases which these functions do not necessarily reproduce. They
  * are good enough in practice, though.
  */

 /**
  * G_SHELL_ERROR:
  *
  * Error domain for shell functions. Errors in this domain will be from
  * the #GShellError enumeration. See #GError for information on error
  * domains.
  **/

 /**
  * GShellError:
  * @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting.
  * @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty.
  * @G_SHELL_ERROR_FAILED: Some other error.
  *
  * Error codes returned by shell functions.
  **/
 G_DEFINE_QUARK (g-shell-error-quark, g_shell_error)

 /* Single quotes preserve the literal string exactly. escape
  * sequences are not allowed; not even \' - if you want a '
  * in the quoted text, you have to do something like 'foo'\''bar'
  *
  * Double quotes allow $ ` " \ and newline to be escaped with backslash.
  * Otherwise double quotes preserve things literally.
  */

 static gboolean
 unquote_string_inplace (gchar* str, gchar** end, GError** err)
 {
   gchar* dest;
   gchar* s;
   gchar quote_char;

   g_return_val_if_fail(end != NULL, FALSE);
   g_return_val_if_fail(err == NULL || *err == NULL, FALSE);
   g_return_val_if_fail(str != NULL, FALSE);

   dest = s = str;

   quote_char = *s;

   if (!(*s == '"' || *s == '\''))
     {
       g_set_error_literal (err,
                            G_SHELL_ERROR,
                            G_SHELL_ERROR_BAD_QUOTING,
                            _("Quoted text doesn’t begin with a quotation mark"));
       *end = str;
       return FALSE;
     }

   /* Skip the initial quote mark */
   ++s;

   if (quote_char == '"')
     {
       while (*s)
         {
           g_assert(s > dest); /* loop invariant */

           switch (*s)
             {
             case '"':
               /* End of the string, return now */
               *dest = '\0';
               ++s;
               *end = s;
               return TRUE;
               break;

             case '\\':
               /* Possible escaped quote or \ */
               ++s;
               switch (*s)
                 {
                 case '"':
                 case '\\':
                 case '`':
                 case '$':
                 case '\n':
                   *dest = *s;
                   ++s;
                   ++dest;
                   break;

                 default:
                   /* not an escaped char */
                   *dest = '\\';
                   ++dest;
                   /* ++s already done. */
                   break;
                 }
               break;

             default:
               *dest = *s;
               ++dest;
               ++s;
               break;
             }

           g_assert(s > dest); /* loop invariant */
         }
     }
   else
     {
       while (*s)
         {
           g_assert(s > dest); /* loop invariant */

           if (*s == '\'')
             {
               /* End of the string, return now */
               *dest = '\0';
               ++s;
               *end = s;
               return TRUE;
             }
           else
             {
               *dest = *s;
               ++dest;
               ++s;
             }

           g_assert(s > dest); /* loop invariant */
         }
     }

   /* If we reach here this means the close quote was never encountered */

   *dest = '\0';

   g_set_error_literal (err,
                        G_SHELL_ERROR,
                        G_SHELL_ERROR_BAD_QUOTING,
                        _("Unmatched quotation mark in command line or other shell-quoted text"));
   *end = s;
   return FALSE;
 }

 /**
  * g_shell_quote:
  * @unquoted_string: (type filename): a literal string
  *
  * Quotes a string so that the shell (/bin/sh) will interpret the
  * quoted string to mean @unquoted_string. If you pass a filename to
  * the shell, for example, you should first quote it with this
  * function.  The return value must be freed with g_free(). The
  * quoting style used is undefined (single or double quotes may be
  * used).
  *
  * Returns: (type filename): quoted string
  **/
 gchar*
 g_shell_quote (const gchar *unquoted_string)
 {
   /* We always use single quotes, because the algorithm is cheesier.
    * We could use double if we felt like it, that might be more
    * human-readable.
    */

   const gchar *p;
   GString *dest;

   g_return_val_if_fail (unquoted_string != NULL, NULL);

   dest = g_string_new ("'");

   p = unquoted_string;

   /* could speed this up a lot by appending chunks of text at a
    * time.
    */
   while (*p)
     {
       /* Replace literal ' with a close ', a \', and a open ' */
       if (*p == '\'')
         g_string_append (dest, "'\\''");
       else
         g_string_append_c (dest, *p);

       ++p;
     }

   /* close the quote */
   g_string_append_c (dest, '\'');

   return g_string_free (dest, FALSE);
 }

 /**
  * g_shell_unquote:
  * @quoted_string: (type filename): shell-quoted string
  * @error: error return location or NULL
  *
  * Unquotes a string as the shell (/bin/sh) would. Only handles
  * quotes; if a string contains file globs, arithmetic operators,
  * variables, backticks, redirections, or other special-to-the-shell
  * features, the result will be different from the result a real shell
  * would produce (the variables, backticks, etc. will be passed
  * through literally instead of being expanded). This function is
  * guaranteed to succeed if applied to the result of
  * g_shell_quote(). If it fails, it returns %NULL and sets the
  * error. The @quoted_string need not actually contain quoted or
  * escaped text; g_shell_unquote() simply goes through the string and
  * unquotes/unescapes anything that the shell would. Both single and
  * double quotes are handled, as are escapes including escaped
  * newlines. The return value must be freed with g_free(). Possible
  * errors are in the #G_SHELL_ERROR domain.
  *
  * Shell quoting rules are a bit strange. Single quotes preserve the
  * literal string exactly. escape sequences are not allowed; not even
  * \' - if you want a ' in the quoted text, you have to do something
  * like 'foo'\''bar'.  Double quotes allow $, `, ", \, and newline to
  * be escaped with backslash. Otherwise double quotes preserve things
  * literally.
  *
  * Returns: (type filename): an unquoted string
  **/
 gchar*
 g_shell_unquote (const gchar *quoted_string,
                  GError     **error)
 {
   gchar *unquoted;
   gchar *end;
   gchar *start;
   GString *retval;

   g_return_val_if_fail (quoted_string != NULL, NULL);

   unquoted = g_strdup (quoted_string);

   start = unquoted;
   end = unquoted;
   retval = g_string_new (NULL);

   /* The loop allows cases such as
    * "foo"blah blah'bar'woo foo"baz"la la la\'\''foo'
    */
   while (*start)
     {
       /* Append all non-quoted chars, honoring backslash escape
        */

       while (*start && !(*start == '"' || *start == '\''))
         {
           if (*start == '\\')
             {
               /* all characters can get escaped by backslash,
                * except newline, which is removed if it follows
                * a backslash outside of quotes
                */

               ++start;
               if (*start)
                 {
                   if (*start != '\n')
                     g_string_append_c (retval, *start);
                   ++start;
                 }
             }
           else
             {
               g_string_append_c (retval, *start);
               ++start;
             }
         }

       if (*start)
         {
           if (!unquote_string_inplace (start, &end, error))
             {
               goto error;
             }
           else
             {
               g_string_append (retval, start);
               start = end;
             }
         }
     }

   g_free (unquoted);
   return g_string_free (retval, FALSE);

  error:
   g_assert (error == NULL || *error != NULL);

   g_free (unquoted);
   g_string_free (retval, TRUE);
   return NULL;
 }

 /* g_parse_argv() does a semi-arbitrary weird subset of the way
  * the shell parses a command line. We don't do variable expansion,
  * don't understand that operators are tokens, don't do tilde expansion,
  * don't do command substitution, no arithmetic expansion, IFS gets ignored,
  * don't do filename globs, don't remove redirection stuff, etc.
  *
  * READ THE UNIX98 SPEC on "Shell Command Language" before changing
  * the behavior of this code.
  *
  * Steps to parsing the argv string:
  *
  *  - tokenize the string (but since we ignore operators,
  *    our tokenization may diverge from what the shell would do)
  *    note that tokenization ignores the internals of a quoted
  *    word and it always splits on spaces, not on IFS even
  *    if we used IFS. We also ignore "end of input indicator"
  *    (I guess this is control-D?)
  *
  *    Tokenization steps, from UNIX98 with operator stuff removed,
  *    are:
  *
  *    1) "If the current character is backslash, single-quote or
  *        double-quote (\, ' or ") and it is not quoted, it will affect
  *        quoting for subsequent characters up to the end of the quoted
  *        text. The rules for quoting are as described in Quoting
  *        . During token recognition no substitutions will be actually
  *        performed, and the result token will contain exactly the
  *        characters that appear in the input (except for newline
  *        character joining), unmodified, including any embedded or
  *        enclosing quotes or substitution operators, between the quote
  *        mark and the end of the quoted text. The token will not be
  *        delimited by the end of the quoted field."
  *
  *    2) "If the current character is an unquoted newline character,
  *        the current token will be delimited."
  *
  *    3) "If the current character is an unquoted blank character, any
  *        token containing the previous character is delimited and the
  *        current character will be discarded."
  *
  *    4) "If the previous character was part of a word, the current
  *        character will be appended to that word."
  *
  *    5) "If the current character is a "#", it and all subsequent
  *        characters up to, but excluding, the next newline character
  *        will be discarded as a comment. The newline character that
  *        ends the line is not considered part of the comment. The
  *        "#" starts a comment only when it is at the beginning of a
  *        token. Since the search for the end-of-comment does not
  *        consider an escaped newline character specially, a comment
  *        cannot be continued to the next line."
  *
  *    6) "The current character will be used as the start of a new word."
  *
  *
  *  - for each token (word), perform portions of word expansion, namely
  *    field splitting (using default whitespace IFS) and quote
  *    removal.  Field splitting may increase the number of words.
  *    Quote removal does not increase the number of words.
  *
  *   "If the complete expansion appropriate for a word results in an
  *   empty field, that empty field will be deleted from the list of
  *   fields that form the completely expanded command, unless the
  *   original word contained single-quote or double-quote characters."
  *    - UNIX98 spec
  *
  *
  */

 static inline void
 ensure_token (GString **token)
 {
   if (*token == NULL)
     *token = g_string_new (NULL);
 }

 static void
 delimit_token (GString **token,
                GSList **retval)
 {
   if (*token == NULL)
     return;

   *retval = g_slist_prepend (*retval, g_string_free (*token, FALSE));

   *token = NULL;
 }

 static GSList*
 tokenize_command_line (const gchar *command_line,
                        GError **error)
 {
   gchar current_quote;
   const gchar *p;
   GString *current_token = NULL;
   GSList *retval = NULL;
   gboolean quoted;

   current_quote = '\0';
   quoted = FALSE;
   p = command_line;

   while (*p)
     {
       if (current_quote == '\\')
         {
           if (*p == '\n')
             {
               /* we append nothing; backslash-newline become nothing */
             }
           else
             {
               /* we append the backslash and the current char,
                * to be interpreted later after tokenization
                */
               ensure_token (&current_token);
               g_string_append_c (current_token, '\\');
               g_string_append_c (current_token, *p);
             }

           current_quote = '\0';
         }
       else if (current_quote == '#')
         {
           /* Discard up to and including next newline */
           while (*p && *p != '\n')
             ++p;

           current_quote = '\0';

           if (*p == '\0')
             break;
         }
       else if (current_quote)
         {
           if (*p == current_quote &&
               /* check that it isn't an escaped double quote */
               !(current_quote == '"' && quoted))
             {
               /* close the quote */
               current_quote = '\0';
             }

           /* Everything inside quotes, and the close quote,
            * gets appended literally.
            */

           ensure_token (&current_token);
           g_string_append_c (current_token, *p);
         }
       else
         {
           switch (*p)
             {
             case '\n':
               delimit_token (&current_token, &retval);
               break;

             case ' ':
             case '\t':
               /* If the current token contains the previous char, delimit
                * the current token. A nonzero length
                * token should always contain the previous char.
                */
               if (current_token &&
                   current_token->len > 0)
                 {
                   delimit_token (&current_token, &retval);
                 }

               /* discard all unquoted blanks (don't add them to a token) */
               break;


               /* single/double quotes are appended to the token,
                * escapes are maybe appended next time through the loop,
                * comment chars are never appended.
                */

             case '\'':
             case '"':
               ensure_token (&current_token);
               g_string_append_c (current_token, *p);

               /* FALL THRU */
             case '\\':
               current_quote = *p;
               break;

             case '#':
               if (p == command_line)
 	        { /* '#' was the first char */
                   current_quote = *p;
                   break;
                 }
               switch(*(p-1))
                 {
                   case ' ':
                   case '\n':
                   case '\0':
                     current_quote = *p;
                     break;
                   default:
                     ensure_token (&current_token);
                     g_string_append_c (current_token, *p);
 		    break;
                 }
               break;

             default:
               /* Combines rules 4) and 6) - if we have a token, append to it,
                * otherwise create a new token.
                */
               ensure_token (&current_token);
               g_string_append_c (current_token, *p);
               break;
             }
         }

       /* We need to count consecutive backslashes mod 2,
        * to detect escaped doublequotes.
        */
       if (*p != '\\')
 	quoted = FALSE;
       else
 	quoted = !quoted;

       ++p;
     }

   delimit_token (&current_token, &retval);

   if (current_quote)
     {
       if (current_quote == '\\')
         g_set_error (error,
                      G_SHELL_ERROR,
                      G_SHELL_ERROR_BAD_QUOTING,
                      _("Text ended just after a “\\” character."
                        " (The text was “%s”)"),
                      command_line);
       else
         g_set_error (error,
                      G_SHELL_ERROR,
                      G_SHELL_ERROR_BAD_QUOTING,
                      _("Text ended before matching quote was found for %c."
                        " (The text was “%s”)"),
                      current_quote, command_line);

       goto error;
     }

   if (retval == NULL)
     {
       g_set_error_literal (error,
                            G_SHELL_ERROR,
                            G_SHELL_ERROR_EMPTY_STRING,
                            _("Text was empty (or contained only whitespace)"));

       goto error;
     }

   /* we appended backward */
   retval = g_slist_reverse (retval);

   return retval;

  error:
   g_assert (error == NULL || *error != NULL);

   g_slist_free_full (retval, g_free);

   return NULL;
 }

 /**
  * g_shell_parse_argv:
  * @command_line: (type filename): command line to parse
  * @argcp: (out) (optional): return location for number of args
  * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
  *   return location for array of args
  * @error: (optional): return location for error
  *
  * Parses a command line into an argument vector, in much the same way
  * the shell would, but without many of the expansions the shell would
  * perform (variable expansion, globs, operators, filename expansion,
  * etc. are not supported). The results are defined to be the same as
  * those you would get from a UNIX98 /bin/sh, as long as the input
  * contains none of the unsupported shell expansions. If the input
  * does contain such expansions, they are passed through
  * literally. Possible errors are those from the #G_SHELL_ERROR
  * domain. Free the returned vector with g_strfreev().
  *
  * Returns: %TRUE on success, %FALSE if error set
  **/
 gboolean
 g_shell_parse_argv (const gchar *command_line,
                     gint        *argcp,
                     gchar     ***argvp,
                     GError     **error)
 {
   /* Code based on poptParseArgvString() from libpopt */
   gint argc = 0;
   gchar **argv = NULL;
   GSList *tokens = NULL;
   gint i;
   GSList *tmp_list;

   g_return_val_if_fail (command_line != NULL, FALSE);

   tokens = tokenize_command_line (command_line, error);
   if (tokens == NULL)
     return FALSE;

   /* Because we can't have introduced any new blank space into the
    * tokens (we didn't do any new expansions), we don't need to
    * perform field splitting. If we were going to honor IFS or do any
    * expansions, we would have to do field splitting on each word
    * here. Also, if we were going to do any expansion we would need to
    * remove any zero-length words that didn't contain quotes
    * originally; but since there's no expansion we know all words have
    * nonzero length, unless they contain quotes.
    *
    * So, we simply remove quotes, and don't do any field splitting or
    * empty word removal, since we know there was no way to introduce
    * such things.
    */

   argc = g_slist_length (tokens);
   argv = g_new0 (gchar*, argc + 1);
   i = 0;
   tmp_list = tokens;
   while (tmp_list)
     {
       argv[i] = g_shell_unquote (tmp_list->data, error);

       /* Since we already checked that quotes matched up in the
        * tokenizer, this shouldn't be possible to reach I guess.
        */
       if (argv[i] == NULL)
         goto failed;

       tmp_list = g_slist_next (tmp_list);
       ++i;
     }

   g_slist_free_full (tokens, g_free);

   if (argcp)
     *argcp = argc;

   if (argvp)
     *argvp = argv;
   else
     g_strfreev (argv);

   return TRUE;

  failed:

   g_assert (error == NULL || *error != NULL);
   g_strfreev (argv);
   g_slist_free_full (tokens, g_free);

   return FALSE;
 }
	/* gshell.c - Shell-related utilities
	*
	* Copyright 2000 Red Hat, Inc.
	* g_execvpe implementation based on GNU libc execvp:
	* Copyright 1991, 92, 95, 96, 97, 98, 99 Free Software Foundation, Inc.
	*
	* This library is free software; you can redistribute it and/or
	* modify it under the terms of the GNU Lesser General Public
	* License as published by the Free Software Foundation; either
	* version 2.1 of the License, or (at your option) any later version.
	*
	* This library is distributed in the hope that it will be useful,
	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	* Lesser General Public License for more details.
	*
	* You should have received a copy of the GNU Lesser General Public License
	* along with this library; if not, see <http://www.gnu.org/licenses/>.
	*/

	#include "config.h"

	#include <string.h>

	#include "gshell.h"

	#include "gslist.h"
	#include "gstrfuncs.h"
	#include "gstring.h"
	#include "gtestutils.h"
	#include "glibintl.h"
	#include "gthread.h"

	/**
	* SECTION:shell
	* @title: Shell-related Utilities
	* @short_description: shell-like commandline handling
	*
	* GLib provides the functions g_shell_quote() and g_shell_unquote()
	* to handle shell-like quoting in strings. The function g_shell_parse_argv()
	* parses a string similar to the way a POSIX shell (/bin/sh) would.
	*
	* Note that string handling in shells has many obscure and historical
	* corner-cases which these functions do not necessarily reproduce. They
	* are good enough in practice, though.
	*/

	/**
	* G_SHELL_ERROR:
	*
	* Error domain for shell functions. Errors in this domain will be from
	* the #GShellError enumeration. See #GError for information on error
	* domains.
	**/

	/**
	* GShellError:
	* @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting.
	* @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty.
	* @G_SHELL_ERROR_FAILED: Some other error.
	*
	* Error codes returned by shell functions.
	**/
	G_DEFINE_QUARK (g-shell-error-quark, g_shell_error)

	/* Single quotes preserve the literal string exactly. escape
	* sequences are not allowed; not even \' - if you want a '
	* in the quoted text, you have to do something like 'foo'\''bar'
	*
	* Double quotes allow $ ` " \ and newline to be escaped with backslash.
	* Otherwise double quotes preserve things literally.
	*/

	static gboolean
	unquote_string_inplace (gchar* str, gchar end, GError err)
	{
	gchar* dest;
	gchar* s;
	gchar quote_char;

	g_return_val_if_fail(end != NULL, FALSE);
	g_return_val_if_fail(err == NULL \|\| *err == NULL, FALSE);
	g_return_val_if_fail(str != NULL, FALSE);

	dest = s = str;

	quote_char = *s;

	if (!(s == '"' \|\| s == '\''))
	{
	g_set_error_literal (err,
	G_SHELL_ERROR,
	G_SHELL_ERROR_BAD_QUOTING,
	_("Quoted text doesn’t begin with a quotation mark"));
	*end = str;
	return FALSE;
	}

	/* Skip the initial quote mark */
	++s;

	if (quote_char == '"')
	{
	while (*s)
	{
	g_assert(s > dest); /* loop invariant */

	switch (*s)
	{
	case '"':
	/* End of the string, return now */
	*dest = '\0';
	++s;
	*end = s;
	return TRUE;
	break;

	case '\\':
	/* Possible escaped quote or \ */
	++s;
	switch (*s)
	{
	case '"':
	case '\\':
	case '`':
	case '$':
	case '\n':
	dest = s;
	++s;
	++dest;
	break;

	default:
	/* not an escaped char */
	*dest = '\\';
	++dest;
	/* ++s already done. */
	break;
	}
	break;

	default:
	dest = s;
	++dest;
	++s;
	break;
	}

	g_assert(s > dest); /* loop invariant */
	}
	}
	else
	{
	while (*s)
	{
	g_assert(s > dest); /* loop invariant */

	if (*s == '\'')
	{
	/* End of the string, return now */
	*dest = '\0';
	++s;
	*end = s;
	return TRUE;
	}
	else
	{
	dest = s;
	++dest;
	++s;
	}

	g_assert(s > dest); /* loop invariant */
	}
	}

	/* If we reach here this means the close quote was never encountered */

	*dest = '\0';

	g_set_error_literal (err,
	G_SHELL_ERROR,
	G_SHELL_ERROR_BAD_QUOTING,
	_("Unmatched quotation mark in command line or other shell-quoted text"));
	*end = s;
	return FALSE;
	}

	/**
	* g_shell_quote:
	* @unquoted_string: (type filename): a literal string
	*
	* Quotes a string so that the shell (/bin/sh) will interpret the
	* quoted string to mean @unquoted_string. If you pass a filename to
	* the shell, for example, you should first quote it with this
	* function. The return value must be freed with g_free(). The
	* quoting style used is undefined (single or double quotes may be
	* used).
	*
	* Returns: (type filename): quoted string
	**/
	gchar*
	g_shell_quote (const gchar *unquoted_string)
	{
	/* We always use single quotes, because the algorithm is cheesier.
	* We could use double if we felt like it, that might be more
	* human-readable.
	*/

	const gchar *p;
	GString *dest;

	g_return_val_if_fail (unquoted_string != NULL, NULL);

	dest = g_string_new ("'");

	p = unquoted_string;

	/* could speed this up a lot by appending chunks of text at a
	* time.
	*/
	while (*p)
	{
	/* Replace literal ' with a close ', a \', and a open ' */
	if (*p == '\'')
	g_string_append (dest, "'\\''");
	else
	g_string_append_c (dest, *p);

	++p;
	}

	/* close the quote */
	g_string_append_c (dest, '\'');

	return g_string_free (dest, FALSE);
	}

	/**
	* g_shell_unquote:
	* @quoted_string: (type filename): shell-quoted string
	* @error: error return location or NULL
	*
	* Unquotes a string as the shell (/bin/sh) would. Only handles
	* quotes; if a string contains file globs, arithmetic operators,
	* variables, backticks, redirections, or other special-to-the-shell
	* features, the result will be different from the result a real shell
	* would produce (the variables, backticks, etc. will be passed
	* through literally instead of being expanded). This function is
	* guaranteed to succeed if applied to the result of
	* g_shell_quote(). If it fails, it returns %NULL and sets the
	* error. The @quoted_string need not actually contain quoted or
	* escaped text; g_shell_unquote() simply goes through the string and
	* unquotes/unescapes anything that the shell would. Both single and
	* double quotes are handled, as are escapes including escaped
	* newlines. The return value must be freed with g_free(). Possible
	* errors are in the #G_SHELL_ERROR domain.
	*
	* Shell quoting rules are a bit strange. Single quotes preserve the
	* literal string exactly. escape sequences are not allowed; not even
	* \' - if you want a ' in the quoted text, you have to do something
	* like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to
	* be escaped with backslash. Otherwise double quotes preserve things
	* literally.
	*
	* Returns: (type filename): an unquoted string
	**/
	gchar*
	g_shell_unquote (const gchar *quoted_string,
	GError **error)
	{
	gchar *unquoted;
	gchar *end;
	gchar *start;
	GString *retval;

	g_return_val_if_fail (quoted_string != NULL, NULL);

	unquoted = g_strdup (quoted_string);

	start = unquoted;
	end = unquoted;
	retval = g_string_new (NULL);

	/* The loop allows cases such as
	* "foo"blah blah'bar'woo foo"baz"la la la\'\''foo'
	*/
	while (*start)
	{
	/* Append all non-quoted chars, honoring backslash escape
	*/

	while (start && !(start == '"' \|\| *start == '\''))
	{
	if (*start == '\\')
	{
	/* all characters can get escaped by backslash,
	* except newline, which is removed if it follows
	* a backslash outside of quotes
	*/

	++start;
	if (*start)
	{
	if (*start != '\n')
	g_string_append_c (retval, *start);
	++start;
	}
	}
	else
	{
	g_string_append_c (retval, *start);
	++start;
	}
	}

	if (*start)
	{
	if (!unquote_string_inplace (start, &end, error))
	{
	goto error;
	}
	else
	{
	g_string_append (retval, start);
	start = end;
	}
	}
	}

	g_free (unquoted);
	return g_string_free (retval, FALSE);

	error:
	g_assert (error == NULL \|\| *error != NULL);

	g_free (unquoted);
	g_string_free (retval, TRUE);
	return NULL;
	}

	/* g_parse_argv() does a semi-arbitrary weird subset of the way
	* the shell parses a command line. We don't do variable expansion,
	* don't understand that operators are tokens, don't do tilde expansion,
	* don't do command substitution, no arithmetic expansion, IFS gets ignored,
	* don't do filename globs, don't remove redirection stuff, etc.
	*
	* READ THE UNIX98 SPEC on "Shell Command Language" before changing
	* the behavior of this code.
	*
	* Steps to parsing the argv string:
	*
	* - tokenize the string (but since we ignore operators,
	* our tokenization may diverge from what the shell would do)
	* note that tokenization ignores the internals of a quoted
	* word and it always splits on spaces, not on IFS even
	* if we used IFS. We also ignore "end of input indicator"
	* (I guess this is control-D?)
	*
	* Tokenization steps, from UNIX98 with operator stuff removed,
	* are:
	*
	* 1) "If the current character is backslash, single-quote or
	* double-quote (\, ' or ") and it is not quoted, it will affect
	* quoting for subsequent characters up to the end of the quoted
	* text. The rules for quoting are as described in Quoting
	* . During token recognition no substitutions will be actually
	* performed, and the result token will contain exactly the
	* characters that appear in the input (except for newline
	* character joining), unmodified, including any embedded or
	* enclosing quotes or substitution operators, between the quote
	* mark and the end of the quoted text. The token will not be
	* delimited by the end of the quoted field."
	*
	* 2) "If the current character is an unquoted newline character,
	* the current token will be delimited."
	*
	* 3) "If the current character is an unquoted blank character, any
	* token containing the previous character is delimited and the
	* current character will be discarded."
	*
	* 4) "If the previous character was part of a word, the current
	* character will be appended to that word."
	*
	* 5) "If the current character is a "#", it and all subsequent
	* characters up to, but excluding, the next newline character
	* will be discarded as a comment. The newline character that
	* ends the line is not considered part of the comment. The
	* "#" starts a comment only when it is at the beginning of a
	* token. Since the search for the end-of-comment does not
	* consider an escaped newline character specially, a comment
	* cannot be continued to the next line."
	*
	* 6) "The current character will be used as the start of a new word."
	*
	*
	* - for each token (word), perform portions of word expansion, namely
	* field splitting (using default whitespace IFS) and quote
	* removal. Field splitting may increase the number of words.
	* Quote removal does not increase the number of words.
	*
	* "If the complete expansion appropriate for a word results in an
	* empty field, that empty field will be deleted from the list of
	* fields that form the completely expanded command, unless the
	* original word contained single-quote or double-quote characters."
	* - UNIX98 spec
	*
	*
	*/

	static inline void
	ensure_token (GString **token)
	{
	if (*token == NULL)
	*token = g_string_new (NULL);
	}

	static void
	delimit_token (GString **token,
	GSList **retval)
	{
	if (*token == NULL)
	return;

	retval = g_slist_prepend (retval, g_string_free (*token, FALSE));

	*token = NULL;
	}

	static GSList*
	tokenize_command_line (const gchar *command_line,
	GError **error)
	{
	gchar current_quote;
	const gchar *p;
	GString *current_token = NULL;
	GSList *retval = NULL;
	gboolean quoted;

	current_quote = '\0';
	quoted = FALSE;
	p = command_line;

	while (*p)
	{
	if (current_quote == '\\')
	{
	if (*p == '\n')
	{
	/* we append nothing; backslash-newline become nothing */
	}
	else
	{
	/* we append the backslash and the current char,
	* to be interpreted later after tokenization
	*/
	ensure_token (&current_token);
	g_string_append_c (current_token, '\\');
	g_string_append_c (current_token, *p);
	}

	current_quote = '\0';
	}
	else if (current_quote == '#')
	{
	/* Discard up to and including next newline */
	while (p && p != '\n')
	++p;

	current_quote = '\0';

	if (*p == '\0')
	break;
	}
	else if (current_quote)
	{
	if (*p == current_quote &&
	/* check that it isn't an escaped double quote */
	!(current_quote == '"' && quoted))
	{
	/* close the quote */
	current_quote = '\0';
	}

	/* Everything inside quotes, and the close quote,
	* gets appended literally.
	*/

	ensure_token (&current_token);
	g_string_append_c (current_token, *p);
	}
	else
	{
	switch (*p)
	{
	case '\n':
	delimit_token (&current_token, &retval);
	break;

	case ' ':
	case '\t':
	/* If the current token contains the previous char, delimit
	* the current token. A nonzero length
	* token should always contain the previous char.
	*/
	if (current_token &&
	current_token->len > 0)
	{
	delimit_token (&current_token, &retval);
	}

	/* discard all unquoted blanks (don't add them to a token) */
	break;


	/* single/double quotes are appended to the token,
	* escapes are maybe appended next time through the loop,
	* comment chars are never appended.
	*/

	case '\'':
	case '"':
	ensure_token (&current_token);
	g_string_append_c (current_token, *p);

	/* FALL THRU */
	case '\\':
	current_quote = *p;
	break;

	case '#':
	if (p == command_line)
	{ /* '#' was the first char */
	current_quote = *p;
	break;
	}
	switch(*(p-1))
	{
	case ' ':
	case '\n':
	case '\0':
	current_quote = *p;
	break;
	default:
	ensure_token (&current_token);
	g_string_append_c (current_token, *p);
	break;
	}
	break;

	default:
	/* Combines rules 4) and 6) - if we have a token, append to it,
	* otherwise create a new token.
	*/
	ensure_token (&current_token);
	g_string_append_c (current_token, *p);
	break;
	}
	}

	/* We need to count consecutive backslashes mod 2,
	* to detect escaped doublequotes.
	*/
	if (*p != '\\')
	quoted = FALSE;
	else
	quoted = !quoted;

	++p;
	}

	delimit_token (&current_token, &retval);

	if (current_quote)
	{
	if (current_quote == '\\')
	g_set_error (error,
	G_SHELL_ERROR,
	G_SHELL_ERROR_BAD_QUOTING,
	_("Text ended just after a “\\” character."
	" (The text was “%s”)"),
	command_line);
	else
	g_set_error (error,
	G_SHELL_ERROR,
	G_SHELL_ERROR_BAD_QUOTING,
	_("Text ended before matching quote was found for %c."
	" (The text was “%s”)"),
	current_quote, command_line);

	goto error;
	}

	if (retval == NULL)
	{
	g_set_error_literal (error,
	G_SHELL_ERROR,
	G_SHELL_ERROR_EMPTY_STRING,
	_("Text was empty (or contained only whitespace)"));

	goto error;
	}

	/* we appended backward */
	retval = g_slist_reverse (retval);

	return retval;

	error:
	g_assert (error == NULL \|\| *error != NULL);

	g_slist_free_full (retval, g_free);

	return NULL;
	}

	/**
	* g_shell_parse_argv:
	* @command_line: (type filename): command line to parse
	* @argcp: (out) (optional): return location for number of args
	* @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
	* return location for array of args
	* @error: (optional): return location for error
	*
	* Parses a command line into an argument vector, in much the same way
	* the shell would, but without many of the expansions the shell would
	* perform (variable expansion, globs, operators, filename expansion,
	* etc. are not supported). The results are defined to be the same as
	* those you would get from a UNIX98 /bin/sh, as long as the input
	* contains none of the unsupported shell expansions. If the input
	* does contain such expansions, they are passed through
	* literally. Possible errors are those from the #G_SHELL_ERROR
	* domain. Free the returned vector with g_strfreev().
	*
	* Returns: %TRUE on success, %FALSE if error set
	**/
	gboolean
	g_shell_parse_argv (const gchar *command_line,
	gint *argcp,
	gchar ***argvp,
	GError **error)
	{
	/* Code based on poptParseArgvString() from libpopt */
	gint argc = 0;
	gchar **argv = NULL;
	GSList *tokens = NULL;
	gint i;
	GSList *tmp_list;

	g_return_val_if_fail (command_line != NULL, FALSE);

	tokens = tokenize_command_line (command_line, error);
	if (tokens == NULL)
	return FALSE;

	/* Because we can't have introduced any new blank space into the
	* tokens (we didn't do any new expansions), we don't need to
	* perform field splitting. If we were going to honor IFS or do any
	* expansions, we would have to do field splitting on each word
	* here. Also, if we were going to do any expansion we would need to
	* remove any zero-length words that didn't contain quotes
	* originally; but since there's no expansion we know all words have
	* nonzero length, unless they contain quotes.
	*
	* So, we simply remove quotes, and don't do any field splitting or
	* empty word removal, since we know there was no way to introduce
	* such things.
	*/

	argc = g_slist_length (tokens);
	argv = g_new0 (gchar*, argc + 1);
	i = 0;
	tmp_list = tokens;
	while (tmp_list)
	{
	argv[i] = g_shell_unquote (tmp_list->data, error);

	/* Since we already checked that quotes matched up in the
	* tokenizer, this shouldn't be possible to reach I guess.
	*/
	if (argv[i] == NULL)
	goto failed;

	tmp_list = g_slist_next (tmp_list);
	++i;
	}

	g_slist_free_full (tokens, g_free);

	if (argcp)
	*argcp = argc;

	if (argvp)
	*argvp = argv;
	else
	g_strfreev (argv);

	return TRUE;

	failed:

	g_assert (error == NULL \|\| *error != NULL);
	g_strfreev (argv);
	g_slist_free_full (tokens, g_free);

	return FALSE;
	}