<refentry id="gnome-vfs-20-gnome-vfs-utils">
<refmeta>
<refentrytitle id="top_of_page">gnome-vfs-utils</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gnome-vfs-utils</refname>
<refpurpose>various utilities functions to manipulate uris</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>

<synopsis>



enum        <link linkend="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</link>;
<link linkend="char">char</link>*       <link linkend="gnome-vfs-format-file-size-for-display">gnome_vfs_format_file_size_for_display</link>
                                            (<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> size);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-format-uri-for-display">gnome_vfs_format_uri_for_display</link>
                                            (const <link linkend="char">char</link> *uri);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-url-show">gnome_vfs_url_show</link>           (const <link linkend="char">char</link> *url);
<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,
                                             <link linkend="char">char</link> **envp);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-escape-string">gnome_vfs_escape_string</link>         (const <link linkend="char">char</link> *string);
<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);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-escape-host-and-path-string">gnome_vfs_escape_host_and_path_string</link>
                                            (const <link linkend="char">char</link> *path);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-escape-slashes">gnome_vfs_escape_slashes</link>        (const <link linkend="char">char</link> *string);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-escape-set">gnome_vfs_escape_set</link>            (const <link linkend="char">char</link> *string,
                                             const <link linkend="char">char</link> *match_set);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-unescape-string">gnome_vfs_unescape_string</link>       (const <link linkend="char">char</link> *escaped_string,
                                             const <link linkend="char">char</link> *illegal_characters);
<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);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-make-uri-canonical-strip-fragment">gnome_vfs_make_uri_canonical_strip_fragment</link>
                                            (const <link linkend="char">char</link> *uri);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-make-path-name-canonical">gnome_vfs_make_path_name_canonical</link>
                                            (const <link linkend="char">char</link> *path);
<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> *location);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-make-uri-from-input-with-dirs">gnome_vfs_make_uri_from_input_with_dirs</link>
                                            (const <link linkend="char">char</link> *location,
                                             <link linkend="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</link> dirs);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-make-uri-from-shell-arg">gnome_vfs_make_uri_from_shell_arg</link>
                                            (const <link linkend="char">char</link> *uri);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-make-uri-full-from-relative">gnome_vfs_make_uri_full_from_relative</link>
                                            (const <link linkend="char">char</link> *base_uri,
                                             const <link linkend="char">char</link> *relative_uri);
<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);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-unescape-string-for-display">gnome_vfs_unescape_string_for_display</link>
                                            (const <link linkend="char">char</link> *escaped);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-get-local-path-from-uri">gnome_vfs_get_local_path_from_uri</link>
                                            (const <link linkend="char">char</link> *uri);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-get-uri-from-local-path">gnome_vfs_get_uri_from_local_path</link>
                                            (const <link linkend="char">char</link> *local_full_path);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-vfs-is-executable-command-string">gnome_vfs_is_executable_command_string</link>
                                            (const <link linkend="char">char</link> *command_string);
<link linkend="void">void</link>        <link linkend="gnome-vfs-list-deep-free">gnome_vfs_list_deep_free</link>        (<link linkend="GList">GList</link> *list);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-get-volume-free-space">gnome_vfs_get_volume_free_space</link>
                                            (const <link linkend="GnomeVFSURI">GnomeVFSURI</link> *vfs_uri,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *size);
<link linkend="char">char</link>*       <link linkend="gnome-vfs-icon-path-from-filename">gnome_vfs_icon_path_from_filename</link>
                                            (const <link linkend="char">char</link> *filename);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-vfs-is-primary-thread">gnome_vfs_is_primary_thread</link>     (void);
<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);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-vfs-uris-match">gnome_vfs_uris_match</link>            (const <link linkend="char">char</link> *uri_1,
                                             const <link linkend="char">char</link> *uri_2);
