## gnome-vfs-utils

gnome-vfs-utils — various utilities functions to manipulate uris

## Synopsis

    char*       gnome_vfs_format_file_size_for_display
                                                (GnomeVFSFileSize size);
    char*       gnome_vfs_escape_string         (const char *string);
    char*       gnome_vfs_escape_path_string    (const char *path);
    char*       gnome_vfs_escape_host_and_path_string
                                                (const char *path);
    char*       gnome_vfs_escape_slashes        (const char *string);
    char*       gnome_vfs_escape_set            (const char *string,
                                                 const char *match_set);
    char*       gnome_vfs_unescape_string       (const char *escaped_string,
                                                 const char *illegal_characters);
    char*       gnome_vfs_make_uri_canonical    (const char *uri);
    char*       gnome_vfs_make_path_name_canonical
                                                (const char *path);
    char*       gnome_vfs_expand_initial_tilde  (const char *path);
    char*       gnome_vfs_unescape_string_for_display
                                                (const char *escaped);
    char*       gnome_vfs_get_local_path_from_uri
                                                (const char *uri);
    char*       gnome_vfs_get_uri_from_local_path
                                                (const char *local_full_path);
    gboolean    gnome_vfs_is_executable_command_string
                                                (const char *command_string);
    void        gnome_vfs_list_deep_free        (GList *list);
    GnomeVFSResult gnome_vfs_get_volume_free_space
                                                (const GnomeVFSURI *vfs_uri,
                                                 GnomeVFSFileSize *size);
    char*       gnome_vfs_icon_path_from_filename
                                                (const char *filename);
    gboolean    gnome_vfs_is_primary_thread     (void);
    char*       gnome_vfs_get_uri_scheme        (const char *uri);
    gboolean    gnome_vfs_uris_match            (const char *uri_1,
                                                 const char *uri_2);
    #define     GNOME_VFS_ASSERT_PRIMARY_THREAD
    #define     GNOME_VFS_ASSERT_SECONDARY_THREAD
    GnomeVFSResult gnome_vfs_read_entire_file   (const char *uri,
                                                 int *file_size,
                                                 char **file_contents);

## Description

## Details

### gnome_vfs_format_file_size_for_display ()

    char*       gnome_vfs_format_file_size_for_display
                                                (GnomeVFSFileSize size);

Formats the file size passed in `bytes` in a way that is easy for the user to read. Gives the size in bytes, kilobytes, megabytes or gigabytes, choosing whatever is appropriate.

`size` : |
Returns : | a newly allocated string with the size ready to be shown.

### gnome_vfs_escape_string ()

    char*       gnome_vfs_escape_string         (const char *string);

Escapes `string`, replacing any and all special characters with equivalent escape sequences.

`string` : | string to be escaped
Returns : | a newly allocated string equivalent to `string` but with all special characters escaped

### gnome_vfs_escape_path_string ()

    char*       gnome_vfs_escape_path_string    (const char *path);

Escapes `path`, replacing only special characters that would not be found in paths (so '/', '&', '=', and '?' will not be escaped by this function).

`path` : | string to be escaped
Returns : | a newly allocated string equivalent to `path` but with non-path characters escaped

### gnome_vfs_escape_host_and_path_string ()

    char*       gnome_vfs_escape_host_and_path_string
                                                (const char *path);

Escapes `path`, replacing only special characters that would not be found in paths or host name (so '/', '&', '=', ':', '@' and '?' will not be escaped by this function).

`path` : | string to be escaped
Returns : | a newly allocated string equivalent to `path` but with non-path/host characters escaped

### gnome_vfs_escape_slashes ()

    char*       gnome_vfs_escape_slashes        (const char *string);

Escapes only '/' and '%' characters in `string`, replacing them with their escape sequence equivalents.

`string` : | string to be escaped
Returns : | a newly allocated string equivalent to `string`, but with no unescaped '/' or '%' characters

### gnome_vfs_escape_set ()

    char*       gnome_vfs_escape_set            (const char *string,
                                                 const char *match_set);

`string` : |
`match_set` : |
Returns : |

### gnome_vfs_unescape_string ()

    char*       gnome_vfs_unescape_string       (const char *escaped_string,
                                                 const char *illegal_characters);

Decodes escaped characters (i.e. PERCENTxx sequences) in `escaped_string`. Characters are encoded in PERCENTxy form, where xy is the ASCII hex code for character 16x+y.

`escaped_string` : | an escaped URI, path, or other string
`illegal_characters` : | a string containing a sequence of characters considered "illegal", '\0' is automatically in this list.
Returns : | a newly allocated string with the unescaped equivalents, or `NULL` if `escaped_string` contained one of the characters in `illegal_characters`.

### gnome_vfs_make_uri_canonical ()

    char*       gnome_vfs_make_uri_canonical    (const char *uri);

