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