1
<refentry id="gnome-vfs-20-gnome-vfs-utils">
3
<refentrytitle>gnome-vfs-utils</refentrytitle>
4
<manvolnum>3</manvolnum>
5
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
9
<refname>gnome-vfs-utils</refname><refpurpose>various utilities functions to manipulate uris</refpurpose>
12
<refsynopsisdiv><title>Synopsis</title>
18
<link linkend="char">char</link>* <link linkend="gnome-vfs-format-file-size-for-display">gnome_vfs_format_file_size_for_display</link>
19
(<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> size);
20
<link linkend="char">char</link>* <link linkend="gnome-vfs-format-uri-for-display">gnome_vfs_format_uri_for_display</link>
21
(const <link linkend="char">char</link> *uri);
22
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-url-show">gnome_vfs_url_show</link> (const <link linkend="char">char</link> *url);
23
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-url-show-with-env">gnome_vfs_url_show_with_env</link> (const <link linkend="char">char</link> *url,
24
<link linkend="char">char</link> **envp);
25
<link linkend="char">char</link>* <link linkend="gnome-vfs-escape-string">gnome_vfs_escape_string</link> (const <link linkend="char">char</link> *string);
26
<link linkend="char">char</link>* <link linkend="gnome-vfs-escape-path-string">gnome_vfs_escape_path_string</link> (const <link linkend="char">char</link> *path);
27
<link linkend="char">char</link>* <link linkend="gnome-vfs-escape-host-and-path-string">gnome_vfs_escape_host_and_path_string</link>
28
(const <link linkend="char">char</link> *path);
29
<link linkend="char">char</link>* <link linkend="gnome-vfs-escape-slashes">gnome_vfs_escape_slashes</link> (const <link linkend="char">char</link> *string);
30
<link linkend="char">char</link>* <link linkend="gnome-vfs-escape-set">gnome_vfs_escape_set</link> (const <link linkend="char">char</link> *string,
31
const <link linkend="char">char</link> *match_set);
32
<link linkend="char">char</link>* <link linkend="gnome-vfs-unescape-string">gnome_vfs_unescape_string</link> (const <link linkend="char">char</link> *escaped_string,
33
const <link linkend="char">char</link> *illegal_characters);
34
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-uri-canonical">gnome_vfs_make_uri_canonical</link> (const <link linkend="char">char</link> *uri);
35
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-uri-canonical-strip-fragment">gnome_vfs_make_uri_canonical_strip_fragment</link>
36
(const <link linkend="char">char</link> *uri);
37
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-path-name-canonical">gnome_vfs_make_path_name_canonical</link>
38
(const <link linkend="char">char</link> *path);
39
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-uri-from-input">gnome_vfs_make_uri_from_input</link> (const <link linkend="char">char</link> *uri);
40
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-uri-from-input-with-dirs">gnome_vfs_make_uri_from_input_with_dirs</link>
41
(const <link linkend="char">char</link> *uri,
42
<link linkend="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</link> dirs);
43
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-uri-from-shell-arg">gnome_vfs_make_uri_from_shell_arg</link>
44
(const <link linkend="char">char</link> *uri);
45
<link linkend="char">char</link>* <link linkend="gnome-vfs-make-uri-full-from-relative">gnome_vfs_make_uri_full_from_relative</link>
46
(const <link linkend="char">char</link> *base_uri,
47
const <link linkend="char">char</link> *relative_uri);
48
<link linkend="char">char</link>* <link linkend="gnome-vfs-expand-initial-tilde">gnome_vfs_expand_initial_tilde</link> (const <link linkend="char">char</link> *path);
49
<link linkend="char">char</link>* <link linkend="gnome-vfs-unescape-string-for-display">gnome_vfs_unescape_string_for_display</link>
50
(const <link linkend="char">char</link> *escaped);
51
<link linkend="char">char</link>* <link linkend="gnome-vfs-get-local-path-from-uri">gnome_vfs_get_local_path_from_uri</link>
52
(const <link linkend="char">char</link> *uri);
53
<link linkend="char">char</link>* <link linkend="gnome-vfs-get-uri-from-local-path">gnome_vfs_get_uri_from_local_path</link>
54
(const <link linkend="char">char</link> *local_full_path);
55
<link linkend="gboolean">gboolean</link> <link linkend="gnome-vfs-is-executable-command-string">gnome_vfs_is_executable_command_string</link>
56
(const <link linkend="char">char</link> *command_string);
57
<link linkend="void">void</link> <link linkend="gnome-vfs-list-deep-free">gnome_vfs_list_deep_free</link> (<link linkend="GList">GList</link> *list);
58
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-get-volume-free-space">gnome_vfs_get_volume_free_space</link>
59
(const <link linkend="GnomeVFSURI">GnomeVFSURI</link> *vfs_uri,
60
<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *size);
61
<link linkend="char">char</link>* <link linkend="gnome-vfs-icon-path-from-filename">gnome_vfs_icon_path_from_filename</link>
62
(const <link linkend="char">char</link> *filename);
63
<link linkend="gboolean">gboolean</link> <link linkend="gnome-vfs-is-primary-thread">gnome_vfs_is_primary_thread</link> (void);
64
<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);
65
<link linkend="gboolean">gboolean</link> <link linkend="gnome-vfs-uris-match">gnome_vfs_uris_match</link> (const <link linkend="char">char</link> *uri_1,
66
const <link linkend="char">char</link> *uri_2);
67
#define <link linkend="GNOME-VFS-ASSERT-PRIMARY-THREAD-CAPS">GNOME_VFS_ASSERT_PRIMARY_THREAD</link>
68
#define <link linkend="GNOME-VFS-ASSERT-SECONDARY-THREAD-CAPS">GNOME_VFS_ASSERT_SECONDARY_THREAD</link>
69
<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,
70
<link linkend="int">int</link> *file_size,
71
<link linkend="char">char</link> **file_contents);
84
<title>Description</title>
91
<title>Details</title>
93
<title><anchor id="gnome-vfs-format-file-size-for-display"/>gnome_vfs_format_file_size_for_display ()</title>
94
<indexterm><primary>gnome_vfs_format_file_size_for_display</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_format_file_size_for_display
95
(<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> size);</programlisting>
97
Formats the file size passed in <parameter>bytes</parameter> in a way that is easy for
98
the user to read. Gives the size in bytes, kilobytes, megabytes or
99
gigabytes, choosing whatever is appropriate.</para>
102
</para><variablelist role="params">
103
<varlistentry><term><parameter>size</parameter> :</term>
105
</simpara></listitem></varlistentry>
106
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string with the size ready to be shown.
107
</simpara></listitem></varlistentry>
108
</variablelist></refsect2>
110
<title><anchor id="gnome-vfs-format-uri-for-display"/>gnome_vfs_format_uri_for_display ()</title>
111
<indexterm role="2.2"><primary>gnome_vfs_format_uri_for_display</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_format_uri_for_display
112
(const <link linkend="char">char</link> *uri);</programlisting>
114
Filter, modify, unescape and change URIs to make them appropriate
115
to display to users. The conversion is done such that the roundtrip
116
to UTF-8 is reversible.
120
file: URI's without fragments should appear as local paths
121
file: URI's with fragments should appear as file: URI's
122
All other URI's appear as expected
125
<parameter>uri</parameter>: a URI</para>
128
</para><variablelist role="params">
129
<varlistentry><term><parameter>uri</parameter> :</term>
131
</simpara></listitem></varlistentry>
132
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated UTF-8 string
134
</simpara></listitem></varlistentry>
135
</variablelist><para>Since 2.2
138
<title><anchor id="gnome-vfs-url-show"/>gnome_vfs_url_show ()</title>
139
<indexterm role="2.4"><primary>gnome_vfs_url_show</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_url_show (const <link linkend="char">char</link> *url);</programlisting>
141
Launches the default application or component associated with the given url.</para>
144
</para><variablelist role="params">
145
<varlistentry><term><parameter>url</parameter> :</term>
147
</simpara></listitem></varlistentry>
148
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> GNOME_VFS_OK if the default action was launched,
149
GNOME_VFS_ERROR_BAD_PARAMETERS for an invalid or non-existant url,
150
GNOME_VFS_ERROR_NOT_SUPPORTED if no default action is associated with the URL.
151
Also error codes from gnome_vfs_mime_action_launch and
152
gnome_vfs_url_show_using_handler for other errors.
154
</simpara></listitem></varlistentry>
155
</variablelist><para>Since 2.4
158
<title><anchor id="gnome-vfs-url-show-with-env"/>gnome_vfs_url_show_with_env ()</title>
159
<indexterm role="2.4"><primary>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,
160
<link linkend="char">char</link> **envp);</programlisting>
162
Like gnome_vfs_url_show except that the default action will be launched
163
with the given environment.</para>
166
</para><variablelist role="params">
167
<varlistentry><term><parameter>url</parameter> :</term>
169
</simpara></listitem></varlistentry>
170
<varlistentry><term><parameter>envp</parameter> :</term>
172
</simpara></listitem></varlistentry>
173
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> GNOME_VFS_OK if the default action was launched.
175
</simpara></listitem></varlistentry>
176
</variablelist><para>Since 2.4
179
<title><anchor id="gnome-vfs-escape-string"/>gnome_vfs_escape_string ()</title>
180
<indexterm><primary>gnome_vfs_escape_string</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_escape_string (const <link linkend="char">char</link> *string);</programlisting>
182
Escapes <parameter>string</parameter>, replacing any and all special characters
183
with equivalent escape sequences.</para>
186
</para><variablelist role="params">
187
<varlistentry><term><parameter>string</parameter> :</term>
188
<listitem><simpara> string to be escaped
189
</simpara></listitem></varlistentry>
190
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string equivalent to <parameter>string</parameter>
191
but with all special characters escaped
192
</simpara></listitem></varlistentry>
193
</variablelist></refsect2>
195
<title><anchor id="gnome-vfs-escape-path-string"/>gnome_vfs_escape_path_string ()</title>
196
<indexterm><primary>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>
198
Escapes <parameter>path</parameter>, replacing only special characters that would not
199
be found in paths (so '/', '&', '=', and '?' will not be escaped by
200
this function).</para>
203
</para><variablelist role="params">
204
<varlistentry><term><parameter>path</parameter> :</term>
205
<listitem><simpara> string to be escaped
206
</simpara></listitem></varlistentry>
207
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string equivalent to <parameter>path</parameter> but
208
with non-path characters escaped
209
</simpara></listitem></varlistentry>
210
</variablelist></refsect2>
212
<title><anchor id="gnome-vfs-escape-host-and-path-string"/>gnome_vfs_escape_host_and_path_string ()</title>
213
<indexterm><primary>gnome_vfs_escape_host_and_path_string</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_escape_host_and_path_string
214
(const <link linkend="char">char</link> *path);</programlisting>
216
Escapes <parameter>path</parameter>, replacing only special characters that would not
217
be found in paths or host name (so '/', '&', '=', ':', '@'
218
and '?' will not be escaped by this function).</para>
221
</para><variablelist role="params">
222
<varlistentry><term><parameter>path</parameter> :</term>
223
<listitem><simpara> string to be escaped
224
</simpara></listitem></varlistentry>
225
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string equivalent to <parameter>path</parameter> but
226
with non-path/host characters escaped
227
</simpara></listitem></varlistentry>
228
</variablelist></refsect2>
230
<title><anchor id="gnome-vfs-escape-slashes"/>gnome_vfs_escape_slashes ()</title>
231
<indexterm><primary>gnome_vfs_escape_slashes</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_escape_slashes (const <link linkend="char">char</link> *string);</programlisting>
233
Escapes only '/' and '%' characters in <parameter>string</parameter>, replacing
234
them with their escape sequence equivalents.</para>
237
</para><variablelist role="params">
238
<varlistentry><term><parameter>string</parameter> :</term>
239
<listitem><simpara> string to be escaped
240
</simpara></listitem></varlistentry>
241
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string equivalent to <parameter>string</parameter>,
242
but with no unescaped '/' or '%' characters
243
</simpara></listitem></varlistentry>
244
</variablelist></refsect2>
246
<title><anchor id="gnome-vfs-escape-set"/>gnome_vfs_escape_set ()</title>
247
<indexterm><primary>gnome_vfs_escape_set</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_escape_set (const <link linkend="char">char</link> *string,
248
const <link linkend="char">char</link> *match_set);</programlisting>
251
</para><variablelist role="params">
252
<varlistentry><term><parameter>string</parameter> :</term>
254
</simpara></listitem></varlistentry>
255
<varlistentry><term><parameter>match_set</parameter> :</term>
257
</simpara></listitem></varlistentry>
258
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
261
</simpara></listitem></varlistentry>
262
</variablelist></refsect2>
264
<title><anchor id="gnome-vfs-unescape-string"/>gnome_vfs_unescape_string ()</title>
265
<indexterm><primary>gnome_vfs_unescape_string</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_unescape_string (const <link linkend="char">char</link> *escaped_string,
266
const <link linkend="char">char</link> *illegal_characters);</programlisting>
268
Decodes escaped characters (i.e. PERCENTxx sequences) in <parameter>escaped_string</parameter>.
269
Characters are encoded in PERCENTxy form, where xy is the ASCII hex code
270
for character 16x+y.</para>
273
</para><variablelist role="params">
274
<varlistentry><term><parameter>escaped_string</parameter> :</term>
275
<listitem><simpara> an escaped URI, path, or other string
276
</simpara></listitem></varlistentry>
277
<varlistentry><term><parameter>illegal_characters</parameter> :</term>
278
<listitem><simpara> a string containing a sequence of characters
279
considered "illegal", '\0' is automatically in this list.
280
</simpara></listitem></varlistentry>
281
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string with the unescaped equivalents,
282
or <literal>NULL</literal> if <parameter>escaped_string</parameter> contained one of the characters
283
in <parameter>illegal_characters</parameter>.
284
</simpara></listitem></varlistentry>
285
</variablelist></refsect2>
287
<title><anchor id="gnome-vfs-make-uri-canonical"/>gnome_vfs_make_uri_canonical ()</title>
288
<indexterm role="2.2"><primary>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>
290
Standarizes the format of the uri being passed, so that it can be used
291
later in other functions that expect a canonical URI.</para>
294
</para><variablelist role="params">
295
<varlistentry><term><parameter>uri</parameter> :</term>
296
<listitem><simpara> and absolute or relative URI, it might have scheme.
297
</simpara></listitem></varlistentry>
298
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string that contains the canonical
299
representation of <parameter>uri</parameter>.
301
</simpara></listitem></varlistentry>
302
</variablelist><para>Since 2.2
305
<title><anchor id="gnome-vfs-make-uri-canonical-strip-fragment"/>gnome_vfs_make_uri_canonical_strip_fragment ()</title>
306
<indexterm role="2.2"><primary>gnome_vfs_make_uri_canonical_strip_fragment</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_make_uri_canonical_strip_fragment
307
(const <link linkend="char">char</link> *uri);</programlisting>
309
If the <parameter>uri</parameter> passed contains a fragment (anything after a '#') strips if,
310
then makes the URI canonical.</para>
313
</para><variablelist role="params">
314
<varlistentry><term><parameter>uri</parameter> :</term>
316
</simpara></listitem></varlistentry>
317
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing a canonical URI.
319
</simpara></listitem></varlistentry>
320
</variablelist><para>Since 2.2
323
<title><anchor id="gnome-vfs-make-path-name-canonical"/>gnome_vfs_make_path_name_canonical ()</title>
324
<indexterm><primary>gnome_vfs_make_path_name_canonical</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_make_path_name_canonical
325
(const <link linkend="char">char</link> *path);</programlisting>
327
Calls _gnome_vfs_canonicalize_pathname, allocating storage for the
328
result and providing for a cleaner memory management.</para>
331
</para><variablelist role="params">
332
<varlistentry><term><parameter>path</parameter> :</term>
333
<listitem><simpara> a file path, relative or absolute
334
</simpara></listitem></varlistentry>
335
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a canonical version of <parameter>path</parameter>
336
</simpara></listitem></varlistentry>
337
</variablelist></refsect2>
339
<title><anchor id="gnome-vfs-make-uri-from-input"/>gnome_vfs_make_uri_from_input ()</title>
340
<indexterm role="2.2"><primary>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> *uri);</programlisting>
342
Takes a user input path/URI and makes a valid URI out of it.
345
This function is the reverse of gnome_vfs_format_uri_for_display
346
but it also handles the fact that the user could have typed
347
arbitrary UTF8 in the entry showing the string.</para>
350
</para><variablelist role="params">
351
<varlistentry><term><parameter>uri</parameter> :</term>
352
<listitem><simpara> a possibly mangled "uri", in UTF8
353
</simpara></listitem></varlistentry>
354
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated uri.
356
</simpara></listitem></varlistentry>
357
</variablelist><para>Since 2.2
360
<title><anchor id="gnome-vfs-make-uri-from-input-with-dirs"/>gnome_vfs_make_uri_from_input_with_dirs ()</title>
361
<indexterm role="2.4"><primary>gnome_vfs_make_uri_from_input_with_dirs</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_make_uri_from_input_with_dirs
362
(const <link linkend="char">char</link> *uri,
363
<link linkend="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</link> dirs);</programlisting>
365
Determines a fully qualified URL from a relative or absolute input path.
366
Basically calls gnome_vfs_make_uri_from_input except it specifically
367
tries to support paths relative to the specified directories (can be homedir
368
and/or current directory).</para>
371
</para><variablelist role="params">
372
<varlistentry><term><parameter>uri</parameter> :</term>
373
<listitem><simpara> a relative or absolute path
374
</simpara></listitem></varlistentry>
375
<varlistentry><term><parameter>dirs</parameter> :</term>
376
<listitem><simpara> directory to use as a base directory if <parameter>uri</parameter> is a relative path.
377
</simpara></listitem></varlistentry>
378
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the fully qualified URL
380
</simpara></listitem></varlistentry>
381
</variablelist><para>Since 2.4
384
<title><anchor id="gnome-vfs-make-uri-from-shell-arg"/>gnome_vfs_make_uri_from_shell_arg ()</title>
385
<indexterm role="2.2"><primary>gnome_vfs_make_uri_from_shell_arg</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_make_uri_from_shell_arg
386
(const <link linkend="char">char</link> *uri);</programlisting>
388
Similar to gnome_vfs_make_uri_from_input, except that:
391
1) guesses relative paths instead of http domains
392
2) doesn't bother stripping leading/trailing white space
393
3) doesn't bother with ~ expansion--that's done by the shell</para>
396
</para><variablelist role="params">
397
<varlistentry><term><parameter>uri</parameter> :</term>
398
<listitem><simpara> a possibly mangled "uri"
399
</simpara></listitem></varlistentry>
400
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated uri
402
</simpara></listitem></varlistentry>
403
</variablelist><para>Since 2.2
406
<title><anchor id="gnome-vfs-make-uri-full-from-relative"/>gnome_vfs_make_uri_full_from_relative ()</title>
407
<indexterm role="2.2"><primary>gnome_vfs_make_uri_full_from_relative</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_make_uri_full_from_relative
408
(const <link linkend="char">char</link> *base_uri,
409
const <link linkend="char">char</link> *relative_uri);</programlisting>
411
Returns a full URI given a full base URI, and a secondary URI which may
415
This function is deprecated, please use
416
gnome_vfs_uri_make_full_from_relative from gnome-vfs-uri.h</para>
419
</para><variablelist role="params">
420
<varlistentry><term><parameter>base_uri</parameter> :</term>
421
<listitem><simpara> uri to use as the base for the full uri
422
</simpara></listitem></varlistentry>
423
<varlistentry><term><parameter>relative_uri</parameter> :</term>
424
<listitem><simpara> full or relative path to append to the base uri
425
</simpara></listitem></varlistentry>
426
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the URI (NULL for some bad errors).
428
</simpara></listitem></varlistentry>
429
</variablelist><para>Since 2.2
432
<title><anchor id="gnome-vfs-expand-initial-tilde"/>gnome_vfs_expand_initial_tilde ()</title>
433
<indexterm><primary>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>
435
If <parameter>path</parameter> starts with a ~, representing the user's home
436
directory, expand it to the actual path location.</para>
439
</para><variablelist role="params">
440
<varlistentry><term><parameter>path</parameter> :</term>
441
<listitem><simpara> a local file path which may start with a '~'
442
</simpara></listitem></varlistentry>
443
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string with the initial
444
tilde (if there was one) converted to an actual path
445
</simpara></listitem></varlistentry>
446
</variablelist></refsect2>
448
<title><anchor id="gnome-vfs-unescape-string-for-display"/>gnome_vfs_unescape_string_for_display ()</title>
449
<indexterm><primary>gnome_vfs_unescape_string_for_display</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_unescape_string_for_display
450
(const <link linkend="char">char</link> *escaped);</programlisting>
453
</para><variablelist role="params">
454
<varlistentry><term><parameter>escaped</parameter> :</term>
456
</simpara></listitem></varlistentry>
457
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
460
</simpara></listitem></varlistentry>
461
</variablelist></refsect2>
463
<title><anchor id="gnome-vfs-get-local-path-from-uri"/>gnome_vfs_get_local_path_from_uri ()</title>
464
<indexterm><primary>gnome_vfs_get_local_path_from_uri</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_get_local_path_from_uri
465
(const <link linkend="char">char</link> *uri);</programlisting>
467
Create a local path for a file:/// URI. Do not use with URIs
468
of other methods.</para>
471
</para><variablelist role="params">
472
<varlistentry><term><parameter>uri</parameter> :</term>
473
<listitem><simpara> URI to convert to a local path
474
</simpara></listitem></varlistentry>
475
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the local path
476
NULL is returned on error or if the uri isn't a file: URI
477
without a fragment identifier (or chained URI).
478
</simpara></listitem></varlistentry>
479
</variablelist></refsect2>
481
<title><anchor id="gnome-vfs-get-uri-from-local-path"/>gnome_vfs_get_uri_from_local_path ()</title>
482
<indexterm><primary>gnome_vfs_get_uri_from_local_path</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_get_uri_from_local_path
483
(const <link linkend="char">char</link> *local_full_path);</programlisting>
485
Returns a file:/// URI for the local path <parameter>local_full_path</parameter>.</para>
488
</para><variablelist role="params">
489
<varlistentry><term><parameter>local_full_path</parameter> :</term>
490
<listitem><simpara> a full local filesystem path (i.e. not relative)
491
</simpara></listitem></varlistentry>
492
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string containing the URI corresponding
493
to <parameter>local_full_path</parameter> (NULL for some bad errors).
494
</simpara></listitem></varlistentry>
495
</variablelist></refsect2>
497
<title><anchor id="gnome-vfs-is-executable-command-string"/>gnome_vfs_is_executable_command_string ()</title>
498
<indexterm><primary>gnome_vfs_is_executable_command_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_is_executable_command_string
499
(const <link linkend="char">char</link> *command_string);</programlisting>
501
Checks if <parameter>command_string</parameter> starts with the full path of an executable file
502
or an executable in $PATH.</para>
505
</para><variablelist role="params">
506
<varlistentry><term><parameter>command_string</parameter> :</term>
508
</simpara></listitem></varlistentry>
509
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if command_string started with and executable file,
511
</simpara></listitem></varlistentry>
512
</variablelist></refsect2>
514
<title><anchor id="gnome-vfs-list-deep-free"/>gnome_vfs_list_deep_free ()</title>
515
<indexterm><primary>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>
517
Free <parameter>list</parameter>, and call <link linkend="g-free"><function>g_free()</function></link> on all data members.</para>
520
</para><variablelist role="params">
521
<varlistentry><term><parameter>list</parameter> :</term>
522
<listitem><simpara> list to be freed
523
</simpara></listitem></varlistentry>
524
</variablelist></refsect2>
526
<title><anchor id="gnome-vfs-get-volume-free-space"/>gnome_vfs_get_volume_free_space ()</title>
527
<indexterm><primary>gnome_vfs_get_volume_free_space</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_get_volume_free_space
528
(const <link linkend="GnomeVFSURI">GnomeVFSURI</link> *vfs_uri,
529
<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *size);</programlisting>
531
Stores in <parameter>size</parameter> the amount of free space on a volume.
532
This only works for URIs with the file: scheme.</para>
535
</para><variablelist role="params">
536
<varlistentry><term><parameter>vfs_uri</parameter> :</term>
538
</simpara></listitem></varlistentry>
539
<varlistentry><term><parameter>size</parameter> :</term>
541
</simpara></listitem></varlistentry>
542
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> GNOME_VFS_OK on success, otherwise an error code
543
</simpara></listitem></varlistentry>
544
</variablelist></refsect2>
546
<title><anchor id="gnome-vfs-icon-path-from-filename"/>gnome_vfs_icon_path_from_filename ()</title>
547
<indexterm><primary>gnome_vfs_icon_path_from_filename</primary></indexterm><programlisting><link linkend="char">char</link>* gnome_vfs_icon_path_from_filename
548
(const <link linkend="char">char</link> *filename);</programlisting>
551
</para><variablelist role="params">
552
<varlistentry><term><parameter>filename</parameter> :</term>
554
</simpara></listitem></varlistentry>
555
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
558
</simpara></listitem></varlistentry>
559
</variablelist></refsect2>
561
<title><anchor id="gnome-vfs-is-primary-thread"/>gnome_vfs_is_primary_thread ()</title>
562
<indexterm><primary>gnome_vfs_is_primary_thread</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_is_primary_thread (void);</programlisting>
564
Check if the current thread is the thread with the main glib event loop.</para>
567
</para><variablelist role="params">
568
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the current thread is the thread with the
570
</simpara></listitem></varlistentry>
571
</variablelist></refsect2>
573
<title><anchor id="gnome-vfs-get-uri-scheme"/>gnome_vfs_get_uri_scheme ()</title>
574
<indexterm role="2.2"><primary>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>
576
Retrieve the scheme used in <parameter>uri</parameter></para>
579
</para><variablelist role="params">
580
<varlistentry><term><parameter>uri</parameter> :</term>
581
<listitem><simpara> a stringified URI
582
</simpara></listitem></varlistentry>
583
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A newly allocated string containing the scheme, NULL
584
if <parameter>uri</parameter> it doesn't seem to contain a scheme
586
</simpara></listitem></varlistentry>
587
</variablelist><para>Since 2.2
590
<title><anchor id="gnome-vfs-uris-match"/>gnome_vfs_uris_match ()</title>
591
<indexterm role="2.2"><primary>gnome_vfs_uris_match</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gnome_vfs_uris_match (const <link linkend="char">char</link> *uri_1,
592
const <link linkend="char">char</link> *uri_2);</programlisting>
594
Compare two URIs.</para>
597
</para><variablelist role="params">
598
<varlistentry><term><parameter>uri_1</parameter> :</term>
599
<listitem><simpara> stringified URI to compare with <parameter>uri_2</parameter>.
600
</simpara></listitem></varlistentry>
601
<varlistentry><term><parameter>uri_2</parameter> :</term>
602
<listitem><simpara> stringified URI to compare with <parameter>uri_1</parameter>.
603
</simpara></listitem></varlistentry>
604
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if they are the same, FALSE otherwise.
606
</simpara></listitem></varlistentry>
607
</variablelist><para>Since 2.2
610
<title><anchor id="GNOME-VFS-ASSERT-PRIMARY-THREAD-CAPS"/>GNOME_VFS_ASSERT_PRIMARY_THREAD</title>
611
<indexterm><primary>GNOME_VFS_ASSERT_PRIMARY_THREAD</primary></indexterm><programlisting>#define GNOME_VFS_ASSERT_PRIMARY_THREAD g_assert (gnome_vfs_is_primary_thread())
614
Asserts that the current thread is the thread with
615
the main glib event loop</para>
620
<title><anchor id="GNOME-VFS-ASSERT-SECONDARY-THREAD-CAPS"/>GNOME_VFS_ASSERT_SECONDARY_THREAD</title>
621
<indexterm><primary>GNOME_VFS_ASSERT_SECONDARY_THREAD</primary></indexterm><programlisting>#define GNOME_VFS_ASSERT_SECONDARY_THREAD g_assert (!gnome_vfs_is_primary_thread())
624
Asserts that the current thread is NOT the thread with
625
the main glib event loop</para>
630
<title><anchor id="gnome-vfs-read-entire-file"/>gnome_vfs_read_entire_file ()</title>
631
<indexterm role="2.2"><primary>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,
632
<link linkend="int">int</link> *file_size,
633
<link linkend="char">char</link> **file_contents);</programlisting>
635
Reads an entire file into memory for convenience. Beware accidentally
636
loading large files into memory with this function.</para>
639
</para><variablelist role="params">
640
<varlistentry><term><parameter>uri</parameter> :</term>
641
<listitem><simpara> URI of the file to read
642
</simpara></listitem></varlistentry>
643
<varlistentry><term><parameter>file_size</parameter> :</term>
644
<listitem><simpara> after reading the file, contains the size of the file read
645
</simpara></listitem></varlistentry>
646
<varlistentry><term><parameter>file_contents</parameter> :</term>
647
<listitem><simpara> contains the file_size bytes, the contents of the file at <parameter>uri</parameter>.
648
</simpara></listitem></varlistentry>
649
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
651
</simpara></listitem></varlistentry>
652
</variablelist><para>Since 2.2