1
<refentry id="gnome-vfs-20-gnome-vfs-utils">
1
<refentry id="gnome-vfs-2.0-gnome-vfs-utils">
3
<refentrytitle role="top_of_page" id="gnome-vfs-20-gnome-vfs-utils.top_of_page">gnome-vfs-utils</refentrytitle>
3
<refentrytitle role="top_of_page" id="gnome-vfs-2.0-gnome-vfs-utils.top_of_page">gnome-vfs-utils</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
10
10
<refpurpose>various utilities functions to manipulate uris</refpurpose>
13
<refsynopsisdiv id="gnome-vfs-20-gnome-vfs-utils.synopsis" role="synopsis">
13
<refsynopsisdiv id="gnome-vfs-2.0-gnome-vfs-utils.synopsis" role="synopsis">
14
14
<title role="synopsis.title">Synopsis</title>
57
57
<link linkend="char">char</link> * <link linkend="gnome-vfs-get-uri-scheme">gnome_vfs_get_uri_scheme</link> (const <link linkend="char">char</link> *uri);
58
58
<link linkend="gboolean">gboolean</link> <link linkend="gnome-vfs-uris-match">gnome_vfs_uris_match</link> (const <link linkend="char">char</link> *uri_1,
59
59
const <link linkend="char">char</link> *uri_2);
60
#define <link linkend="GNOME-VFS-ASSERT-PRIMARY-THREAD--CAPS">GNOME_VFS_ASSERT_PRIMARY_THREAD</link>
61
#define <link linkend="GNOME-VFS-ASSERT-SECONDARY-THREAD--CAPS">GNOME_VFS_ASSERT_SECONDARY_THREAD</link>
60
#define <link linkend="GNOME-VFS-ASSERT-PRIMARY-THREAD:CAPS">GNOME_VFS_ASSERT_PRIMARY_THREAD</link>
61
#define <link linkend="GNOME-VFS-ASSERT-SECONDARY-THREAD:CAPS">GNOME_VFS_ASSERT_SECONDARY_THREAD</link>
62
62
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-open-fd">gnome_vfs_open_fd</link> (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> **handle,
63
63
<link linkend="int">int</link> filedes);
64
64
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-read-entire-file">gnome_vfs_read_entire_file</link> (const <link linkend="char">char</link> *uri,
78
<refsect1 id="gnome-vfs-20-gnome-vfs-utils.description" role="desc">
78
<refsect1 id="gnome-vfs-2.0-gnome-vfs-utils.description" role="desc">
79
79
<title role="desc.title">Description</title>
84
<refsect1 id="gnome-vfs-20-gnome-vfs-utils.details" role="details">
85
<refsect1 id="gnome-vfs-2.0-gnome-vfs-utils.details" role="details">
85
86
<title role="details.title">Details</title>
86
87
<refsect2 id="GnomeVFSMakeURIDirs" role="enum">
87
88
<title>enum GnomeVFSMakeURIDirs</title>
88
<indexterm zone="GnomeVFSMakeURIDirs"><primary sortas="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</primary></indexterm><programlisting>typedef enum {
89
<indexterm zone="GnomeVFSMakeURIDirs"><primary>GnomeVFSMakeURIDirs</primary></indexterm>
90
<programlisting>typedef enum {
89
91
GNOME_VFS_MAKE_URI_DIR_NONE = 0,
90
92
GNOME_VFS_MAKE_URI_DIR_HOMEDIR = 1 << 0,
91
93
GNOME_VFS_MAKE_URI_DIR_CURRENT = 1 << 1
98
100
If both flags are passed the current directory is checked first.</para>
100
102
</para><variablelist role="enum">
101
<varlistentry id="GNOME-VFS-MAKE-URI-DIR-NONE--CAPS" role="constant">
103
<varlistentry id="GNOME-VFS-MAKE-URI-DIR-NONE:CAPS" role="constant">
102
104
<term><literal>GNOME_VFS_MAKE_URI_DIR_NONE</literal></term>
103
105
<listitem><simpara> Don't check any directory
104
106
</simpara></listitem>
106
<varlistentry id="GNOME-VFS-MAKE-URI-DIR-HOMEDIR--CAPS" role="constant">
108
<varlistentry id="GNOME-VFS-MAKE-URI-DIR-HOMEDIR:CAPS" role="constant">
107
109
<term><literal>GNOME_VFS_MAKE_URI_DIR_HOMEDIR</literal></term>
108
110
<listitem><simpara> Check the home directory
109
111
</simpara></listitem>
111
<varlistentry id="GNOME-VFS-MAKE-URI-DIR-CURRENT--CAPS" role="constant">
113
<varlistentry id="GNOME-VFS-MAKE-URI-DIR-CURRENT:CAPS" role="constant">
112
114
<term><literal>GNOME_VFS_MAKE_URI_DIR_CURRENT</literal></term>
113
115
<listitem><simpara> Check the current direcotry
114
116
</simpara></listitem>
116
118
</variablelist></refsect2>
117
119
<refsect2 id="gnome-vfs-format-file-size-for-display" role="function">
118
120
<title>gnome_vfs_format_file_size_for_display ()</title>
119
<indexterm zone="gnome-vfs-format-file-size-for-display"><primary sortas="gnome_vfs_format_file_size_for_display">gnome_vfs_format_file_size_for_display</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_format_file_size_for_display
121
<indexterm zone="gnome-vfs-format-file-size-for-display"><primary>gnome_vfs_format_file_size_for_display</primary></indexterm>
122
<programlisting><link linkend="char">char</link> * gnome_vfs_format_file_size_for_display
120
123
(<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> size);</programlisting>
122
125
Formats the file <parameter>size</parameter> passed so that it is easy for
132
135
</variablelist></refsect2>
133
136
<refsect2 id="gnome-vfs-format-uri-for-display" role="function" condition="since:2.2">
134
137
<title>gnome_vfs_format_uri_for_display ()</title>
135
<indexterm zone="gnome-vfs-format-uri-for-display" role="2.2"><primary sortas="gnome_vfs_format_uri_for_display">gnome_vfs_format_uri_for_display</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_format_uri_for_display (const <link linkend="char">char</link> *uri);</programlisting>
138
<indexterm zone="gnome-vfs-format-uri-for-display" role="2.2"><primary>gnome_vfs_format_uri_for_display</primary></indexterm>
139
<programlisting><link linkend="char">char</link> * gnome_vfs_format_uri_for_display (const <link linkend="char">char</link> *uri);</programlisting>
137
141
Filter, modify, unescape and change <parameter>uri</parameter> to make it appropriate
138
142
for display to users. The conversion is done such that the roundtrip
154
158
</variablelist><para role="since">Since 2.2</para></refsect2>
155
159
<refsect2 id="gnome-vfs-url-show" role="function" condition="since:2.4">
156
160
<title>gnome_vfs_url_show ()</title>
157
<indexterm zone="gnome-vfs-url-show" role="2.4"><primary sortas="gnome_vfs_url_show">gnome_vfs_url_show</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_url_show (const <link linkend="char">char</link> *url);</programlisting>
161
<indexterm zone="gnome-vfs-url-show" role="2.4"><primary>gnome_vfs_url_show</primary></indexterm>
162
<programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_url_show (const <link linkend="char">char</link> *url);</programlisting>
159
164
Launches the default application or component associated with the given <parameter>url</parameter>.</para>
162
167
<varlistentry><term><parameter>url</parameter> :</term>
163
168
<listitem><simpara> url to be shown.
164
169
</simpara></listitem></varlistentry>
165
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK--CAPS"><literal>GNOME_VFS_OK</literal></link> if the default action was launched,
166
<link linkend="GNOME-VFS-ERROR-BAD-PARAMETERS--CAPS"><literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal></link> for an invalid or non-existant <parameter>url</parameter>,
167
<link linkend="GNOME-VFS-ERROR-NO-DEFAULT--CAPS"><literal>GNOME_VFS_ERROR_NO_DEFAULT</literal></link> if no default action is associated with the <parameter>url</parameter>.
170
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK:CAPS"><literal>GNOME_VFS_OK</literal></link> if the default action was launched,
171
<link linkend="GNOME-VFS-ERROR-BAD-PARAMETERS:CAPS"><literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal></link> for an invalid or non-existant <parameter>url</parameter>,
172
<link linkend="GNOME-VFS-ERROR-NO-DEFAULT:CAPS"><literal>GNOME_VFS_ERROR_NO_DEFAULT</literal></link> if no default action is associated with the <parameter>url</parameter>.
168
173
Also error codes from <link linkend="gnome-vfs-mime-action-launch"><function>gnome_vfs_mime_action_launch()</function></link>
169
174
or <link linkend="gnome-vfs-mime-action-launch-with-env"><function>gnome_vfs_mime_action_launch_with_env()</function></link>.
172
177
</variablelist><para role="since">Since 2.4</para></refsect2>
173
178
<refsect2 id="gnome-vfs-url-show-with-env" role="function" condition="since:2.4">
174
179
<title>gnome_vfs_url_show_with_env ()</title>
175
<indexterm zone="gnome-vfs-url-show-with-env" role="2.4"><primary sortas="gnome_vfs_url_show_with_env">gnome_vfs_url_show_with_env</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_url_show_with_env (const <link linkend="char">char</link> *url,
180
<indexterm zone="gnome-vfs-url-show-with-env" role="2.4"><primary>gnome_vfs_url_show_with_env</primary></indexterm>
181
<programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_url_show_with_env (const <link linkend="char">char</link> *url,
176
182
<link linkend="char">char</link> **envp);</programlisting>
178
184
Like <link linkend="gnome-vfs-url-show"><function>gnome_vfs_url_show()</function></link> except that the default action will be launched
185
191
<varlistentry><term><parameter>envp</parameter> :</term>
186
192
<listitem><simpara> environment data.
187
193
</simpara></listitem></varlistentry>
188
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK--CAPS"><literal>GNOME_VFS_OK</literal></link> if the default action was launched.
189
<link linkend="GNOME-VFS-ERROR-BAD-PARAMETERS--CAPS"><literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal></link> for an invalid or non-existant <parameter>url</parameter>,
190
<link linkend="GNOME-VFS-ERROR-NO-DEFAULT--CAPS"><literal>GNOME_VFS_ERROR_NO_DEFAULT</literal></link> if no default action is associated with the <parameter>url</parameter>.
194
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK:CAPS"><literal>GNOME_VFS_OK</literal></link> if the default action was launched.
195
<link linkend="GNOME-VFS-ERROR-BAD-PARAMETERS:CAPS"><literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal></link> for an invalid or non-existant <parameter>url</parameter>,
196
<link linkend="GNOME-VFS-ERROR-NO-DEFAULT:CAPS"><literal>GNOME_VFS_ERROR_NO_DEFAULT</literal></link> if no default action is associated with the <parameter>url</parameter>.
191
197
Also error codes from <link linkend="gnome-vfs-mime-application-launch-with-env"><function>gnome_vfs_mime_application_launch_with_env()</function></link>
192
198
or <link linkend="gnome-vfs-mime-action-launch-with-env"><function>gnome_vfs_mime_action_launch_with_env()</function></link>.
195
201
</variablelist><para role="since">Since 2.4</para></refsect2>
196
202
<refsect2 id="gnome-vfs-escape-string" role="function">
197
203
<title>gnome_vfs_escape_string ()</title>
198
<indexterm zone="gnome-vfs-escape-string"><primary sortas="gnome_vfs_escape_string">gnome_vfs_escape_string</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_escape_string (const <link linkend="char">char</link> *string);</programlisting>
204
<indexterm zone="gnome-vfs-escape-string"><primary>gnome_vfs_escape_string</primary></indexterm>
205
<programlisting><link linkend="char">char</link> * gnome_vfs_escape_string (const <link linkend="char">char</link> *string);</programlisting>
200
207
Escapes <parameter>string</parameter>, replacing any and all special characters
201
208
with equivalent escape sequences.</para>
210
217
</variablelist></refsect2>
211
218
<refsect2 id="gnome-vfs-escape-path-string" role="function">
212
219
<title>gnome_vfs_escape_path_string ()</title>
213
<indexterm zone="gnome-vfs-escape-path-string"><primary sortas="gnome_vfs_escape_path_string">gnome_vfs_escape_path_string</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_escape_path_string (const <link linkend="char">char</link> *path);</programlisting>
220
<indexterm zone="gnome-vfs-escape-path-string"><primary>gnome_vfs_escape_path_string</primary></indexterm>
221
<programlisting><link linkend="char">char</link> * gnome_vfs_escape_path_string (const <link linkend="char">char</link> *path);</programlisting>
215
223
Escapes <parameter>path</parameter>, replacing only special characters that would not
216
224
be found in paths (so '/', '&', and '=' will not be escaped by
226
234
</variablelist></refsect2>
227
235
<refsect2 id="gnome-vfs-escape-host-and-path-string" role="function">
228
236
<title>gnome_vfs_escape_host_and_path_string ()</title>
229
<indexterm zone="gnome-vfs-escape-host-and-path-string"><primary sortas="gnome_vfs_escape_host_and_path_string">gnome_vfs_escape_host_and_path_string</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_escape_host_and_path_string
237
<indexterm zone="gnome-vfs-escape-host-and-path-string"><primary>gnome_vfs_escape_host_and_path_string</primary></indexterm>
238
<programlisting><link linkend="char">char</link> * gnome_vfs_escape_host_and_path_string
230
239
(const <link linkend="char">char</link> *path);</programlisting>
232
241
Escapes <parameter>path</parameter>, replacing only special characters that would not
243
252
</variablelist></refsect2>
244
253
<refsect2 id="gnome-vfs-escape-slashes" role="function">
245
254
<title>gnome_vfs_escape_slashes ()</title>
246
<indexterm zone="gnome-vfs-escape-slashes"><primary sortas="gnome_vfs_escape_slashes">gnome_vfs_escape_slashes</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_escape_slashes (const <link linkend="char">char</link> *string);</programlisting>
255
<indexterm zone="gnome-vfs-escape-slashes"><primary>gnome_vfs_escape_slashes</primary></indexterm>
256
<programlisting><link linkend="char">char</link> * gnome_vfs_escape_slashes (const <link linkend="char">char</link> *string);</programlisting>
248
258
Escapes only '/' and '%' characters in <parameter>string</parameter>, replacing
249
259
them with their escape sequence equivalents.</para>
258
268
</variablelist></refsect2>
259
269
<refsect2 id="gnome-vfs-escape-set" role="function">
260
270
<title>gnome_vfs_escape_set ()</title>
261
<indexterm zone="gnome-vfs-escape-set"><primary sortas="gnome_vfs_escape_set">gnome_vfs_escape_set</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_escape_set (const <link linkend="char">char</link> *string,
271
<indexterm zone="gnome-vfs-escape-set"><primary>gnome_vfs_escape_set</primary></indexterm>
272
<programlisting><link linkend="char">char</link> * gnome_vfs_escape_set (const <link linkend="char">char</link> *string,
262
273
const <link linkend="char">char</link> *match_set);</programlisting>
264
275
Escapes all characters in <parameter>string</parameter> which are listed in <parameter>match_set</parameter>.</para>
276
287
</variablelist></refsect2>
277
288
<refsect2 id="gnome-vfs-unescape-string" role="function">
278
289
<title>gnome_vfs_unescape_string ()</title>
279
<indexterm zone="gnome-vfs-unescape-string"><primary sortas="gnome_vfs_unescape_string">gnome_vfs_unescape_string</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_unescape_string (const <link linkend="char">char</link> *escaped_string,
290
<indexterm zone="gnome-vfs-unescape-string"><primary>gnome_vfs_unescape_string</primary></indexterm>
291
<programlisting><link linkend="char">char</link> * gnome_vfs_unescape_string (const <link linkend="char">char</link> *escaped_string,
280
292
const <link linkend="char">char</link> *illegal_characters);</programlisting>
282
294
Decodes escaped characters (i.e. PERCENTxx sequences) in <parameter>escaped_string</parameter>.
292
304
considered "illegal" to be escaped, '\0' is automatically in this list.
293
305
</simpara></listitem></varlistentry>
294
306
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string with the unescaped
295
equivalents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>escaped_string</parameter> contained an escaped
307
equivalents, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>escaped_string</parameter> contained an escaped
296
308
encoding of one of the characters in <parameter>illegal_characters</parameter>.
297
309
</simpara></listitem></varlistentry>
298
310
</variablelist></refsect2>
299
311
<refsect2 id="gnome-vfs-make-uri-canonical" role="function" condition="since:2.2">
300
312
<title>gnome_vfs_make_uri_canonical ()</title>
301
<indexterm zone="gnome-vfs-make-uri-canonical" role="2.2"><primary sortas="gnome_vfs_make_uri_canonical">gnome_vfs_make_uri_canonical</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_canonical (const <link linkend="char">char</link> *uri);</programlisting>
313
<indexterm zone="gnome-vfs-make-uri-canonical" role="2.2"><primary>gnome_vfs_make_uri_canonical</primary></indexterm>
314
<programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_canonical (const <link linkend="char">char</link> *uri);</programlisting>
303
316
Standardizes the format of the <parameter>uri</parameter>, so that it can be used
304
317
later in other functions that expect a canonical uri.</para>
314
327
</variablelist><para role="since">Since 2.2</para></refsect2>
315
328
<refsect2 id="gnome-vfs-make-uri-canonical-strip-fragment" role="function" condition="since:2.2">
316
329
<title>gnome_vfs_make_uri_canonical_strip_fragment ()</title>
317
<indexterm zone="gnome-vfs-make-uri-canonical-strip-fragment" role="2.2"><primary sortas="gnome_vfs_make_uri_canonical_strip_fragment">gnome_vfs_make_uri_canonical_strip_fragment</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_canonical_strip_fragment
330
<indexterm zone="gnome-vfs-make-uri-canonical-strip-fragment" role="2.2"><primary>gnome_vfs_make_uri_canonical_strip_fragment</primary></indexterm>
331
<programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_canonical_strip_fragment
318
332
(const <link linkend="char">char</link> *uri);</programlisting>
320
334
Returns a canonicalized uri. If <parameter>uri</parameter> contains a fragment (anything after a '#') strips off that and
323
337
</para><variablelist role="params">
324
338
<varlistentry><term><parameter>uri</parameter> :</term>
325
<listitem><simpara> a <link linkend="GnomeVFSURI"><type>GnomeVFSURI</type></link>.
339
<listitem><simpara> a <link linkend="GnomeVFSURI."><type>GnomeVFSURI.</type></link>
326
340
</simpara></listitem></varlistentry>
327
341
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing a canonical <parameter>uri</parameter>.
330
344
</variablelist><para role="since">Since 2.2</para></refsect2>
331
345
<refsect2 id="gnome-vfs-make-path-name-canonical" role="function">
332
346
<title>gnome_vfs_make_path_name_canonical ()</title>
333
<indexterm zone="gnome-vfs-make-path-name-canonical"><primary sortas="gnome_vfs_make_path_name_canonical">gnome_vfs_make_path_name_canonical</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_path_name_canonical (const <link linkend="char">char</link> *path);</programlisting>
347
<indexterm zone="gnome-vfs-make-path-name-canonical"><primary>gnome_vfs_make_path_name_canonical</primary></indexterm>
348
<programlisting><link linkend="char">char</link> * gnome_vfs_make_path_name_canonical (const <link linkend="char">char</link> *path);</programlisting>
335
350
Calls <link linkend="gnome-vfs-canonicalize-pathname"><function>_gnome_vfs_canonicalize_pathname()</function></link>, allocating storage for the
336
351
result and providing for a cleaner memory management.</para>
344
359
</variablelist></refsect2>
345
360
<refsect2 id="gnome-vfs-make-uri-from-input" role="function" condition="since:2.2">
346
361
<title>gnome_vfs_make_uri_from_input ()</title>
347
<indexterm zone="gnome-vfs-make-uri-from-input" role="2.2"><primary sortas="gnome_vfs_make_uri_from_input">gnome_vfs_make_uri_from_input</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_from_input (const <link linkend="char">char</link> *location);</programlisting>
362
<indexterm zone="gnome-vfs-make-uri-from-input" role="2.2"><primary>gnome_vfs_make_uri_from_input</primary></indexterm>
363
<programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_from_input (const <link linkend="char">char</link> *location);</programlisting>
349
365
Takes a user input path/uri and makes a valid uri out of it.
363
379
</variablelist><para role="since">Since 2.2</para></refsect2>
364
380
<refsect2 id="gnome-vfs-make-uri-from-input-with-dirs" role="function" condition="since:2.4">
365
381
<title>gnome_vfs_make_uri_from_input_with_dirs ()</title>
366
<indexterm zone="gnome-vfs-make-uri-from-input-with-dirs" role="2.4"><primary sortas="gnome_vfs_make_uri_from_input_with_dirs">gnome_vfs_make_uri_from_input_with_dirs</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_from_input_with_dirs
382
<indexterm zone="gnome-vfs-make-uri-from-input-with-dirs" role="2.4"><primary>gnome_vfs_make_uri_from_input_with_dirs</primary></indexterm>
383
<programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_from_input_with_dirs
367
384
(const <link linkend="char">char</link> *location,
368
385
<link linkend="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</link> dirs);</programlisting>
385
402
</variablelist><para role="since">Since 2.4</para></refsect2>
386
403
<refsect2 id="gnome-vfs-make-uri-from-shell-arg" role="function" condition="since:2.2">
387
404
<title>gnome_vfs_make_uri_from_shell_arg ()</title>
388
<indexterm zone="gnome-vfs-make-uri-from-shell-arg" role="2.2"><primary sortas="gnome_vfs_make_uri_from_shell_arg">gnome_vfs_make_uri_from_shell_arg</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_from_shell_arg (const <link linkend="char">char</link> *uri);</programlisting>
405
<indexterm zone="gnome-vfs-make-uri-from-shell-arg" role="2.2"><primary>gnome_vfs_make_uri_from_shell_arg</primary></indexterm>
406
<programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_from_shell_arg (const <link linkend="char">char</link> *uri);</programlisting>
390
408
Similar to <link linkend="gnome-vfs-make-uri-from-input"><function>gnome_vfs_make_uri_from_input()</function></link>, except that:
404
422
</variablelist><para role="since">Since 2.2</para></refsect2>
405
423
<refsect2 id="gnome-vfs-make-uri-full-from-relative" role="function" condition="deprecated|since:2.2">
406
424
<title>gnome_vfs_make_uri_full_from_relative ()</title>
407
<indexterm zone="gnome-vfs-make-uri-full-from-relative" role="deprecated"><primary sortas="gnome_vfs_make_uri_full_from_relative">gnome_vfs_make_uri_full_from_relative</primary></indexterm><indexterm zone="gnome-vfs-make-uri-full-from-relative" role="2.2"><primary sortas="gnome_vfs_make_uri_full_from_relative">gnome_vfs_make_uri_full_from_relative</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_full_from_relative
425
<indexterm zone="gnome-vfs-make-uri-full-from-relative" role="deprecated"><primary>gnome_vfs_make_uri_full_from_relative</primary></indexterm><indexterm zone="gnome-vfs-make-uri-full-from-relative" role="2.2"><primary>gnome_vfs_make_uri_full_from_relative</primary></indexterm>
426
<programlisting><link linkend="char">char</link> * gnome_vfs_make_uri_full_from_relative
408
427
(const <link linkend="char">char</link> *base_uri,
409
428
const <link linkend="char">char</link> *relative_uri);</programlisting>
410
429
<warning><para><literal>gnome_vfs_make_uri_full_from_relative</literal> is deprecated and should not be used in newly-written code. This function is deprecated, please use
421
440
<listitem><simpara> full or relative path to be appended to the <parameter>base_uri</parameter>.
422
441
</simpara></listitem></varlistentry>
423
442
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the uri.
424
(<link linkend="NULL--CAPS"><literal>NULL</literal></link> for some bad errors).
443
(<link linkend="NULL:CAPS"><literal>NULL</literal></link> for some bad errors).
426
445
</simpara></listitem></varlistentry>
427
446
</variablelist><para role="since">Since 2.2</para></refsect2>
428
447
<refsect2 id="gnome-vfs-expand-initial-tilde" role="function">
429
448
<title>gnome_vfs_expand_initial_tilde ()</title>
430
<indexterm zone="gnome-vfs-expand-initial-tilde"><primary sortas="gnome_vfs_expand_initial_tilde">gnome_vfs_expand_initial_tilde</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_expand_initial_tilde (const <link linkend="char">char</link> *path);</programlisting>
449
<indexterm zone="gnome-vfs-expand-initial-tilde"><primary>gnome_vfs_expand_initial_tilde</primary></indexterm>
450
<programlisting><link linkend="char">char</link> * gnome_vfs_expand_initial_tilde (const <link linkend="char">char</link> *path);</programlisting>
432
452
If <parameter>path</parameter> starts with a ~, representing the user's home
433
453
directory, expand it to the actual path location.</para>
442
462
</variablelist></refsect2>
443
463
<refsect2 id="gnome-vfs-unescape-string-for-display" role="function">
444
464
<title>gnome_vfs_unescape_string_for_display ()</title>
445
<indexterm zone="gnome-vfs-unescape-string-for-display"><primary sortas="gnome_vfs_unescape_string_for_display">gnome_vfs_unescape_string_for_display</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_unescape_string_for_display
465
<indexterm zone="gnome-vfs-unescape-string-for-display"><primary>gnome_vfs_unescape_string_for_display</primary></indexterm>
466
<programlisting><link linkend="char">char</link> * gnome_vfs_unescape_string_for_display
446
467
(const <link linkend="char">char</link> *escaped);</programlisting>
448
469
Similar to gnome_vfs_unescape_string, but it returns something
449
470
semi-intelligable to a user even upon receiving traumatic input
450
such as <link linkend="00--CAPS"><literal>00</literal></link> or URIs in bad form.
471
such as <link linkend="00:CAPS"><literal>00</literal></link> or URIs in bad form.
453
474
See also: <link linkend="gnome-vfs-unescape-string"><function>gnome_vfs_unescape_string()</function></link>.
468
489
</variablelist></refsect2>
469
490
<refsect2 id="gnome-vfs-get-local-path-from-uri" role="function">
470
491
<title>gnome_vfs_get_local_path_from_uri ()</title>
471
<indexterm zone="gnome-vfs-get-local-path-from-uri"><primary sortas="gnome_vfs_get_local_path_from_uri">gnome_vfs_get_local_path_from_uri</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_get_local_path_from_uri (const <link linkend="char">char</link> *uri);</programlisting>
492
<indexterm zone="gnome-vfs-get-local-path-from-uri"><primary>gnome_vfs_get_local_path_from_uri</primary></indexterm>
493
<programlisting><link linkend="char">char</link> * gnome_vfs_get_local_path_from_uri (const <link linkend="char">char</link> *uri);</programlisting>
473
495
Create a local path for a file:/// uri. Do not use with uris
474
496
of other methods.</para>
478
500
<listitem><simpara> uri to convert to a local path.
479
501
</simpara></listitem></varlistentry>
480
502
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the local path.
481
<link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned on error or if the uri isn't a file: uri
503
<link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned on error or if the uri isn't a file: uri
482
504
without a fragment identifier (or chained uri).
483
505
</simpara></listitem></varlistentry>
484
506
</variablelist></refsect2>
485
507
<refsect2 id="gnome-vfs-get-uri-from-local-path" role="function">
486
508
<title>gnome_vfs_get_uri_from_local_path ()</title>
487
<indexterm zone="gnome-vfs-get-uri-from-local-path"><primary sortas="gnome_vfs_get_uri_from_local_path">gnome_vfs_get_uri_from_local_path</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_get_uri_from_local_path (const <link linkend="char">char</link> *local_full_path);</programlisting>
509
<indexterm zone="gnome-vfs-get-uri-from-local-path"><primary>gnome_vfs_get_uri_from_local_path</primary></indexterm>
510
<programlisting><link linkend="char">char</link> * gnome_vfs_get_uri_from_local_path (const <link linkend="char">char</link> *local_full_path);</programlisting>
489
512
Returns a file:/// URI for the local path <parameter>local_full_path</parameter>,
490
513
such as a path provided by <link linkend="gtk-file-chooser-get-filename"><function>gtk_file_chooser_get_filename()</function></link>.
499
522
<listitem><simpara> a full local filesystem path (i.e. not relative).
500
523
</simpara></listitem></varlistentry>
501
524
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the uri corresponding
502
to <parameter>local_full_path</parameter> (<link linkend="NULL--CAPS"><literal>NULL</literal></link> for some bad errors).
525
to <parameter>local_full_path</parameter> (<link linkend="NULL:CAPS"><literal>NULL</literal></link> for some bad errors).
503
526
</simpara></listitem></varlistentry>
504
527
</variablelist></refsect2>
505
528
<refsect2 id="gnome-vfs-is-executable-command-string" role="function">
506
529
<title>gnome_vfs_is_executable_command_string ()</title>
507
<indexterm zone="gnome-vfs-is-executable-command-string"><primary sortas="gnome_vfs_is_executable_command_string">gnome_vfs_is_executable_command_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_is_executable_command_string
530
<indexterm zone="gnome-vfs-is-executable-command-string"><primary>gnome_vfs_is_executable_command_string</primary></indexterm>
531
<programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_is_executable_command_string
508
532
(const <link linkend="char">char</link> *command_string);</programlisting>
510
534
Checks if <parameter>command_string</parameter> starts with the full path of an executable file
514
538
<varlistentry><term><parameter>command_string</parameter> :</term>
515
539
<listitem><simpara> a string representing a command ie "xterm -bg white".
516
540
</simpara></listitem></varlistentry>
517
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>command_string</parameter> started with an executable file, and is in $PATH,
518
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
541
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>command_string</parameter> started with an executable file, and is in $PATH,
542
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
519
543
</simpara></listitem></varlistentry>
520
544
</variablelist></refsect2>
521
545
<refsect2 id="gnome-vfs-list-deep-free" role="function">
522
546
<title>gnome_vfs_list_deep_free ()</title>
523
<indexterm zone="gnome-vfs-list-deep-free"><primary sortas="gnome_vfs_list_deep_free">gnome_vfs_list_deep_free</primary></indexterm><programlisting><link linkend="void">void</link> gnome_vfs_list_deep_free (<link linkend="GList">GList</link> *list);</programlisting>
547
<indexterm zone="gnome-vfs-list-deep-free"><primary>gnome_vfs_list_deep_free</primary></indexterm>
548
<programlisting><link linkend="void">void</link> gnome_vfs_list_deep_free (<link linkend="GList">GList</link> *list);</programlisting>
525
550
Free <parameter>list</parameter> and call <link linkend="g-free"><function>g_free()</function></link> on all data members.</para>
531
556
</variablelist></refsect2>
532
557
<refsect2 id="gnome-vfs-get-volume-free-space" role="function">
533
558
<title>gnome_vfs_get_volume_free_space ()</title>
534
<indexterm zone="gnome-vfs-get-volume-free-space"><primary sortas="gnome_vfs_get_volume_free_space">gnome_vfs_get_volume_free_space</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_get_volume_free_space (const <link linkend="GnomeVFSURI">GnomeVFSURI</link> *vfs_uri,
559
<indexterm zone="gnome-vfs-get-volume-free-space"><primary>gnome_vfs_get_volume_free_space</primary></indexterm>
560
<programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_get_volume_free_space (const <link linkend="GnomeVFSURI">GnomeVFSURI</link> *vfs_uri,
535
561
<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *size);</programlisting>
537
563
Stores the amount of free space in bytes on <parameter>vfs</parameter>-uri's
540
566
</para><variablelist role="params">
541
567
<varlistentry><term><parameter>vfs_uri</parameter> :</term>
542
<listitem><simpara> a <link linkend="GnomeVFSURI"><type>GnomeVFSURI</type></link>.
568
<listitem><simpara> a <link linkend="GnomeVFSURI."><type>GnomeVFSURI.</type></link>
543
569
</simpara></listitem></varlistentry>
544
570
<varlistentry><term><parameter>size</parameter> :</term>
545
<listitem><simpara> a <link linkend="GnomeVFSFileSize"><type>GnomeVFSFileSize</type></link>.
571
<listitem><simpara> a <link linkend="GnomeVFSFileSize."><type>GnomeVFSFileSize.</type></link>
546
572
</simpara></listitem></varlistentry>
547
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK--CAPS"><literal>GNOME_VFS_OK</literal></link> on success, otherwise an
548
<link linkend="GNOME-VFS-ERROR---CAPS"><literal>GNOME_VFS_ERROR_</literal></link>* code.
573
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK:CAPS"><literal>GNOME_VFS_OK</literal></link> on success, otherwise an
574
<link linkend="GNOME-VFS-ERROR-:CAPS"><literal>GNOME_VFS_ERROR_</literal></link>* code.
549
575
</simpara></listitem></varlistentry>
550
576
</variablelist></refsect2>
551
577
<refsect2 id="gnome-vfs-icon-path-from-filename" role="function">
552
578
<title>gnome_vfs_icon_path_from_filename ()</title>
553
<indexterm zone="gnome-vfs-icon-path-from-filename"><primary sortas="gnome_vfs_icon_path_from_filename">gnome_vfs_icon_path_from_filename</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_icon_path_from_filename (const <link linkend="char">char</link> *filename);</programlisting>
579
<indexterm zone="gnome-vfs-icon-path-from-filename"><primary>gnome_vfs_icon_path_from_filename</primary></indexterm>
580
<programlisting><link linkend="char">char</link> * gnome_vfs_icon_path_from_filename (const <link linkend="char">char</link> *filename);</programlisting>
557
582
</para><variablelist role="params">
558
583
<varlistentry><term><parameter>filename</parameter> :</term>
565
590
</variablelist></refsect2>
566
591
<refsect2 id="gnome-vfs-is-primary-thread" role="function">
567
592
<title>gnome_vfs_is_primary_thread ()</title>
568
<indexterm zone="gnome-vfs-is-primary-thread"><primary sortas="gnome_vfs_is_primary_thread">gnome_vfs_is_primary_thread</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_is_primary_thread (void);</programlisting>
593
<indexterm zone="gnome-vfs-is-primary-thread"><primary>gnome_vfs_is_primary_thread</primary></indexterm>
594
<programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_is_primary_thread (void);</programlisting>
570
596
Check if the current thread is the thread with the main glib event loop.</para>
572
598
</para><variablelist role="params">
573
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the current thread is the thread with the
599
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the current thread is the thread with the
574
600
main glib event loop.
575
601
</simpara></listitem></varlistentry>
576
602
</variablelist></refsect2>
577
603
<refsect2 id="gnome-vfs-get-uri-scheme" role="function" condition="since:2.2">
578
604
<title>gnome_vfs_get_uri_scheme ()</title>
579
<indexterm zone="gnome-vfs-get-uri-scheme" role="2.2"><primary sortas="gnome_vfs_get_uri_scheme">gnome_vfs_get_uri_scheme</primary></indexterm><programlisting><link linkend="char">char</link> * gnome_vfs_get_uri_scheme (const <link linkend="char">char</link> *uri);</programlisting>
605
<indexterm zone="gnome-vfs-get-uri-scheme" role="2.2"><primary>gnome_vfs_get_uri_scheme</primary></indexterm>
606
<programlisting><link linkend="char">char</link> * gnome_vfs_get_uri_scheme (const <link linkend="char">char</link> *uri);</programlisting>
581
608
Retrieve the scheme used in <parameter>uri</parameter>.</para>
584
611
<varlistentry><term><parameter>uri</parameter> :</term>
585
612
<listitem><simpara> a stringified uri.
586
613
</simpara></listitem></varlistentry>
587
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the scheme, <link linkend="NULL--CAPS"><literal>NULL</literal></link>
614
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the scheme, <link linkend="NULL:CAPS"><literal>NULL</literal></link>
588
615
if <parameter>uri</parameter> doesn't contain a scheme.
590
617
</simpara></listitem></varlistentry>
591
618
</variablelist><para role="since">Since 2.2</para></refsect2>
592
619
<refsect2 id="gnome-vfs-uris-match" role="function" condition="since:2.2">
593
620
<title>gnome_vfs_uris_match ()</title>
594
<indexterm zone="gnome-vfs-uris-match" role="2.2"><primary sortas="gnome_vfs_uris_match">gnome_vfs_uris_match</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_uris_match (const <link linkend="char">char</link> *uri_1,
621
<indexterm zone="gnome-vfs-uris-match" role="2.2"><primary>gnome_vfs_uris_match</primary></indexterm>
622
<programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_uris_match (const <link linkend="char">char</link> *uri_1,
595
623
const <link linkend="char">char</link> *uri_2);</programlisting>
597
625
Compare two uris.</para>
603
631
<varlistentry><term><parameter>uri_2</parameter> :</term>
604
632
<listitem><simpara> stringified uri to compare with <parameter>uri_1</parameter>.
605
633
</simpara></listitem></varlistentry>
606
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if they are the same, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
634
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if they are the same, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
608
636
</simpara></listitem></varlistentry>
609
637
</variablelist><para role="since">Since 2.2</para></refsect2>
610
<refsect2 id="GNOME-VFS-ASSERT-PRIMARY-THREAD--CAPS" role="macro">
638
<refsect2 id="GNOME-VFS-ASSERT-PRIMARY-THREAD:CAPS" role="macro">
611
639
<title>GNOME_VFS_ASSERT_PRIMARY_THREAD</title>
612
<indexterm zone="GNOME-VFS-ASSERT-PRIMARY-THREAD--CAPS"><primary sortas="GNOME_VFS_ASSERT_PRIMARY_THREAD">GNOME_VFS_ASSERT_PRIMARY_THREAD</primary></indexterm><programlisting>#define GNOME_VFS_ASSERT_PRIMARY_THREAD g_assert (gnome_vfs_is_primary_thread())
640
<indexterm zone="GNOME-VFS-ASSERT-PRIMARY-THREAD:CAPS"><primary>GNOME_VFS_ASSERT_PRIMARY_THREAD</primary></indexterm>
641
<programlisting>#define GNOME_VFS_ASSERT_PRIMARY_THREAD g_assert (gnome_vfs_is_primary_thread())
613
642
</programlisting>
615
644
Asserts that the current thread is the thread with
616
645
the main glib event loop</para>
618
647
</para></refsect2>
619
<refsect2 id="GNOME-VFS-ASSERT-SECONDARY-THREAD--CAPS" role="macro">
648
<refsect2 id="GNOME-VFS-ASSERT-SECONDARY-THREAD:CAPS" role="macro">
620
649
<title>GNOME_VFS_ASSERT_SECONDARY_THREAD</title>
621
<indexterm zone="GNOME-VFS-ASSERT-SECONDARY-THREAD--CAPS"><primary sortas="GNOME_VFS_ASSERT_SECONDARY_THREAD">GNOME_VFS_ASSERT_SECONDARY_THREAD</primary></indexterm><programlisting>#define GNOME_VFS_ASSERT_SECONDARY_THREAD g_assert (!gnome_vfs_is_primary_thread())
650
<indexterm zone="GNOME-VFS-ASSERT-SECONDARY-THREAD:CAPS"><primary>GNOME_VFS_ASSERT_SECONDARY_THREAD</primary></indexterm>
651
<programlisting>#define GNOME_VFS_ASSERT_SECONDARY_THREAD g_assert (!gnome_vfs_is_primary_thread())
622
652
</programlisting>
624
654
Asserts that the current thread is NOT the thread with
627
657
</para></refsect2>
628
658
<refsect2 id="gnome-vfs-open-fd" role="function">
629
659
<title>gnome_vfs_open_fd ()</title>
630
<indexterm zone="gnome-vfs-open-fd"><primary sortas="gnome_vfs_open_fd">gnome_vfs_open_fd</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_open_fd (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> **handle,
660
<indexterm zone="gnome-vfs-open-fd"><primary>gnome_vfs_open_fd</primary></indexterm>
661
<programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_open_fd (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> **handle,
631
662
<link linkend="int">int</link> filedes);</programlisting>
633
664
Converts an open unix file descript into a GnomeVFSHandle that
641
672
<varlistentry><term><parameter>filedes</parameter> :</term>
642
673
<listitem><simpara> a UNIX file descriptor
643
674
</simpara></listitem></varlistentry>
644
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK--CAPS"><literal>GNOME_VFS_OK</literal></link> if the open was ok, a suitable error otherwise.
675
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GNOME-VFS-OK:CAPS"><literal>GNOME_VFS_OK</literal></link> if the open was ok, a suitable error otherwise.
647
678
</simpara></listitem></varlistentry>
648
679
</variablelist></refsect2>
649
680
<refsect2 id="gnome-vfs-read-entire-file" role="function" condition="since:2.2">
650
681
<title>gnome_vfs_read_entire_file ()</title>
651
<indexterm zone="gnome-vfs-read-entire-file" role="2.2"><primary sortas="gnome_vfs_read_entire_file">gnome_vfs_read_entire_file</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_read_entire_file (const <link linkend="char">char</link> *uri,
682
<indexterm zone="gnome-vfs-read-entire-file" role="2.2"><primary>gnome_vfs_read_entire_file</primary></indexterm>
683
<programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_read_entire_file (const <link linkend="char">char</link> *uri,
652
684
<link linkend="int">int</link> *file_size,
653
685
<link linkend="char">char</link> **file_contents);</programlisting>
added
removed
doc/xml/gnome-vfs-utils.xml
