← Back to branch summary

~ubuntu-branches/debian/jessie/glib2.0/jessie

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/shell.xml

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo Noronha Silva
  • Date: 2009-02-15 13:00:43 UTC
  • mto: (1.4.3 upstream)
  • mto: This revision was merged to the branch mainline in revision 70.
  • Revision ID: james.westby@ubuntu.com-20090215130043-6snh45flhit8oalb
Tags: upstream-2.18.4
Import upstream version 2.18.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/xml/shell.xml
1
1
<refentry id="glib-Shell-related-Utilities">
2
2
<refmeta>
3
 
<refentrytitle role="top_of_page">Shell-related Utilities</refentrytitle>
 
3
<refentrytitle role="top_of_page" id="glib-Shell-related-Utilities.top_of_page">Shell-related Utilities</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GLIB Library</refmiscinfo>
6
6
</refmeta>
8
8
<refnamediv>
9
9
<refname>Shell-related Utilities</refname>
10
10
<refpurpose>shell-like commandline handling</refpurpose>
11
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12
11
</refnamediv>
13
12
 
14
 
<refsynopsisdiv role="synopsis">
 
13
<refsynopsisdiv id="glib-Shell-related-Utilities.synopsis" role="synopsis">
15
14
<title role="synopsis.title">Synopsis</title>
16
15
 
17
16
<synopsis>
18
17
 
19
18
#include &lt;glib.h&gt;
20
19
 
21
 
 
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,
28
26
<link linkend="gchar">gchar</link>*              <link linkend="g-shell-quote">g_shell_quote</link>                       (const <link linkend="gchar">gchar</link> *unquoted_string);
29
27
<link linkend="gchar">gchar</link>*              <link linkend="g-shell-unquote">g_shell_unquote</link>                     (const <link linkend="gchar">gchar</link> *quoted_string,
30
28
                                                         <link linkend="GError">GError</link> **error);
31
 
 
32
29
</synopsis>
33
30
</refsynopsisdiv>
34
31
 
40
37
 
41
38
 
42
39
 
43
 
<refsect1 role="desc">
 
40
<refsect1 id="glib-Shell-related-Utilities.description" role="desc">
44
41
<title role="desc.title">Description</title>
45
42
<para>
46
 
 
47
43
</para>
48
44
</refsect1>
49
45
 
50
 
<refsect1 role="details">
 
46
<refsect1 id="glib-Shell-related-Utilities.details" role="details">
51
47
<title role="details.title">Details</title>
52
 
<refsect2>
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
55
51
{
56
52
  /* mismatched or otherwise mangled quoting */
57
53
  G_SHELL_ERROR_BAD_QUOTING,
63
59
<para>
64
60
Error codes returned by shell functions.
65
61
</para><variablelist role="enum">
66
 
<varlistentry>
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>
70
66
</varlistentry>
71
 
<varlistentry>
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>
75
71
</varlistentry>
76
 
<varlistentry>
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.
79
 
 
80
75
</simpara></listitem>
81
76
</varlistentry>
82
77
</variablelist></refsect2>
83
 
<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 ()
86
81
</programlisting>
87
82
<para>
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
90
85
error domains.
91
86
</para></refsect2>
92
 
<refsect2>
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>
108
103
<para>
109
 
 
110
104
</para><variablelist role="params">
111
 
<varlistentry><term><parameter>command_line</parameter>&nbsp;:</term>
 
105
<varlistentry><term><parameter>command_line</parameter>&#160;:</term>
112
106
<listitem><simpara> command line to parse
113
107
</simpara></listitem></varlistentry>
114
 
<varlistentry><term><parameter>argcp</parameter>&nbsp;:</term>
 
108
<varlistentry><term><parameter>argcp</parameter>&#160;:</term>
115
109
<listitem><simpara> return location for number of args
116
110
</simpara></listitem></varlistentry>
117
 
<varlistentry><term><parameter>argvp</parameter>&nbsp;:</term>
 
111
<varlistentry><term><parameter>argvp</parameter>&#160;:</term>
118
112
<listitem><simpara> return location for array of args
119
113
</simpara></listitem></varlistentry>
120
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
114
<varlistentry><term><parameter>error</parameter>&#160;:</term>
121
115
<listitem><simpara> return location for error
122
116
</simpara></listitem></varlistentry>
123
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</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>&#160;:</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>
126
 
<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>
129
123
<para>
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
135
129
used).</para>
136
130
<para>
137
 
 
138
131
</para><variablelist role="params">
139
 
<varlistentry><term><parameter>unquoted_string</parameter>&nbsp;:</term>
 
132
<varlistentry><term><parameter>unquoted_string</parameter>&#160;:</term>
140
133
<listitem><simpara> a literal string
141
134
</simpara></listitem></varlistentry>
142
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> quoted string
 
135
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> quoted string
143
136
</simpara></listitem></varlistentry>
144
137
</variablelist></refsect2>
145
 
<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>
149
142
<para>
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.
164
157
</para>
165
158
<para>
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>
172
165
<para>
173
 
 
174
166
</para><variablelist role="params">
175
 
<varlistentry><term><parameter>quoted_string</parameter>&nbsp;:</term>
 
167
<varlistentry><term><parameter>quoted_string</parameter>&#160;:</term>
176
168
<listitem><simpara> shell-quoted string
177
169
</simpara></listitem></varlistentry>
178
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
170
<varlistentry><term><parameter>error</parameter>&#160;:</term>
179
171
<listitem><simpara> error return location or NULL
180
172
</simpara></listitem></varlistentry>
181
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an unquoted string
 
173
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> an unquoted string
182
174
</simpara></listitem></varlistentry>
183
175
</variablelist></refsect2>
184
176
 
187
179
 
188
180
 
189
181
 
190
 
 
191
 
<refsect1><refsect2 /><refsect2 /></refsect1>
192
182
</refentry>