Standarizes the format of the uri being passed, so that it can be used later in other functions that expect a canonical URI.

`uri` : | and absolute or relative URI, it might have scheme.
Returns : | a newly allocated string that contains the canonical representation of `uri`.

Since 2.2

### gnome_vfs_make_path_name_canonical ()

    char*       gnome_vfs_make_path_name_canonical
                                                (const char *path);

Calls _gnome_vfs_canonicalize_pathname, allocating storage for the result and providing for a cleaner memory management.

`path` : | a file path, relative or absolute
Returns : | a canonical version of `path`

### gnome_vfs_expand_initial_tilde ()

    char*       gnome_vfs_expand_initial_tilde  (const char *path);

If `path` starts with a ~, representing the user's home directory, expand it to the actual path location.

`path` : | a local file path which may start with a '~'
Returns : | a newly allocated string with the initial tilde (if there was one) converted to an actual path

### gnome_vfs_unescape_string_for_display ()

    char*       gnome_vfs_unescape_string_for_display
                                                (const char *escaped);

`escaped` : |
Returns : |

### gnome_vfs_get_local_path_from_uri ()

    char*       gnome_vfs_get_local_path_from_uri
                                                (const char *uri);

Create a local path for a file:/// URI. Do not use with URIs of other methods.

`uri` : | URI to convert to a local path
Returns : | a newly allocated string containing the local path NULL is returned on error or if the uri isn't a file: URI without a fragment identifier (or chained URI).

### gnome_vfs_get_uri_from_local_path ()

    char*       gnome_vfs_get_uri_from_local_path
                                                (const char *local_full_path);

Returns a file:/// URI for the local path `local_full_path`.

`local_full_path` : | a full local filesystem path (i.e. not relative)
Returns : | a newly allocated string containing the URI corresponding to `local_full_path` (NULL for some bad errors).

### gnome_vfs_is_executable_command_string ()

    gboolean    gnome_vfs_is_executable_command_string
                                                (const char *command_string);

Checks if `command_string` starts with the full path of an executable file or an executable in $PATH.

`command_string` : |
Returns : | TRUE if command_string started with and executable file, FALSE otherwise.

### gnome_vfs_list_deep_free ()

    void        gnome_vfs_list_deep_free        (GList *list);

Free `list`, and call `g_free()` on all data members.

`list` : | list to be freed

### gnome_vfs_get_volume_free_space ()

    GnomeVFSResult gnome_vfs_get_volume_free_space
                                                (const GnomeVFSURI *vfs_uri,
                                                 GnomeVFSFileSize *size);

Stores in `size` the amount of free space on a volume. This only works for URIs with the file: scheme.

`vfs_uri` : |
`size` : |
Returns : | GNOME_VFS_OK on success, otherwise an error code

### gnome_vfs_icon_path_from_filename ()

    char*       gnome_vfs_icon_path_from_filename
                                                (const char *filename);

`filename` : |
Returns : |

### gnome_vfs_is_primary_thread ()

    gboolean    gnome_vfs_is_primary_thread     (void);

Check if the current thread is the thread with the main glib event loop.

Returns : | `TRUE` if the current thread is the thread with the main glib event loop

### gnome_vfs_get_uri_scheme ()

    char*       gnome_vfs_get_uri_scheme        (const char *uri);

Retrieve the scheme used in `uri`

`uri` : | a stringified URI
Returns : | A newly allocated string containing the scheme, NULL if `uri` it doesn't seem to contain a scheme

Since 2.2

### gnome_vfs_uris_match ()

    gboolean    gnome_vfs_uris_match            (const char *uri_1,
                                                 const char *uri_2);

Compare two URIs.

`uri_1` : | stringified URI to compare with `uri_2`.
`uri_2` : | stringified URI to compare with `uri_1`.
Returns : | TRUE if they are the same, FALSE otherwise.

Since 2.2

### GNOME_VFS_ASSERT_PRIMARY_THREAD

    #define GNOME_VFS_ASSERT_PRIMARY_THREAD g_assert (gnome_vfs_is_primary_thread())

Asserts that the current thread is the thread with the main glib event loop

### GNOME_VFS_ASSERT_SECONDARY_THREAD

    #define GNOME_VFS_ASSERT_SECONDARY_THREAD g_assert (!gnome_vfs_is_primary_thread())

Asserts that the current thread is NOT the thread with the main glib event loop

### gnome_vfs_read_entire_file ()

    GnomeVFSResult gnome_vfs_read_entire_file   (const char *uri,
                                                 int *file_size,
                                                 char **file_contents);

Reads an entire file into memory for convenience. Beware accidentally loading large files into memory with this function.

`uri` : | URI of the file to read
`file_size` : | after reading the file, contains the size of the file read
`file_contents` : | contains the file_size bytes, the contents of the file at `uri`.
Returns : | An integer representing the result of the operation

Since 2.2