## Reading and Writing Files

Reading and Writing Files — Reading from and writing to open file handles.

## Synopsis

    enum                GnomeVFSSeekPosition;
    GnomeVFSResult      gnome_vfs_read                      (GnomeVFSHandle *handle,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read);
    GnomeVFSResult      gnome_vfs_write                     (GnomeVFSHandle *handle,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written);
    GnomeVFSResult      gnome_vfs_seek                      (GnomeVFSHandle *handle,
                                                             GnomeVFSSeekPosition whence,
                                                             GnomeVFSFileOffset offset);
    GnomeVFSResult      gnome_vfs_tell                      (GnomeVFSHandle *handle,
                                                             GnomeVFSFileSize *offset_return);
    GnomeVFSResult      gnome_vfs_forget_cache              (GnomeVFSHandle *handle,
                                                             GnomeVFSFileOffset offset,
                                                             GnomeVFSFileSize size);

## Description

Reading and writing operations are explained, also `gnome_vfs_seek()`, which is used to move the file pointer inside the file.

## Details

### enum GnomeVFSSeekPosition

    typedef enum {
            GNOME_VFS_SEEK_START,
            GNOME_VFS_SEEK_CURRENT,
            GNOME_VFS_SEEK_END
    } GnomeVFSSeekPosition;

This is used to specify the start position for seek operations.

`GNOME_VFS_SEEK_START` | Start of the file.
`GNOME_VFS_SEEK_CURRENT` | Current position.
`GNOME_VFS_SEEK_END` | End of the file.

### gnome_vfs_read ()

    GnomeVFSResult      gnome_vfs_read                      (GnomeVFSHandle *handle,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read);

Read `bytes` from `handle`. As with Unix system calls, the number of bytes read can effectively be less than `bytes` on return and will be stored in `bytes_read`.

`handle` : | handle of the file to read data from.
`buffer` : | pointer to a buffer that must be at least `bytes` bytes large.
`bytes` : | number of bytes to read.
`bytes_read` : | pointer to a variable that will hold the number of bytes effectively read on return.
Returns : | an integer representing the result of the operation.

### gnome_vfs_write ()

    GnomeVFSResult      gnome_vfs_write                     (GnomeVFSHandle *handle,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written);

Write `bytes` into the file opened through `handle`. As with Unix system calls, the number of bytes written can effectively be less than `bytes` on return and will be stored in `bytes_written`.

`handle` : | handle of the file to write data to.
`buffer` : | pointer to the buffer containing the data to be written.
`bytes` : | number of bytes to write.
`bytes_written` : | pointer to a variable that will hold the number of bytes effectively written on return.
Returns : | an integer representing the result of the operation.

### gnome_vfs_seek ()

    GnomeVFSResult      gnome_vfs_seek                      (GnomeVFSHandle *handle,
                                                             GnomeVFSSeekPosition whence,
                                                             GnomeVFSFileOffset offset);

Set the current position for reading/writing through `handle`.

`handle` : | handle for which the current position must be changed.
`whence` : | integer value representing the starting position.
`offset` : | number of bytes to skip from the position specified by `whence`. (a positive value means to move forward; a negative one to move backwards).
Returns : | an integer representing the result of the operation.

### gnome_vfs_tell ()

    GnomeVFSResult      gnome_vfs_tell                      (GnomeVFSHandle *handle,
                                                             GnomeVFSFileSize *offset_return);

Return the current position on `handle`. This is the point in the file pointed to by handle that reads and writes will occur on.

`handle` : | handle for which the current position must be retrieved.
`offset_return` : | pointer to a variable that will contain the current position on return.
Returns : | an integer representing the result of the operation.

### gnome_vfs_forget_cache ()

    GnomeVFSResult      gnome_vfs_forget_cache              (GnomeVFSHandle *handle,
                                                             GnomeVFSFileOffset offset,
                                                             GnomeVFSFileSize size);

With this call you can announce to gnome-vfs that you will no longer use the region of data starting at `offset` with the size of `size`. Any cached data for this region might then be freed.

This might be useful if you stream large files, for example.

`handle` : | handle of the file to affect.
`offset` : | start point of the region to be freed.
`size` : | length of the region to be freed (or until the end of the file if 0 is specified).
Returns : | an integer representing the result of the operation.

Since 2.12