9
9
<refname>Shell-related Utilities</refname>
10
10
<refpurpose>shell-like commandline handling</refpurpose>
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
14
<refsynopsisdiv role="synopsis">
13
<refsynopsisdiv id="glib-Shell-related-Utilities.synopsis" role="synopsis">
15
14
<title role="synopsis.title">Synopsis</title>
19
18
#include <glib.h>
22
20
enum <link linkend="GShellError">GShellError</link>;
23
#define <link linkend="G-SHELL-ERROR:CAPS">G_SHELL_ERROR</link>
21
#define <link linkend="G-SHELL-ERROR--CAPS">G_SHELL_ERROR</link>
24
22
<link linkend="gboolean">gboolean</link> <link linkend="g-shell-parse-argv">g_shell_parse_argv</link> (const <link linkend="gchar">gchar</link> *command_line,
25
23
<link linkend="gint">gint</link> *argcp,
26
24
<link linkend="gchar">gchar</link> ***argvp,
43
<refsect1 role="desc">
40
<refsect1 id="glib-Shell-related-Utilities.description" role="desc">
44
41
<title role="desc.title">Description</title>
50
<refsect1 role="details">
46
<refsect1 id="glib-Shell-related-Utilities.details" role="details">
51
47
<title role="details.title">Details</title>
53
<title><anchor id="GShellError" role="enum"/>enum GShellError</title>
54
<indexterm><primary>GShellError</primary></indexterm><programlisting>typedef enum
48
<refsect2 id="GShellError" role="enum">
49
<title>enum GShellError</title>
50
<indexterm zone="GShellError"><primary sortas="GShellError">GShellError</primary></indexterm><programlisting>typedef enum
56
52
/* mismatched or otherwise mangled quoting */
57
53
G_SHELL_ERROR_BAD_QUOTING,
64
60
Error codes returned by shell functions.
65
61
</para><variablelist role="enum">
67
<term><anchor id="G-SHELL-ERROR-BAD-QUOTING:CAPS" role="constant"/><literal>G_SHELL_ERROR_BAD_QUOTING</literal></term>
62
<varlistentry id="G-SHELL-ERROR-BAD-QUOTING--CAPS" role="constant">
63
<term><literal>G_SHELL_ERROR_BAD_QUOTING</literal></term>
68
64
<listitem><simpara>Mismatched or otherwise mangled quoting.
69
65
</simpara></listitem>
72
<term><anchor id="G-SHELL-ERROR-EMPTY-STRING:CAPS" role="constant"/><literal>G_SHELL_ERROR_EMPTY_STRING</literal></term>
67
<varlistentry id="G-SHELL-ERROR-EMPTY-STRING--CAPS" role="constant">
68
<term><literal>G_SHELL_ERROR_EMPTY_STRING</literal></term>
73
69
<listitem><simpara>String to be parsed was empty.
74
70
</simpara></listitem>
77
<term><anchor id="G-SHELL-ERROR-FAILED:CAPS" role="constant"/><literal>G_SHELL_ERROR_FAILED</literal></term>
72
<varlistentry id="G-SHELL-ERROR-FAILED--CAPS" role="constant">
73
<term><literal>G_SHELL_ERROR_FAILED</literal></term>
78
74
<listitem><simpara>Some other error.
80
75
</simpara></listitem>
82
77
</variablelist></refsect2>
84
<title><anchor id="G-SHELL-ERROR:CAPS" role="macro"/>G_SHELL_ERROR</title>
85
<indexterm><primary>G_SHELL_ERROR</primary></indexterm><programlisting>#define G_SHELL_ERROR g_shell_error_quark ()
78
<refsect2 id="G-SHELL-ERROR--CAPS" role="macro">
79
<title>G_SHELL_ERROR</title>
80
<indexterm zone="G-SHELL-ERROR--CAPS"><primary sortas="G_SHELL_ERROR">G_SHELL_ERROR</primary></indexterm><programlisting>#define G_SHELL_ERROR g_shell_error_quark ()
88
83
Error domain for shell functions. Errors in this domain will
89
84
be from the <link linkend="GShellError"><type>GShellError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
93
<title><anchor id="g-shell-parse-argv" role="function"/>g_shell_parse_argv ()</title>
94
<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,
87
<refsect2 id="g-shell-parse-argv" role="function">
88
<title>g_shell_parse_argv ()</title>
89
<indexterm zone="g-shell-parse-argv"><primary sortas="g_shell_parse_argv">g_shell_parse_argv</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_shell_parse_argv (const <link linkend="gchar">gchar</link> *command_line,
95
90
<link linkend="gint">gint</link> *argcp,
96
91
<link linkend="gchar">gchar</link> ***argvp,
97
92
<link linkend="GError">GError</link> **error);</programlisting>
103
98
those you would get from a UNIX98 /bin/sh, as long as the input
104
99
contains none of the unsupported shell expansions. If the input
105
100
does contain such expansions, they are passed through
106
literally. Possible errors are those from the <link linkend="G-SHELL-ERROR:CAPS"><type>G_SHELL_ERROR</type></link>
101
literally. Possible errors are those from the <link linkend="G-SHELL-ERROR--CAPS"><type>G_SHELL_ERROR</type></link>
107
102
domain. Free the returned vector with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.</para>
110
104
</para><variablelist role="params">
111
<varlistentry><term><parameter>command_line</parameter> :</term>
105
<varlistentry><term><parameter>command_line</parameter> :</term>
112
106
<listitem><simpara> command line to parse
113
107
</simpara></listitem></varlistentry>
114
<varlistentry><term><parameter>argcp</parameter> :</term>
108
<varlistentry><term><parameter>argcp</parameter> :</term>
115
109
<listitem><simpara> return location for number of args
116
110
</simpara></listitem></varlistentry>
117
<varlistentry><term><parameter>argvp</parameter> :</term>
111
<varlistentry><term><parameter>argvp</parameter> :</term>
118
112
<listitem><simpara> return location for array of args
119
113
</simpara></listitem></varlistentry>
120
<varlistentry><term><parameter>error</parameter> :</term>
114
<varlistentry><term><parameter>error</parameter> :</term>
121
115
<listitem><simpara> return location for error
122
116
</simpara></listitem></varlistentry>
123
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if error set
117
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if error set
124
118
</simpara></listitem></varlistentry>
125
119
</variablelist></refsect2>
127
<title><anchor id="g-shell-quote" role="function"/>g_shell_quote ()</title>
128
<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>
120
<refsect2 id="g-shell-quote" role="function">
121
<title>g_shell_quote ()</title>
122
<indexterm zone="g-shell-quote"><primary sortas="g_shell_quote">g_shell_quote</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_shell_quote (const <link linkend="gchar">gchar</link> *unquoted_string);</programlisting>
130
124
Quotes a string so that the shell (/bin/sh) will interpret the
131
125
quoted string to mean <parameter>unquoted_string</parameter>. If you pass a filename to
134
128
quoting style used is undefined (single or double quotes may be
138
131
</para><variablelist role="params">
139
<varlistentry><term><parameter>unquoted_string</parameter> :</term>
132
<varlistentry><term><parameter>unquoted_string</parameter> :</term>
140
133
<listitem><simpara> a literal string
141
134
</simpara></listitem></varlistentry>
142
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> quoted string
135
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> quoted string
143
136
</simpara></listitem></varlistentry>
144
137
</variablelist></refsect2>
146
<title><anchor id="g-shell-unquote" role="function"/>g_shell_unquote ()</title>
147
<indexterm><primary>g_shell_unquote</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_shell_unquote (const <link linkend="gchar">gchar</link> *quoted_string,
138
<refsect2 id="g-shell-unquote" role="function">
139
<title>g_shell_unquote ()</title>
140
<indexterm zone="g-shell-unquote"><primary sortas="g_shell_unquote">g_shell_unquote</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_shell_unquote (const <link linkend="gchar">gchar</link> *quoted_string,
148
141
<link linkend="GError">GError</link> **error);</programlisting>
150
143
Unquotes a string as the shell (/bin/sh) would. Only handles
154
147
would produce (the variables, backticks, etc. will be passed
155
148
through literally instead of being expanded). This function is
156
149
guaranteed to succeed if applied to the result of
157
<link linkend="g-shell-quote"><function>g_shell_quote()</function></link>. If it fails, it returns <link linkend="NULL:CAPS"><literal>NULL</literal></link> and sets the
150
<link linkend="g-shell-quote"><function>g_shell_quote()</function></link>. If it fails, it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link> and sets the
158
151
error. The <parameter>quoted_string</parameter> need not actually contain quoted or
159
152
escaped text; <link linkend="g-shell-unquote"><function>g_shell_unquote()</function></link> simply goes through the string and
160
153
unquotes/unescapes anything that the shell would. Both single and
161
154
double quotes are handled, as are escapes including escaped
162
155
newlines. The return value must be freed with <link linkend="g-free"><function>g_free()</function></link>. Possible
163
errors are in the <link linkend="G-SHELL-ERROR:CAPS"><type>G_SHELL_ERROR</type></link> domain.
156
errors are in the <link linkend="G-SHELL-ERROR--CAPS"><type>G_SHELL_ERROR</type></link> domain.
166
159
Shell quoting rules are a bit strange. Single quotes preserve the
170
163
be escaped with backslash. Otherwise double quotes preserve things
171
164
literally.</para>
174
166
</para><variablelist role="params">
175
<varlistentry><term><parameter>quoted_string</parameter> :</term>
167
<varlistentry><term><parameter>quoted_string</parameter> :</term>
176
168
<listitem><simpara> shell-quoted string
177
169
</simpara></listitem></varlistentry>
178
<varlistentry><term><parameter>error</parameter> :</term>
170
<varlistentry><term><parameter>error</parameter> :</term>
179
171
<listitem><simpara> error return location or NULL
180
172
</simpara></listitem></varlistentry>
181
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an unquoted string
173
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an unquoted string
182
174
</simpara></listitem></varlistentry>
183
175
</variablelist></refsect2>