glib-Shell-related-Utilities.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Shell-related Utilities</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-utilities.html" title="GLib Utilities"><link rel="previous" href="glib-File-Utilities.html" title="File Utilities"><link rel="next" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="refentry" href="glib-building.html" title="Compiling the GLib package"><link rel="refentry" href="glib-cross-compiling.html" title="Cross-compiling the GLib package"><link rel="refentry" href="glib-compiling.html" title="Compiling GLib Applications"><link rel="refentry" href="glib-running.html" title="Running GLib Applications"><link rel="refentry" href="glib-changes.html" title="Changes to GLib"><link rel="refentry" href="glib-resources.html" title="Mailing lists and bug reports"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="refentry" href="glib-Basic-Types.html" title="Basic Types"><link rel="refentry" href="glib-Limits-of-Basic-Types.html" title="Limits of Basic Types"><link rel="refentry" href="glib-Standard-Macros.html" title="Standard Macros"><link rel="refentry" href="glib-Type-Conversion-Macros.html" title="Type Conversion Macros"><link rel="refentry" href="glib-Byte-Order-Macros.html" title="Byte Order Macros"><link rel="refentry" href="glib-Numerical-Definitions.html" title="Numerical Definitions"><link rel="refentry" href="glib-Miscellaneous-Macros.html" title="Miscellaneous Macros"><link rel="refentry" href="glib-Atomic-Operations.html" title="Atomic Operations"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="refentry" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop"><link rel="refentry" href="glib-Threads.html" title="
Threads"><link rel="refentry" href="glib-Thread-Pools.html" title="Thread Pools"><link rel="refentry" href="glib-Asynchronous-Queues.html" title="Asynchronous Queues"><link rel="refentry" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules"><link rel="refentry" href="glib-Memory-Allocation.html" title="Memory Allocation"><link rel="refentry" href="glib-IO-Channels.html" title="IO Channels"><link rel="refentry" href="glib-Error-Reporting.html" title="Error Reporting"><link rel="refentry" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions"><link rel="refentry" href="glib-Message-Logging.html" title="Message Logging"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="refentry" href="glib-String-Utility-Functions.html" title="String Utility Functions"><link rel="refentry" href="glib-Character-Set-Conversion.html" title="Character Set Conversion"><link rel="refentry" href="glib-Unicode-Manipulation.html" title="Unicode Manipulation"><link rel="refentry" href="glib-I18N.html" title="Internationalization"><link rel="refentry" href="glib-Date-and-Time-Functions.html" title="Date and Time Functions"><link rel="refentry" href="glib-Random-Numbers.html" title="Random Numbers"><link rel="refentry" href="glib-Hook-Functions.html" title="Hook Functions"><link rel="refentry" href="glib-Miscellaneous-Utility-Functions.html" title="Miscellaneous Utility Functions"><link rel="refentry" href="glib-Lexical-Scanner.html" title="Lexical Scanner"><link rel="refentry" href="glib-Automatic-String-Completion.html" title="Automatic String Completion"><link rel="refentry" href="glib-Timers.html" title="Timers"><link rel="refentry" href="glib-Spawning-Processes.html" title="Spawning Processes"><link rel="refentry" href="glib-File-Utilities.html" title="File Utilities"><link rel="refentry" href="glib-Shell-related-Utilities.html" title="Shell-related Utilities"><link rel="refentry" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching"><link rel="refentry" href="glib-Simple-XML-Subset-Parser.html" title="Simple XML Subset Parser"><link rel="refentry" href="glib-Windows-Compatability-Functions.html" title="Windows Compatibility Functions"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="refentry" href="glib-Memory-Chunks.html" title="Memory Chunks"><link rel="refentry" href="glib-Doubly-Linked-Lists.html" title="Doubly-Linked Lists"><link rel="refentry" href="glib-Singly-Linked-Lists.html" title="Singly-Linked Lists"><link rel="refentry" href="glib-Double-ended-Queues.html" title="Double-ended Queues"><link rel="refentry" href="glib-Trash-Stacks.html" title="Trash Stacks"><link rel="refentry" href="glib-Hash-Tables.html" title="Hash Tables"><link rel="refentry" href="glib-Strings.html" title="Strings"><link rel="refentry" href="glib-String-Chunks.html" title="String Chunks"><link rel="refentry" href="glib-Arrays.html" title="Arrays"><link rel="refentry" href="glib-Pointer-Arrays.html" title="Pointer Arrays"><link rel="refentry" href="glib-Byte-Arrays.html" title="Byte Arrays"><link rel="refentry" href="glib-Balanced-Binary-Trees.html" title="Balanced Binary Trees"><link rel="refentry" href="glib-N-ary-Trees.html" title="N-ary Trees"><link rel="refentry" href="glib-Quarks.html" title="Quarks"><link rel="refentry" href="glib-Keyed-Data-Lists.html" title="Keyed Data Lists"><link rel="refentry" href="glib-Datasets.html" title="Datasets"><link rel="refentry" href="glib-Relations-and-Tuples.html" title="Relations and Tuples"><link rel="refentry" href="glib-Caches.html" title="Caches"><link rel="refentry" href="glib-Memory-Allocators.html" title="Memory Allocators"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="refentry" href="glib-gettextize.html" title="glib-gettextize"><link rel="index" href="ix01.html" title="Index"><link rel="section" href="glib-Shell-related-Utilities.html#id3219015" title="Description"><link rel="section" href="glib-Shell-related-Utilities.html#id3219025" title="Details"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-File-Utilities.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-Glob-style-pattern-matching.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Shell-related-Utilities"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Shell-related Utilities</span></h2><p>Shell-related Utilities — shell-like commandline handling.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
#include <glib.h>
enum <a href="glib-Shell-related-Utilities.html#GShellError">GShellError</a>;
#define <a href="glib-Shell-related-Utilities.html#G-SHELL-ERROR-CAPS">G_SHELL_ERROR</a>
<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Shell-related-Utilities.html#g-shell-parse-argv">g_shell_parse_argv</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *command_line,
<a href="glib-Basic-Types.html#gint">gint</a> *argcp,
<a href="glib-Basic-Types.html#gchar">gchar</a> ***argvp,
<a href="glib-Error-Reporting.html#GError">GError</a> **error);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Shell-related-Utilities.html#g-shell-quote">g_shell_quote</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *unquoted_string);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Shell-related-Utilities.html#g-shell-unquote">g_shell_unquote</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *quoted_string,
<a href="glib-Error-Reporting.html#GError">GError</a> **error);
</pre></div><div class="refsect1" lang="en"><a name="id3219015"></a><h2>Description</h2><p>
</p></div><div class="refsect1" lang="en"><a name="id3219025"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id3219031"></a><h3><a name="GShellError"></a>enum GShellError</h3><a class="indexterm" name="id3219042"></a><pre class="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;
</pre><p>
Error codes returned by shell functions.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><tt class="literal">G_SHELL_ERROR_BAD_QUOTING</tt></span></td><td>Mismatched or otherwise mangled quoting.
</td></tr><tr><td><span class="term"><tt class="literal">G_SHELL_ERROR_EMPTY_STRING</tt></span></td><td>String to be parsed was empty.
</td></tr><tr><td><span class="term"><tt class="literal">G_SHELL_ERROR_FAILED</tt></span></td><td>Some other error.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3219110"></a><h3><a name="G-SHELL-ERROR-CAPS"></a>G_SHELL_ERROR</h3><a class="indexterm" name="id3219121"></a><pre class="programlisting">#define G_SHELL_ERROR g_shell_error_quark ()
</pre><p>
Error domain for shell functions. Errors in this domain will
be from the <a href="glib-Shell-related-Utilities.html#GShellError"><span class="type">GShellError</span></a> enumeration. See <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> for information on
error domains.
</p></div><hr><div class="refsect2" lang="en"><a name="id3219155"></a><h3><a name="g-shell-parse-argv"></a>g_shell_parse_argv ()</h3><a class="indexterm" name="id3219166"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a> g_shell_parse_argv (const <a href="glib-Basic-Types.html#gchar">gchar</a> *command_line,
<a href="glib-Basic-Types.html#gint">gint</a> *argcp,
<a href="glib-Basic-Types.html#gchar">gchar</a> ***argvp,
<a href="glib-Error-Reporting.html#GError">GError</a> **error);</pre><p>
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 <a href="glib-Shell-related-Utilities.html#G-SHELL-ERROR-CAPS"><span class="type">G_SHELL_ERROR</span></a>
domain. Free the returned vector with <a href="glib-String-Utility-Functions.html#g-strfreev"><tt class="function">g_strfreev()</tt></a>.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>command_line</tt></i> :</span></td><td> command line to parse
</td></tr><tr><td><span class="term"><i class="parameter"><tt>argcp</tt></i> :</span></td><td> return location for number of args
</td></tr><tr><td><span class="term"><i class="parameter"><tt>argvp</tt></i> :</span></td><td> return location for array of args
</td></tr><tr><td><span class="term"><i class="parameter"><tt>error</tt></i> :</span></td><td> return location for error
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> <tt class="literal">TRUE</tt> on success, <tt class="literal">FALSE</tt> if error set
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3219339"></a><h3><a name="g-shell-quote"></a>g_shell_quote ()</h3><a class="indexterm" name="id3219350"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_shell_quote (const <a href="glib-Basic-Types.html#gchar">gchar</a> *unquoted_string);</pre><p>
Quotes a string so that the shell (/bin/sh) will interpret the
quoted string to mean <i class="parameter"><tt>unquoted_string</tt></i>. 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 <a href="glib-Memory-Allocation.html#g-free"><tt class="function">g_free()</tt></a>. The
quoting style used is undefined (single or double quotes may be
used).</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>unquoted_string</tt></i> :</span></td><td> a literal string
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> quoted string
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3219432"></a><h3><a name="g-shell-unquote"></a>g_shell_unquote ()</h3><a class="indexterm" name="id3219443"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_shell_unquote (const <a href="glib-Basic-Types.html#gchar">gchar</a> *quoted_string,
<a href="glib-Error-Reporting.html#GError">GError</a> **error);</pre><p>
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
<a href="glib-Shell-related-Utilities.html#g-shell-quote"><tt class="function">g_shell_quote()</tt></a>. If it fails, it returns <tt class="literal">NULL</tt> and sets the
error. The <i class="parameter"><tt>quoted_string</tt></i> need not actually contain quoted or
escaped text; <a href="glib-Shell-related-Utilities.html#g-shell-unquote"><tt class="function">g_shell_unquote()</tt></a> 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 <a href="glib-Memory-Allocation.html#g-free"><tt class="function">g_free()</tt></a>. Possible
errors are in the <a href="glib-Shell-related-Utilities.html#G-SHELL-ERROR-CAPS"><span class="type">G_SHELL_ERROR</span></a> domain.
</p><p>
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.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>quoted_string</tt></i> :</span></td><td> shell-quoted string
</td></tr><tr><td><span class="term"><i class="parameter"><tt>error</tt></i> :</span></td><td> error return location or NULL
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> an unquoted string
</td></tr></tbody></table></div></div></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="glib-File-Utilities.html"><b><< File Utilities</b></a></td><td align="right"><a accesskey="n" href="glib-Glob-style-pattern-matching.html"><b>Glob-style pattern matching >></b></a></td></tr></table></body></html>