<refentry id="glib-Shell-related-Utilities"> <refmeta> <refentrytitle>Shell-related Utilities</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>GLIB Library</refmiscinfo> </refmeta> <refnamediv> <refname>Shell-related Utilities</refname><refpurpose>shell-like commandline handling.</refpurpose> </refnamediv> <refsynopsisdiv><title>Synopsis</title> <synopsis> #include <glib.h> enum <link linkend="GShellError">GShellError</link>; #define <link linkend="G-SHELL-ERROR-CAPS">G_SHELL_ERROR</link> <link linkend="gboolean">gboolean</link> <link linkend="g-shell-parse-argv">g_shell_parse_argv</link> (const <link linkend="gchar">gchar</link> *command_line, <link linkend="gint">gint</link> *argcp, <link linkend="gchar">gchar</link> ***argvp, <link linkend="GError">GError</link> **error); <link linkend="gchar">gchar</link>* <link linkend="g-shell-quote">g_shell_quote</link> (const <link linkend="gchar">gchar</link> *unquoted_string); <link linkend="gchar">gchar</link>* <link linkend="g-shell-unquote">g_shell_unquote</link> (const <link linkend="gchar">gchar</link> *quoted_string, <link linkend="GError">GError</link> **error); </synopsis> </refsynopsisdiv> <refsect1> <title>Description</title> <para> </para> </refsect1> <refsect1> <title>Details</title> <refsect2> <title><anchor id="GShellError"/>enum GShellError</title> <indexterm><primary>GShellError</primary></indexterm><programlisting>typedef enum { /* mismatched or otherwise mangled quoting */ G_SHELL_ERROR_BAD_QUOTING, /* string to be parsed was empty */ G_SHELL_ERROR_EMPTY_STRING, G_SHELL_ERROR_FAILED } GShellError; </programlisting> <para> Error codes returned by shell functions. </para><variablelist role="enum"> <varlistentry> <term><literal>G_SHELL_ERROR_BAD_QUOTING</literal></term> <listitem><simpara>Mismatched or otherwise mangled quoting. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_SHELL_ERROR_EMPTY_STRING</literal></term> <listitem><simpara>String to be parsed was empty. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_SHELL_ERROR_FAILED</literal></term> <listitem><simpara>Some other error. </simpara></listitem> </varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="G-SHELL-ERROR-CAPS"/>G_SHELL_ERROR</title> <indexterm><primary>G_SHELL_ERROR</primary></indexterm><programlisting>#define G_SHELL_ERROR g_shell_error_quark () </programlisting> <para> Error domain for shell functions. Errors in this domain will be from the <link linkend="GShellError"><type>GShellError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on error domains. </para></refsect2> <refsect2> <title><anchor id="g-shell-parse-argv"/>g_shell_parse_argv ()</title> <indexterm><primary>g_shell_parse_argv</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_shell_parse_argv (const <link linkend="gchar">gchar</link> *command_line, <link linkend="gint">gint</link> *argcp, <link linkend="gchar">gchar</link> ***argvp, <link linkend="GError">GError</link> **error);</programlisting> <para> 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 <link linkend="G-SHELL-ERROR-CAPS"><type>G_SHELL_ERROR</type></link> domain. Free the returned vector with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>command_line</parameter> :</term> <listitem><simpara> command line to parse </simpara></listitem></varlistentry> <varlistentry><term><parameter>argcp</parameter> :</term> <listitem><simpara> return location for number of args </simpara></listitem></varlistentry> <varlistentry><term><parameter>argvp</parameter> :</term> <listitem><simpara> return location for array of args </simpara></listitem></varlistentry> <varlistentry><term><parameter>error</parameter> :</term> <listitem><simpara> return location for error </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> on success, <literal>FALSE</literal> if error set </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-shell-quote"/>g_shell_quote ()</title> <indexterm><primary>g_shell_quote</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_shell_quote (const <link linkend="gchar">gchar</link> *unquoted_string);</programlisting> <para> Quotes a string so that the shell (/bin/sh) will interpret the quoted string to mean <parameter>unquoted_string</parameter>. 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 <link linkend="g-free"><function>g_free()</function></link>. The quoting style used is undefined (single or double quotes may be used).</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>unquoted_string</parameter> :</term> <listitem><simpara> a literal string </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> quoted string </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-shell-unquote"/>g_shell_unquote ()</title> <indexterm><primary>g_shell_unquote</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_shell_unquote (const <link linkend="gchar">gchar</link> *quoted_string, <link linkend="GError">GError</link> **error);</programlisting> <para> 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 <link linkend="g-shell-quote"><function>g_shell_quote()</function></link>. If it fails, it returns <literal>NULL</literal> and sets the error. The <parameter>quoted_string</parameter> need not actually contain quoted or escaped text; <link linkend="g-shell-unquote"><function>g_shell_unquote()</function></link> 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 <link linkend="g-free"><function>g_free()</function></link>. Possible errors are in the <link linkend="G-SHELL-ERROR-CAPS"><type>G_SHELL_ERROR</type></link> domain. </para> <para> 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.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>quoted_string</parameter> :</term> <listitem><simpara> shell-quoted string </simpara></listitem></varlistentry> <varlistentry><term><parameter>error</parameter> :</term> <listitem><simpara> error return location or NULL </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an unquoted string </simpara></listitem></varlistentry> </variablelist></refsect2> </refsect1> </refentry>