## gnome-vfs-utils

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

## Synopsis

    enum                GnomeVFSMakeURIDirs;
    char *              gnome_vfs_format_file_size_for_display
                                                            (GnomeVFSFileSize size);
    char *              gnome_vfs_format_uri_for_display    (const char *uri);
    GnomeVFSResult      gnome_vfs_url_show                  (const char *url);
    GnomeVFSResult      gnome_vfs_url_show_with_env         (const char *url,
                                                             char **envp);
    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_uri_canonical_strip_fragment
                                                            (const char *uri);
    char *              gnome_vfs_make_path_name_canonical  (const char *path);
    char *              gnome_vfs_make_uri_from_input       (const char *location);
    char *              gnome_vfs_make_uri_from_input_with_dirs
                                                            (const char *location,
                                                             GnomeVFSMakeURIDirs dirs);
    char *              gnome_vfs_make_uri_from_shell_arg   (const char *uri);
    char *              gnome_vfs_make_uri_full_from_relative
                                                            (const char *base_uri,
                                                             const char *relative_uri);
    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_open_fd                   (GnomeVFSHandle **handle,
                                                             int filedes);
    GnomeVFSResult      gnome_vfs_read_entire_file          (const char *uri,
                                                             int *file_size,
                                                             char **file_contents);

## Description

## Details

### enum GnomeVFSMakeURIDirs

    typedef enum {
    	GNOME_VFS_MAKE_URI_DIR_NONE = 0,
    	GNOME_VFS_MAKE_URI_DIR_HOMEDIR = 1 << 0,
    	GNOME_VFS_MAKE_URI_DIR_CURRENT = 1 << 1
    } GnomeVFSMakeURIDirs;

Flags that can be passed to `gnome_vfs_make_uri_from_input_with_dirs()`. 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.

`GNOME_VFS_MAKE_URI_DIR_NONE` | Don't check any directory
`GNOME_VFS_MAKE_URI_DIR_HOMEDIR` | Check the home directory
`GNOME_VFS_MAKE_URI_DIR_CURRENT` | Check the current direcotry

### gnome_vfs_format_file_size_for_display ()

    char *              gnome_vfs_format_file_size_for_display
                                                            (GnomeVFSFileSize size);

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

`size` : | a GnomeVFSFileSize (a guint64 value).
Returns : | a newly allocated string with the size ready to be shown.

### gnome_vfs_format_uri_for_display ()

    char *              gnome_vfs_format_uri_for_display    (const char *uri);

Filter, modify, unescape and change `uri` to make it appropriate for display to users. The conversion is done such that the roundtrip to UTF-8 is reversible.

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.

`uri` : | uri to be displayed.
Returns : | a newly allocated string which represents `uri` and can be displayed.

Since 2.2

### gnome_vfs_url_show ()

    GnomeVFSResult      gnome_vfs_url_show                  (const char *url);

Launches the default application or component associated with the given `url`.

`url` : | url to be shown.
Returns : | `GNOME_VFS_OK` if the default action was launched, `GNOME_VFS_ERROR_BAD_PARAMETERS` for an invalid or non-existant `url`, `GNOME_VFS_ERROR_NO_DEFAULT` if no default action is associated with the `url`. Also error codes from `gnome_vfs_mime_action_launch()` or `gnome_vfs_mime_action_launch_with_env()`.

Since 2.4

### gnome_vfs_url_show_with_env ()

    GnomeVFSResult      gnome_vfs_url_show_with_env         (const char *url,
                                                             char **envp);

Like `gnome_vfs_url_show()` except that the default action will be launched with the given environment.

`url` : | url to be shown.
`envp` : | environment data.
Returns : | `GNOME_VFS_OK` if the default action was launched. `GNOME_VFS_ERROR_BAD_PARAMETERS` for an invalid or non-existant `url`, `GNOME_VFS_ERROR_NO_DEFAULT` if no default action is associated with the `url`. Also error codes from `gnome_vfs_mime_application_launch_with_env()` or `gnome_vfs_mime_action_launch_with_env()`.

Since 2.4

### 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);

Escapes all characters in `string` which are listed in `match_set`.

`string` : | string to be escaped.
`match_set` : | a string containing all characters to be escaped in `string`.
Returns : | a newly allocated string equivalent to `string` but with characters in `match_string` escaped.

### 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" to be escaped, '\0' is automatically in this list.
Returns : | a newly allocated string with the unescaped equivalents, or `NULL` if `escaped_string` contained an escaped encoding of one of the characters in `illegal_characters`.

### gnome_vfs_make_uri_canonical ()

    char *              gnome_vfs_make_uri_canonical        (const char *uri);

Standardizes the format of the `uri`, so that it can be used later in other functions that expect a canonical uri.