#define     <link linkend="GNOME-VFS-ASSERT-PRIMARY-THREAD:CAPS">GNOME_VFS_ASSERT_PRIMARY_THREAD</link>
#define     <link linkend="GNOME-VFS-ASSERT-SECONDARY-THREAD:CAPS">GNOME_VFS_ASSERT_SECONDARY_THREAD</link>
<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,
                                             <link linkend="int">int</link> *file_size,
                                             <link linkend="char">char</link> **file_contents);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="GnomeVFSMakeURIDirs" role="enum"/>enum GnomeVFSMakeURIDirs</title>
<indexterm><primary>GnomeVFSMakeURIDirs</primary></indexterm><programlisting>typedef enum {
	GNOME_VFS_MAKE_URI_DIR_NONE = 0,
	GNOME_VFS_MAKE_URI_DIR_HOMEDIR = 1 &lt;&lt; 0,
	GNOME_VFS_MAKE_URI_DIR_CURRENT = 1 &lt;&lt; 1
} GnomeVFSMakeURIDirs;
</programlisting>
<para>
Flags that can be passed to <link linkend="gnome-vfs-make-uri-from-input-with-dirs"><function>gnome_vfs_make_uri_from_input_with_dirs()</function></link>.
If the given input might be a relative path it checks for existence of the file
in the directory specified by this flag.
If both flags are passed the current directory is checked first.</para>
<para>

</para><variablelist role="enum">
<varlistentry>
<term><literal>GNOME_VFS_MAKE_URI_DIR_NONE</literal></term>
<listitem><simpara> Don't check any directory
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GNOME_VFS_MAKE_URI_DIR_HOMEDIR</literal></term>
<listitem><simpara> Check the home directory
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GNOME_VFS_MAKE_URI_DIR_CURRENT</literal></term>
<listitem><simpara> Check the current direcotry
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-format-file-size-for-display" role="function"/>gnome_vfs_format_file_size_for_display ()</title>
<indexterm><primary>gnome_vfs_format_file_size_for_display</primary></indexterm><programlisting><link linkend="char">char</link>*       gnome_vfs_format_file_size_for_display
                                            (<link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> size);</programlisting>
<para>
Formats the file <parameter>size</parameter> passed so that it is easy for
the user to read. Gives the size in bytes, kilobytes, megabytes or
gigabytes, choosing whatever is appropriate.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSFileSize"><type>GnomeVFSFileSize</type></link> (a <link linkend="guint64"><type>guint64</type></link> value).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string with the size ready to be shown.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-format-uri-for-display" role="function" condition="since:2.2"/>gnome_vfs_format_uri_for_display ()</title>
<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
                                            (const <link linkend="char">char</link> *uri);</programlisting>
<para>
Filter, modify, unescape and change <parameter>uri</parameter> to make it appropriate
for display to users. The conversion is done such that the roundtrip
to UTF-8 is reversible.
</para>
<para>
Rules:
	file: uri without fragments should appear as local paths.
	file: uri with fragments should appear as file:uri.
	All other uri appear as expected.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> uri to be displayed.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a string which represents <parameter>uri</parameter> and can be displayed.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-url-show" role="function" condition="since:2.4"/>gnome_vfs_url_show ()</title>
<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>
<para>
Launches the default application or component associated with the given <parameter>url</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> url to be shown.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>GNOME_VFS_OK</literal> if the default action was launched,
<literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal> for an invalid or non-existant <parameter>url</parameter>,
<literal>GNOME_VFS_ERROR_NO_DEFAULT</literal> if no default action is associated with the <parameter>url</parameter>.
Also error codes from <link linkend="gnome-vfs-mime-action-launch"><function>gnome_vfs_mime_action_launch()</function></link>
or <link linkend="gnome-vfs-mime-action-launch-with-env"><function>gnome_vfs_mime_action_launch_with_env()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.4
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-url-show-with-env" role="function" condition="since:2.4"/>gnome_vfs_url_show_with_env ()</title>
<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,
                                             <link linkend="char">char</link> **envp);</programlisting>
