Reading and Writing Files
3
GNOME-VFS-2.0 Library

# 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