Basic File Operations

## Basic File Operations Basic File Operations — Essential VFS operations. This includes creating, moving and deleting files, opening and closing file handles. |

## Synopsis

    enum                MateVFSOpenMode;
    MateVFSResult      mate_vfs_create                    (MateVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             MateVFSOpenMode open_mode,
                                                             gboolean exclusive,
                                                             guint perm);
    MateVFSResult      mate_vfs_create_uri                (MateVFSHandle **handle,
                                                             MateVFSURI *uri,
                                                             MateVFSOpenMode open_mode,
                                                             gboolean exclusive,
                                                             guint perm);
    MateVFSResult      mate_vfs_open                      (MateVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             MateVFSOpenMode open_mode);
    MateVFSResult      mate_vfs_open_uri                  (MateVFSHandle **handle,
                                                             MateVFSURI *uri,
                                                             MateVFSOpenMode open_mode);
    MateVFSResult      mate_vfs_close                     (MateVFSHandle *handle);
    MateVFSResult      mate_vfs_unlink                    (const gchar *text_uri);
    MateVFSResult      mate_vfs_unlink_from_uri           (MateVFSURI *uri);
    MateVFSResult      mate_vfs_move_uri                  (MateVFSURI *old_uri,
                                                             MateVFSURI *new_uri,
                                                             gboolean force_replace);
    MateVFSResult      mate_vfs_move                      (const gchar *old_text_uri,
                                                             const gchar *new_text_uri,
                                                             gboolean force_replace);
    MateVFSResult      mate_vfs_check_same_fs_uris        (MateVFSURI *source_uri,
                                                             MateVFSURI *target_uri,
                                                             gboolean *same_fs_return);
    MateVFSResult      mate_vfs_check_same_fs             (const gchar *source,
                                                             const gchar *target,
                                                             gboolean *same_fs_return);
    gboolean            mate_vfs_uri_exists                (MateVFSURI *uri);
    MateVFSResult      mate_vfs_create_symbolic_link      (MateVFSURI *uri,
                                                             const gchar *target_reference);

## Description

MateVFS file operations are, for the most part, patterned after their POSIX equivalents, with the systematic difference that they accept URIs rather than paths on the local filesystem. This makes them easy to learn as if you are already familiar with basic commands such as `open()`, `seek()`, `write()`, etc you will feel right at home with MateVFS after learning a little about URIs.

## Details

### enum MateVFSOpenMode

    typedef enum {
            MATE_VFS_OPEN_NONE = 0,
            MATE_VFS_OPEN_READ = 1 << 0,
            MATE_VFS_OPEN_WRITE = 1 << 1,
            MATE_VFS_OPEN_RANDOM = 1 << 2,
    	MATE_VFS_OPEN_TRUNCATE = 1 << 3
    } MateVFSOpenMode;

Mode in which files are opened. If MATE_VFS_OPEN_RANDOM is not used, the file will be have to be accessed sequentially.

`MATE_VFS_OPEN_NONE` | No access.
`MATE_VFS_OPEN_READ` | Read access.
`MATE_VFS_OPEN_WRITE` | Write access.
`MATE_VFS_OPEN_RANDOM` | Random access.
`MATE_VFS_OPEN_TRUNCATE` | Truncate file before accessing it, i.e. delete its contents.

### mate_vfs_create ()

    MateVFSResult      mate_vfs_create                    (MateVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             MateVFSOpenMode open_mode,
                                                             gboolean exclusive,
                                                             guint perm);

Create `text_uri` according to mode `open_mode`. On return, `handle` will then contain a pointer to a handle for the open file.

`handle` : | pointer to a pointer to a MateVFSHandle object.
`text_uri` : | string representing the uri to create.
`open_mode` : | mode to leave the file opened in after creation (or `MATE_VFS_OPEN_MODE_NONE` to leave the file closed after creation).
`exclusive` : | whether the file should be created in "exclusive" mode. i.e. if this flag is nonzero, operation will fail if a file with the same name already exists.
`perm` : | bitmap representing the permissions for the newly created file (Unix style).
Returns : | an integer representing the result of the operation.

### mate_vfs_create_uri ()

    MateVFSResult      mate_vfs_create_uri                (MateVFSHandle **handle,
                                                             MateVFSURI *uri,
                                                             MateVFSOpenMode open_mode,
                                                             gboolean exclusive,
                                                             guint perm);

Create `uri` according to mode `open_mode`. On return, `handle` will then contain a pointer to a handle for the open file.

`handle` : | pointer to a pointer to a MateVFSHandle object.
`uri` : | uri for the file to create.
`open_mode` : | open mode.
`exclusive` : | whether the file should be created in "exclusive" mode. i.e. if this flag is nonzero, operation will fail if a file with the same name already exists.
`perm` : | bitmap representing the permissions for the newly created file (Unix style).
Returns : | an integer representing the result of the operation.