<para>
Like <link linkend="gnome-vfs-url-show"><function>gnome_vfs_url_show()</function></link> except that the default action will be launched
with the given environment.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> url to be shown.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>envp</parameter>&nbsp;:</term>
<listitem><simpara> environment data.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>GNOME_VFS_OK</literal> if the default action was launched.
<literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal> for an invalid or non-existant <parameter>url</parameter>,
<literal>GNOME_VFS_ERROR_NO_DEFAULT</literal> if no default action is associated with the <parameter>url</parameter>.
Also error codes from <link linkend="gnome-vfs-mime-application-launch-with-env"><function>gnome_vfs_mime_application_launch_with_env()</function></link>
or <link linkend="gnome-vfs-mime-action-launch-with-env"><function>gnome_vfs_mime_action_launch_with_env()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.4
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-escape-string" role="function"/>gnome_vfs_escape_string ()</title>
<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>
<para>
Escapes <parameter>string</parameter>, replacing any and all special characters 
with equivalent escape sequences.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to be escaped.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string equivalent to <parameter>string</parameter>
but with all special characters escaped.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-escape-path-string" role="function"/>gnome_vfs_escape_path_string ()</title>
<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>
<para>
Escapes <parameter>path</parameter>, replacing only special characters that would not
be found in paths (so '/', '&amp;', '=', and '?' will not be escaped by
this function).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> string to be escaped.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string equivalent to <parameter>path</parameter> but
with non-path characters escaped.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-escape-host-and-path-string" role="function"/>gnome_vfs_escape_host_and_path_string ()</title>
<indexterm><primary>gnome_vfs_escape_host_and_path_string</primary></indexterm><programlisting><link linkend="char">char</link>*       gnome_vfs_escape_host_and_path_string
                                            (const <link linkend="char">char</link> *path);</programlisting>
<para>
Escapes <parameter>path</parameter>, replacing only special characters that would not
be found in paths or host name (so '/', '&amp;', '=', ':', '@' 
and '?' will not be escaped by this function).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> string to be escaped.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string equivalent to <parameter>path</parameter> but
with non-path/host characters escaped.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-escape-slashes" role="function"/>gnome_vfs_escape_slashes ()</title>
<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>
<para>
Escapes only '/' and '%' characters in <parameter>string</parameter>, replacing
them with their escape sequence equivalents.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to be escaped.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string equivalent to <parameter>string</parameter>,
but with no unescaped '/' or '%' characters.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-escape-set" role="function"/>gnome_vfs_escape_set ()</title>
<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,
                                             const <link linkend="char">char</link> *match_set);</programlisting>
<para>
Escapes all characters in <parameter>string</parameter> which are listed in <parameter>match_set</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to be escaped.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>match_set</parameter>&nbsp;:</term>
<listitem><simpara> a string containing all characters to be escaped in <parameter>string</parameter>. 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string equivalent to <parameter>string</parameter> but 
with characters in <parameter>match_string</parameter> escaped.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-unescape-string" role="function"/>gnome_vfs_unescape_string ()</title>
<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,
                                             const <link linkend="char">char</link> *illegal_characters);</programlisting>
<para>
Decodes escaped characters (i.e. PERCENTxx sequences) in <parameter>escaped_string</parameter>.
Characters are encoded in PERCENTxy form, where xy is the ASCII hex code 
for character 16x+y.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>escaped_string</parameter>&nbsp;:</term>
<listitem><simpara> an escaped uri, path, or other string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>illegal_characters</parameter>&nbsp;:</term>
<listitem><simpara> a string containing a sequence of characters
considered "illegal" to be escaped, '\0' is automatically in this list.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string with the unescaped
equivalents, or <literal>NULL</literal> if <parameter>escaped_string</parameter> contained an escaped
encoding of one of the characters in <parameter>illegal_characters</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-uri-canonical" role="function" condition="since:2.2"/>gnome_vfs_make_uri_canonical ()</title>
<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>
<para>
Standardizes the format of the <parameter>uri</parameter>, so that it can be used
later in other functions that expect a canonical uri.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> an absolute or relative stringified uri. It might have scheme.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string that contains the canonical 
representation of <parameter>uri</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-uri-canonical-strip-fragment" role="function" condition="since:2.2"/>gnome_vfs_make_uri_canonical_strip_fragment ()</title>
<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
                                            (const <link linkend="char">char</link> *uri);</programlisting>