`uri` : | an absolute or relative stringified uri. It might have scheme.
Returns : | a newly allocated string that contains the canonical representation of `uri`.

Since 2.2

### gnome_vfs_make_uri_canonical_strip_fragment ()

    char *              gnome_vfs_make_uri_canonical_strip_fragment
                                                            (const char *uri);

Returns a canonicalized uri. If `uri` contains a fragment (anything after a '#') strips off that and then makes the `uri` canonical.

`uri` : | a GnomeVFSURI.
Returns : | a newly allocated string containing a canonical `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_make_uri_from_input ()

    char *              gnome_vfs_make_uri_from_input       (const char *location);

Takes a user input path/uri and makes a valid uri out of it.

This function is the reverse of `gnome_vfs_format_uri_for_display()` but it also handles the fact that the user could have typed arbitrary UTF-8 in the entry showing the string.

`location` : | a possibly mangled "uri", in UTF-8.
Returns : | a newly allocated uri.

Since 2.2

### gnome_vfs_make_uri_from_input_with_dirs ()

    char *              gnome_vfs_make_uri_from_input_with_dirs
                                                            (const char *location,
                                                             GnomeVFSMakeURIDirs dirs);

Determines a fully qualified uri from a relative or absolute input path. Basically calls `gnome_vfs_make_uri_from_input()` except it specifically tries to support paths relative to the specified directories (can be homedir and/or current directory). See GnomeVFSMakeURIDirs for more information.

`location` : | a relative or absolute path.
`dirs` : | directory to use as a base directory if `location` is a relative path.
Returns : | a newly allocated string containing the fully qualified uri.

Since 2.4

### gnome_vfs_make_uri_from_shell_arg ()

    char *              gnome_vfs_make_uri_from_shell_arg   (const char *uri);

Similar to `gnome_vfs_make_uri_from_input()`, except that:

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.

`uri` : | path to make the uri from.
Returns : | a newly allocated string representing `uri`.

Since 2.2

### gnome_vfs_make_uri_full_from_relative ()

    char *              gnome_vfs_make_uri_full_from_relative
                                                            (const char *base_uri,
                                                             const char *relative_uri);

### Warning

`gnome_vfs_make_uri_full_from_relative` is deprecated and should not be used in newly-written code. This function is deprecated, please use `gnome_vfs_uri_make_full_from_relative()` from gnome-vfs-uri.h .

Returns a string representing the full uri given a full `base_uri` and a secondary uri which may be relative.

`base_uri` : | path to use as the base for the full uri.
`relative_uri` : | full or relative path to be appended to the `base_uri`.
Returns : | a newly allocated string containing the uri. (`NULL` for some bad errors).

Since 2.2

### 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);

Similar to gnome_vfs_unescape_string, but it returns something semi-intelligable to a user even upon receiving traumatic input such as `00` or URIs in bad form.

See also: `gnome_vfs_unescape_string()`.

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 "#" "&" and "?", which have special meanings in URI strings.

`escaped` : | a string encoded with escaped sequences.
Returns : | a pointer to a g_malloc'd string with all characters replacing their escaped hex values.

### 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`, such as a path provided by `gtk_file_chooser_get_filename()`. The resulting URI may be provided, for instance, to `gnome_vfs_uri_new()`.

On Windows `local_full_path` should be in the UTF-8 encoding, and can start with a drive letter, but doesn't have to.

`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` : | a string representing a command ie "xterm -bg white".
Returns : | `TRUE` if `command_string` started with an executable file, and is in $PATH, `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 the amount of free space in bytes on `vfs`-uri's volume in `size`.

`vfs_uri` : | a GnomeVFSURI.
`size` : | a GnomeVFSFileSize.
Returns : | `GNOME_VFS_OK` on success, otherwise an `GNOME_VFS_ERROR_`* code.

### gnome_vfs_icon_path_from_filename ()

    char *              gnome_vfs_icon_path_from_filename   (const char *filename);

`filename` : | path to a file. Could be relative or absolute path.
Returns : | Returns the icon path for the `filename`. 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.

### 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` doesn't 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_open_fd ()

    GnomeVFSResult      gnome_vfs_open_fd                   (GnomeVFSHandle **handle,
                                                             int filedes);

Converts an open unix file descript into a GnomeVFSHandle that can be used with the normal GnomeVFS file operations. When the handle is closed the file descriptor will also be closed.

`handle` : | A pointer to a pointer to a GnomeVFSHandle object
`filedes` : | a UNIX file descriptor
Returns : | `GNOME_VFS_OK` if the open was ok, a suitable error otherwise. Since 2.2

### 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.

Since version 2.10 the string stored in `file_contents` will be null-terminated, so for text files you can use result as a normal string.

`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