### mate_vfs_open ()

    MateVFSResult      mate_vfs_open                      (MateVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             MateVFSOpenMode open_mode);

Open `text_uri` according to mode `open_mode`. On return, `handle` will then contain a pointer to a handle for the open file.

`handle` : | pointer to a pointer to a MateVFSHandle object.
`text_uri` : | string representing the uri to open.
`open_mode` : | open mode.
Returns : | an integer representing the result of the operation.

### mate_vfs_open_uri ()

    MateVFSResult      mate_vfs_open_uri                  (MateVFSHandle **handle,
                                                             MateVFSURI *uri,
                                                             MateVFSOpenMode open_mode);

Open `uri` according to mode `open_mode`. On return, `handle` will then contain a pointer to a handle for the open file.

`handle` : | pointer to a pointer to a MateVFSHandle object.
`uri` : | uri to open.
`open_mode` : | open mode.
Returns : | an integer representing the result of the operation.

### mate_vfs_close ()

    MateVFSResult      mate_vfs_close                     (MateVFSHandle *handle);

Close file associated with `handle`.

`handle` : | pointer to a MateVFSHandle object.
Returns : | an integer representing the result of the operation.

### mate_vfs_unlink ()

    MateVFSResult      mate_vfs_unlink                    (const gchar *text_uri);

Unlink `text_uri` (i.e. delete the file).

`text_uri` : | uri of the file to be unlinked.
Returns : | an integer representing the result of the operation.

### mate_vfs_unlink_from_uri ()

    MateVFSResult      mate_vfs_unlink_from_uri           (MateVFSURI *uri);

Unlink `uri` (i.e. delete the file).

`uri` : | uri of the file to be unlinked.
Returns : | an integer representing the result of the operation.

### mate_vfs_move_uri ()

    MateVFSResult      mate_vfs_move_uri                  (MateVFSURI *old_uri,
                                                             MateVFSURI *new_uri,
                                                             gboolean force_replace);

Move a file from uri `old_uri` to `new_uri`. This will only work if `old_uri` and `new_uri` are on the same file system. Otherwise, it is necessary to use the more general `mate_vfs_xfer_uri()` function.

`old_uri` : | source uri.
`new_uri` : | destination uri.
`force_replace` : | if `TRUE`, move `old_uri` to `new_uri` even if there is already a file at `new_uri`. If there is a file, it will be discarded.
Returns : | an integer representing the result of the operation.

### mate_vfs_move ()

    MateVFSResult      mate_vfs_move                      (const gchar *old_text_uri,
                                                             const gchar *new_text_uri,
                                                             gboolean force_replace);

Move a file from `old_text_uri` to `new_text_uri`. This will only work if `old_text_uri` and `new_text_uri` are on the same file system. Otherwise, it is necessary to use the more general `mate_vfs_xfer_uri()` function.

`old_text_uri` : | string representing the source file location.
`new_text_uri` : | string representing the destination file location.
`force_replace` : | if `TRUE`, perform the operation even if it unlinks an existing file at `new_text_uri`.
Returns : | an integer representing the result of the operation.

### mate_vfs_check_same_fs_uris ()

    MateVFSResult      mate_vfs_check_same_fs_uris        (MateVFSURI *source_uri,
                                                             MateVFSURI *target_uri,
                                                             gboolean *same_fs_return);

Check if `source_uri` and `target_uri` are on the same file system.

`source_uri` : | a uri.
`target_uri` : | another uri.
`same_fs_return` : | pointer to a boolean variable which will be set to `TRUE` on return if `source_uri` and `target_uri` are on the same file system.
Returns : | an integer representing the result of the operation.

### mate_vfs_check_same_fs ()

    MateVFSResult      mate_vfs_check_same_fs             (const gchar *source,
                                                             const gchar *target,
                                                             gboolean *same_fs_return);

Check if `source` and `target` are on the same file system.

`source` : | path to a file.
`target` : | path to another file.
`same_fs_return` : | pointer to a boolean variable which will be set to `TRUE` on return if `source` and `target` are on the same file system.
Returns : | an integer representing the result of the operation.

### mate_vfs_uri_exists ()

    gboolean            mate_vfs_uri_exists                (MateVFSURI *uri);

Check if the uri points to an existing entity.

`uri` : | a uri.
Returns : | `TRUE` if uri exists.

### mate_vfs_create_symbolic_link ()

    MateVFSResult      mate_vfs_create_symbolic_link      (MateVFSURI *uri,
                                                             const gchar *target_reference);

Creates a symbolic link, or eventually, a uri link (as necessary) at `uri` pointing to `target_reference`.

`uri` : | uri to create a link at.
`target_reference` : | uri "reference" to point the link to (uri or relative path).
Returns : | an integer representing the result of the operation.