<para>
Returns a canonicalized uri. If <parameter>uri</parameter> contains a fragment (anything after a '#') strips off that and
then makes the <parameter>uri</parameter> canonical.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSURI"><type>GnomeVFSURI</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string containing a canonical <parameter>uri</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-path-name-canonical" role="function"/>gnome_vfs_make_path_name_canonical ()</title>
<indexterm><primary>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>
<para>
Calls <link linkend="gnome-vfs-canonicalize-pathname"><function>_gnome_vfs_canonicalize_pathname()</function></link>, allocating storage for the 
result and providing for a cleaner memory management.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> a file path, relative or absolute.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a canonical version of <parameter>path</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-uri-from-input" role="function" condition="since:2.2"/>gnome_vfs_make_uri_from_input ()</title>
<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> *location);</programlisting>
<para>
Takes a user input path/uri and makes a valid uri out of it.
</para>
<para>
This function is the reverse of <link linkend="gnome-vfs-format-uri-for-display"><function>gnome_vfs_format_uri_for_display()</function></link>
but it also handles the fact that the user could have typed
arbitrary UTF-8 in the entry showing the string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>location</parameter>&nbsp;:</term>
<listitem><simpara> a possibly mangled "uri", in UTF-8.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated uri.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-uri-from-input-with-dirs" role="function" condition="since:2.4"/>gnome_vfs_make_uri_from_input_with_dirs ()</title>
<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
                                            (const <link linkend="char">char</link> *location,
                                             <link linkend="GnomeVFSMakeURIDirs">GnomeVFSMakeURIDirs</link> dirs);</programlisting>
<para>
Determines a fully qualified uri from a relative or absolute input path.
Basically calls <link linkend="gnome-vfs-make-uri-from-input"><function>gnome_vfs_make_uri_from_input()</function></link> except it specifically
tries to support paths relative to the specified directories (can be homedir
and/or current directory). See <link linkend="GnomeVFSMakeURIDirs"><type>GnomeVFSMakeURIDirs</type></link> for more information.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>location</parameter>&nbsp;:</term>
<listitem><simpara> a relative or absolute path.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dirs</parameter>&nbsp;:</term>
<listitem><simpara> directory to use as a base directory if <parameter>location</parameter> is a relative path.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string containing the fully qualified uri.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.4
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-uri-from-shell-arg" role="function" condition="since:2.2"/>gnome_vfs_make_uri_from_shell_arg ()</title>
<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
                                            (const <link linkend="char">char</link> *uri);</programlisting>
<para>
Similar to <link linkend="gnome-vfs-make-uri-from-input"><function>gnome_vfs_make_uri_from_input()</function></link>, except that:
</para>
<para>
1) guesses relative paths instead of http domains.
2) doesn't bother stripping leading/trailing white space.
3) doesn't bother with ~ expansion--that's done by the shell.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> path to make the uri from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string representing <parameter>uri</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-make-uri-full-from-relative" role="function" condition="deprecated|since:2.2"/>gnome_vfs_make_uri_full_from_relative ()</title>
<indexterm role="deprecated 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
                                            (const <link linkend="char">char</link> *base_uri,
                                             const <link linkend="char">char</link> *relative_uri);</programlisting>
