Basic File Operations
3
GNOME-VFS-2.0 Library

# Basic File Operations

Essential VFS operations. This includes creating, moving and deleting files, opening and closing file handles.

## Synopsis

    enum                GnomeVFSOpenMode;
    GnomeVFSResult      gnome_vfs_create                    (GnomeVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             GnomeVFSOpenMode open_mode,
                                                             gboolean exclusive,
                                                             guint perm);
    GnomeVFSResult      gnome_vfs_create_uri                (GnomeVFSHandle **handle,
                                                             GnomeVFSURI *uri,
                                                             GnomeVFSOpenMode open_mode,
                                                             gboolean exclusive,
                                                             guint perm);
    GnomeVFSResult      gnome_vfs_open                      (GnomeVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             GnomeVFSOpenMode open_mode);
    GnomeVFSResult      gnome_vfs_open_uri                  (GnomeVFSHandle **handle,
                                                             GnomeVFSURI *uri,
                                                             GnomeVFSOpenMode open_mode);
    GnomeVFSResult      gnome_vfs_close                     (GnomeVFSHandle *handle);
    GnomeVFSResult      gnome_vfs_unlink                    (const gchar *text_uri);
    GnomeVFSResult      gnome_vfs_unlink_from_uri           (GnomeVFSURI *uri);
    GnomeVFSResult      gnome_vfs_move_uri                  (GnomeVFSURI *old_uri,
                                                             GnomeVFSURI *new_uri,
                                                             gboolean force_replace);
    GnomeVFSResult      gnome_vfs_move                      (const gchar *old_text_uri,
                                                             const gchar *new_text_uri,
                                                             gboolean force_replace);
    GnomeVFSResult      gnome_vfs_check_same_fs_uris        (GnomeVFSURI *source_uri,
                                                             GnomeVFSURI *target_uri,
                                                             gboolean *same_fs_return);
    GnomeVFSResult      gnome_vfs_check_same_fs             (const gchar *source,
                                                             const gchar *target,
                                                             gboolean *same_fs_return);
    gboolean            gnome_vfs_uri_exists                (GnomeVFSURI *uri);
    GnomeVFSResult      gnome_vfs_create_symbolic_link      (GnomeVFSURI *uri,
                                                             const gchar *target_reference);

## Description

GnomeVFS 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 GnomeVFS after learning a little about URIs.

## Details

### enum GnomeVFSOpenMode

    typedef enum {
            GNOME_VFS_OPEN_NONE = 0,
            GNOME_VFS_OPEN_READ = 1 << 0,
            GNOME_VFS_OPEN_WRITE = 1 << 1,
            GNOME_VFS_OPEN_RANDOM = 1 << 2,
    	GNOME_VFS_OPEN_TRUNCATE = 1 << 3
    } GnomeVFSOpenMode;

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

`GNOME_VFS_OPEN_NONE`

  No access.

`GNOME_VFS_OPEN_READ`

  Read access.

`GNOME_VFS_OPEN_WRITE`

  Write access.

`GNOME_VFS_OPEN_RANDOM`

  Random access.

`GNOME_VFS_OPEN_TRUNCATE`

  Truncate file before accessing it, i.e. delete its contents.

### gnome_vfs_create ()

    GnomeVFSResult      gnome_vfs_create                    (GnomeVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             GnomeVFSOpenMode 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 GnomeVFSHandle object.

`text_uri` :

  string representing the uri to create.

`open_mode` :

  mode to leave the file opened in after creation (or `GNOME_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.

### gnome_vfs_create_uri ()

    GnomeVFSResult      gnome_vfs_create_uri                (GnomeVFSHandle **handle,
                                                             GnomeVFSURI *uri,
                                                             GnomeVFSOpenMode 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 GnomeVFSHandle 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.

### gnome_vfs_open ()

    GnomeVFSResult      gnome_vfs_open                      (GnomeVFSHandle **handle,
                                                             const gchar *text_uri,
                                                             GnomeVFSOpenMode 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 GnomeVFSHandle object.

`text_uri` :

  string representing the uri to open.

`open_mode` :

  open mode.

Returns :

  an integer representing the result of the operation.

### gnome_vfs_open_uri ()

    GnomeVFSResult      gnome_vfs_open_uri                  (GnomeVFSHandle **handle,
                                                             GnomeVFSURI *uri,
                                                             GnomeVFSOpenMode 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 GnomeVFSHandle object.

`uri` :

  uri to open.

`open_mode` :

  open mode.

Returns :

  an integer representing the result of the operation.

### gnome_vfs_close ()

    GnomeVFSResult      gnome_vfs_close                     (GnomeVFSHandle *handle);

Close file associated with `handle`.

`handle` :

  pointer to a GnomeVFSHandle object.

Returns :

  an integer representing the result of the operation.

### gnome_vfs_unlink ()

    GnomeVFSResult      gnome_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.

### gnome_vfs_unlink_from_uri ()

    GnomeVFSResult      gnome_vfs_unlink_from_uri           (GnomeVFSURI *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.

### gnome_vfs_move_uri ()

    GnomeVFSResult      gnome_vfs_move_uri                  (GnomeVFSURI *old_uri,
                                                             GnomeVFSURI *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 `gnome_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.

### gnome_vfs_move ()

    GnomeVFSResult      gnome_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 `gnome_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.

### gnome_vfs_check_same_fs_uris ()

    GnomeVFSResult      gnome_vfs_check_same_fs_uris        (GnomeVFSURI *source_uri,
                                                             GnomeVFSURI *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.

### gnome_vfs_check_same_fs ()

    GnomeVFSResult      gnome_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.

### gnome_vfs_uri_exists ()

    gboolean            gnome_vfs_uri_exists                (GnomeVFSURI *uri);

Check if the uri points to an existing entity.

`uri` :

  a uri.

Returns :

  `TRUE` if uri exists.

### gnome_vfs_create_symbolic_link ()

    GnomeVFSResult      gnome_vfs_create_symbolic_link      (GnomeVFSURI *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.