docs/reference/glib/html/glib-Shell-related-Utilities.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Shell-related Utilities</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-Hostname-Utilities.html" title="Hostname Utilities">
  10 <link rel="next" href="glib-Commandline-option-parser.html" title="Commandline option parser">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Hostname-Utilities.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Commandline-option-parser.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Shell-related-Utilities.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Shell-related-Utilities.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Shell-related-Utilities"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Shell-related-Utilities.top_of_page"></a>Shell-related Utilities</span></h2>
  34 <p>Shell-related Utilities — shell-like commandline handling</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Shell-related-Utilities.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43 enum                <a class="link" href="glib-Shell-related-Utilities.html#GShellError" title="enum GShellError">GShellError</a>;
  44 #define             <a class="link" href="glib-Shell-related-Utilities.html#G-SHELL-ERROR:CAPS" title="G_SHELL_ERROR">G_SHELL_ERROR</a>
  45 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Shell-related-Utilities.html#g-shell-parse-argv" title="g_shell_parse_argv ()">g_shell_parse_argv</a>                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *command_line</code></em>,
  46                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *argcp</code></em>,
  47                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> ***argvp</code></em>,
  48                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  49 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Shell-related-Utilities.html#g-shell-quote" title="g_shell_quote ()">g_shell_quote</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *unquoted_string</code></em>);
  50 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Shell-related-Utilities.html#g-shell-unquote" title="g_shell_unquote ()">g_shell_unquote</a>                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *quoted_string</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  52 </pre>
  53 </div>
  54 <div class="refsect1">
  55 <a name="glib-Shell-related-Utilities.description"></a><h2>Description</h2>
  56 </div>
  57 <div class="refsect1">
  58 <a name="glib-Shell-related-Utilities.details"></a><h2>Details</h2>
  59 <div class="refsect2">
  60 <a name="GShellError"></a><h3>enum GShellError</h3>
  61 <pre class="programlisting">typedef enum {
  62   /* mismatched or otherwise mangled quoting */
  63   G_SHELL_ERROR_BAD_QUOTING,
  64   /* string to be parsed was empty */
  65   G_SHELL_ERROR_EMPTY_STRING,
  66   G_SHELL_ERROR_FAILED
  67 } GShellError;
  68 </pre>
  69 <p>
  70 Error codes returned by shell functions.
  71 </p>
  72 <div class="variablelist"><table border="0">
  73 <col align="left" valign="top">
  74 <tbody>
  75 <tr>
  76 <td><p><a name="G-SHELL-ERROR-BAD-QUOTING:CAPS"></a><span class="term"><code class="literal">G_SHELL_ERROR_BAD_QUOTING</code></span></p></td>
  77 <td>Mismatched or otherwise mangled quoting.
  78 </td>
  79 </tr>
  80 <tr>
  81 <td><p><a name="G-SHELL-ERROR-EMPTY-STRING:CAPS"></a><span class="term"><code class="literal">G_SHELL_ERROR_EMPTY_STRING</code></span></p></td>
  82 <td>String to be parsed was empty.
  83 </td>
  84 </tr>
  85 <tr>
  86 <td><p><a name="G-SHELL-ERROR-FAILED:CAPS"></a><span class="term"><code class="literal">G_SHELL_ERROR_FAILED</code></span></p></td>
  87 <td>Some other error.
  88 </td>
  89 </tr>
  90 </tbody>
  91 </table></div>
  92 </div>
  93 <hr>
  94 <div class="refsect2">
  95 <a name="G-SHELL-ERROR:CAPS"></a><h3>G_SHELL_ERROR</h3>
  96 <pre class="programlisting">#define G_SHELL_ERROR g_shell_error_quark ()
  97 </pre>
  98 <p>
  99 Error domain for shell functions. Errors in this domain will be from
 100 the <a class="link" href="glib-Shell-related-Utilities.html#GShellError" title="enum GShellError"><span class="type">GShellError</span></a> enumeration. See <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> for information on error
 101 domains.
 102 </p>
 103 </div>
 104 <hr>
 105 <div class="refsect2">
 106 <a name="g-shell-parse-argv"></a><h3>g_shell_parse_argv ()</h3>
 107 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_shell_parse_argv                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *command_line</code></em>,
 108                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *argcp</code></em>,
 109                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> ***argvp</code></em>,
 110                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 111 <p>
 112 Parses a command line into an argument vector, in much the same way
 113 the shell would, but without many of the expansions the shell would
 114 perform (variable expansion, globs, operators, filename expansion,
 115 etc. are not supported). The results are defined to be the same as
 116 those you would get from a UNIX98 /bin/sh, as long as the input
 117 contains none of the unsupported shell expansions. If the input
 118 does contain such expansions, they are passed through
 119 literally. Possible errors are those from the <a class="link" href="glib-Shell-related-Utilities.html#G-SHELL-ERROR:CAPS" title="G_SHELL_ERROR"><span class="type">G_SHELL_ERROR</span></a>
 120 domain. Free the returned vector with <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>.
 121 </p>
 122 <div class="variablelist"><table border="0">
 123 <col align="left" valign="top">
 124 <tbody>
 125 <tr>
 126 <td><p><span class="term"><em class="parameter"><code>command_line</code></em> :</span></p></td>
 127 <td>command line to parse</td>
 128 </tr>
 129 <tr>
 130 <td><p><span class="term"><em class="parameter"><code>argcp</code></em> :</span></p></td>
 131 <td>return location for number of args. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span>
 132 </td>
 133 </tr>
 134 <tr>
 135 <td><p><span class="term"><em class="parameter"><code>argvp</code></em> :</span></p></td>
 136 <td>return location for array of args. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argcp zero-terminated=1]</span>
 137 </td>
 138 </tr>
 139 <tr>
 140 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 141 <td>return location for error</td>
 142 </tr>
 143 <tr>
 144 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 145 <td>
 146 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if error set</td>
 147 </tr>
 148 </tbody>
 149 </table></div>
 150 </div>
 151 <hr>
 152 <div class="refsect2">
 153 <a name="g-shell-quote"></a><h3>g_shell_quote ()</h3>
 154 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_shell_quote                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *unquoted_string</code></em>);</pre>
 155 <p>
 156 Quotes a string so that the shell (/bin/sh) will interpret the
 157 quoted string to mean <em class="parameter"><code>unquoted_string</code></em>. If you pass a filename to
 158 the shell, for example, you should first quote it with this
 159 function.  The return value must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>. The
 160 quoting style used is undefined (single or double quotes may be
 161 used).
 162 </p>
 163 <div class="variablelist"><table border="0">
 164 <col align="left" valign="top">
 165 <tbody>
 166 <tr>
 167 <td><p><span class="term"><em class="parameter"><code>unquoted_string</code></em> :</span></p></td>
 168 <td>a literal string</td>
 169 </tr>
 170 <tr>
 171 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 172 <td>quoted string</td>
 173 </tr>
 174 </tbody>
 175 </table></div>
 176 </div>
 177 <hr>
 178 <div class="refsect2">
 179 <a name="g-shell-unquote"></a><h3>g_shell_unquote ()</h3>
 180 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_shell_unquote                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *quoted_string</code></em>,
 181                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 182 <p>
 183 Unquotes a string as the shell (/bin/sh) would. Only handles
 184 quotes; if a string contains file globs, arithmetic operators,
 185 variables, backticks, redirections, or other special-to-the-shell
 186 features, the result will be different from the result a real shell
 187 would produce (the variables, backticks, etc. will be passed
 188 through literally instead of being expanded). This function is
 189 guaranteed to succeed if applied to the result of
 190 <a class="link" href="glib-Shell-related-Utilities.html#g-shell-quote" title="g_shell_quote ()"><code class="function">g_shell_quote()</code></a>. If it fails, it returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> and sets the
 191 error. The <em class="parameter"><code>quoted_string</code></em> need not actually contain quoted or
 192 escaped text; <a class="link" href="glib-Shell-related-Utilities.html#g-shell-unquote" title="g_shell_unquote ()"><code class="function">g_shell_unquote()</code></a> simply goes through the string and
 193 unquotes/unescapes anything that the shell would. Both single and
 194 double quotes are handled, as are escapes including escaped
 195 newlines. The return value must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>. Possible
 196 errors are in the <a class="link" href="glib-Shell-related-Utilities.html#G-SHELL-ERROR:CAPS" title="G_SHELL_ERROR"><span class="type">G_SHELL_ERROR</span></a> domain.
 197 </p>
 198 <p>
 199 Shell quoting rules are a bit strange. Single quotes preserve the
 200 literal string exactly. escape sequences are not allowed; not even
 201 \' - if you want a ' in the quoted text, you have to do something
 202 like 'foo'\''bar'.  Double quotes allow $, `, ", \, and newline to
 203 be escaped with backslash. Otherwise double quotes preserve things
 204 literally.
 205 </p>
 206 <div class="variablelist"><table border="0">
 207 <col align="left" valign="top">
 208 <tbody>
 209 <tr>
 210 <td><p><span class="term"><em class="parameter"><code>quoted_string</code></em> :</span></p></td>
 211 <td>shell-quoted string</td>
 212 </tr>
 213 <tr>
 214 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 215 <td>error return location or NULL</td>
 216 </tr>
 217 <tr>
 218 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 219 <td>an unquoted string</td>
 220 </tr>
 221 </tbody>
 222 </table></div>
 223 </div>
 224 </div>
 225 </div>
 226 <div class="footer">
 227 <hr>
 228           Generated by GTK-Doc V1.18</div>
 229 </body>
 230 </html>