<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 
<link linkend="gnome-vfs-uri-make-full-from-relative"><function>gnome_vfs_uri_make_full_from_relative()</function></link> from gnome-vfs-uri.h .</para></warning>
<para>
Returns a string representing the full uri given a full <parameter>base_uri</parameter> and a 
secondary uri which may be relative.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>base_uri</parameter>&nbsp;:</term>
<listitem><simpara> path to use as the base for the full uri.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>relative_uri</parameter>&nbsp;:</term>
<listitem><simpara> full or relative path to be appended to the <parameter>base_uri</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string containing the uri.
(<literal>NULL</literal> for some bad errors).

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-expand-initial-tilde" role="function"/>gnome_vfs_expand_initial_tilde ()</title>
<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>
<para>
If <parameter>path</parameter> starts with a ~, representing the user's home
directory, expand it to the actual path location.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> a local file path which may start with a '~'.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string with the initial
tilde (if there was one) converted to an actual path.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-unescape-string-for-display" role="function"/>gnome_vfs_unescape_string_for_display ()</title>
<indexterm><primary>gnome_vfs_unescape_string_for_display</primary></indexterm><programlisting><link linkend="char">char</link>*       gnome_vfs_unescape_string_for_display
                                            (const <link linkend="char">char</link> *escaped);</programlisting>
<para>
Similar to gnome_vfs_unescape_string, but it returns something
semi-intelligable to a user even upon receiving traumatic input
such as <literal>00</literal> or URIs in bad form.
</para>
<para>
See also: <link linkend="gnome-vfs-unescape-string"><function>gnome_vfs_unescape_string()</function></link>.
</para>
<para>
WARNING: You should never use this function on a whole URI!  It
unescapes reserved characters, and can result in a mangled URI
that can not be re-entered.  For example, it unescapes "#" "&amp;" and "?",
which have special meanings in URI strings.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>escaped</parameter>&nbsp;:</term>
<listitem><simpara> a string encoded with escaped sequences.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a pointer to a g_malloc'd string with all characters
replacing their escaped hex values.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-get-local-path-from-uri" role="function"/>gnome_vfs_get_local_path_from_uri ()</title>
<indexterm><primary>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>
<para>
Create a local path for a file:/// uri. Do not use with uris
of other methods.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> uri to convert to a local path.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string containing the local path.
<literal>NULL</literal> is returned on error or if the uri isn't a file: uri
without a fragment identifier (or chained uri).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-get-uri-from-local-path" role="function"/>gnome_vfs_get_uri_from_local_path ()</title>
<indexterm><primary>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>
<para>
Returns a file:/// URI for the local path <parameter>local_full_path</parameter>, 
such as a path provided by <link linkend="gtk-file-chooser-get-filename"><function>gtk_file_chooser_get_filename()</function></link>.
The resulting URI may be provided, for instance, to <link linkend="gnome-vfs-uri-new"><function>gnome_vfs_uri_new()</function></link>.
</para>
<para>
On Windows <parameter>local_full_path</parameter> should be in the UTF-8 encoding, and can start with a drive
letter, but doesn't have to.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>local_full_path</parameter>&nbsp;:</term>
<listitem><simpara> a full local filesystem path (i.e. not relative).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string containing the uri corresponding 
to <parameter>local_full_path</parameter> (<literal>NULL</literal> for some bad errors).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-is-executable-command-string" role="function"/>gnome_vfs_is_executable_command_string ()</title>
<indexterm><primary>gnome_vfs_is_executable_command_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_vfs_is_executable_command_string
                                            (const <link linkend="char">char</link> *command_string);</programlisting>
<para>
Checks if <parameter>command_string</parameter> starts with the full path of an executable file
or an executable in $PATH.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>command_string</parameter>&nbsp;:</term>
<listitem><simpara> a string representing a command ie "xterm -bg white".
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>TRUE</literal> if <parameter>command_string</parameter> started with an executable file, and is in $PATH,
<literal>FALSE</literal> otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-list-deep-free" role="function"/>gnome_vfs_list_deep_free ()</title>
<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>
<para>
Free <parameter>list</parameter> and call <link linkend="g-free"><function>g_free()</function></link> on all data members.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>list</parameter>&nbsp;:</term>
<listitem><simpara> list to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-get-volume-free-space" role="function"/>gnome_vfs_get_volume_free_space ()</title>
<indexterm><primary>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,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *size);</programlisting>
<para>
Stores the amount of free space in bytes on <parameter>vfs</parameter>-uri's
volume in <parameter>size</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>vfs_uri</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSURI"><type>GnomeVFSURI</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSFileSize"><type>GnomeVFSFileSize</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>GNOME_VFS_OK</literal> on success, otherwise an
<literal>GNOME_VFS_ERROR_</literal>* code.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-icon-path-from-filename" role="function"/>gnome_vfs_icon_path_from_filename ()</title>
<indexterm><primary>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>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> Returns the icon path for the <parameter>relative_filename</parameter>. Example:
gnome_vfs_icon_path_from_filename ("nautilus/nautilus-desktop.png") will return a string 
forming the full path of the file nautilus-desktop.png ie $PREFIX/share/pixmaps/nautilus/nautilus-desktop.png.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-is-primary-thread" role="function"/>gnome_vfs_is_primary_thread ()</title>
<indexterm><primary>gnome_vfs_is_primary_thread</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_vfs_is_primary_thread     (void);</programlisting>
<para>
Check if the current thread is the thread with the main glib event loop.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>TRUE</literal> if the current thread is the thread with the 
main glib event loop.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-get-uri-scheme" role="function" condition="since:2.2"/>gnome_vfs_get_uri_scheme ()</title>
<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>
<para>
Retrieve the scheme used in <parameter>uri</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> a stringified uri.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string containing the scheme, <literal>NULL</literal>
if <parameter>uri</parameter> doesn't contain a scheme.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-uris-match" role="function" condition="since:2.2"/>gnome_vfs_uris_match ()</title>
<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,
                                             const <link linkend="char">char</link> *uri_2);</programlisting>
<para>
Compare two uris.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_1</parameter>&nbsp;:</term>
<listitem><simpara> stringified uri to compare with <parameter>uri_2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri_2</parameter>&nbsp;:</term>
<listitem><simpara> stringified uri to compare with <parameter>uri_1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>TRUE</literal> if they are the same, <literal>FALSE</literal> otherwise.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>
<refsect2>
<title><anchor id="GNOME-VFS-ASSERT-PRIMARY-THREAD:CAPS" role="macro"/>GNOME_VFS_ASSERT_PRIMARY_THREAD</title>
<indexterm><primary>GNOME_VFS_ASSERT_PRIMARY_THREAD</primary></indexterm><programlisting>#define GNOME_VFS_ASSERT_PRIMARY_THREAD g_assert (gnome_vfs_is_primary_thread())
</programlisting>
<para>
Asserts that the current thread is the thread with 
the main glib event loop</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GNOME-VFS-ASSERT-SECONDARY-THREAD:CAPS" role="macro"/>GNOME_VFS_ASSERT_SECONDARY_THREAD</title>
<indexterm><primary>GNOME_VFS_ASSERT_SECONDARY_THREAD</primary></indexterm><programlisting>#define GNOME_VFS_ASSERT_SECONDARY_THREAD g_assert (!gnome_vfs_is_primary_thread())
</programlisting>
<para>
Asserts that the current thread is NOT the thread with
the main glib event loop</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-read-entire-file" role="function" condition="since:2.2"/>gnome_vfs_read_entire_file ()</title>
<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,
                                             <link linkend="int">int</link> *file_size,
                                             <link linkend="char">char</link> **file_contents);</programlisting>
<para>
Reads an entire file into memory for convenience. Beware accidentally
loading large files into memory with this function.
</para>
<para>
Since version 2.10 the string stored in <parameter>file_contents</parameter> will be null-terminated,
so for text files you can use result as a normal string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> uri of the file to read.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>file_size</parameter>&nbsp;:</term>
<listitem><simpara> after reading the file, contains the size of the file read.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>file_contents</parameter>&nbsp;:</term>
<listitem><simpara> contains the file_size bytes, the contents of the file at <parameter>uri</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an integer representing the result of the operation.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.2
</para></refsect2>

</refsect1>




</refentry>
