Reading and Writing Files

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

## Synopsis

    enum                MateVFSSeekPosition;
    MateVFSResult      mate_vfs_read                      (MateVFSHandle *handle,
                                                             gpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_read);
    MateVFSResult      mate_vfs_write                     (MateVFSHandle *handle,
                                                             gconstpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_written);
    MateVFSResult      mate_vfs_seek                      (MateVFSHandle *handle,
                                                             MateVFSSeekPosition whence,
                                                             MateVFSFileOffset offset);
    MateVFSResult      mate_vfs_tell                      (MateVFSHandle *handle,
                                                             MateVFSFileSize *offset_return);
    MateVFSResult      mate_vfs_forget_cache              (MateVFSHandle *handle,
                                                             MateVFSFileOffset offset,
                                                             MateVFSFileSize size);

## Description

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

## Details

### enum MateVFSSeekPosition

    typedef enum {
            MATE_VFS_SEEK_START,
            MATE_VFS_SEEK_CURRENT,
            MATE_VFS_SEEK_END
    } MateVFSSeekPosition;

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

`MATE_VFS_SEEK_START` | Start of the file.
`MATE_VFS_SEEK_CURRENT` | Current position.
`MATE_VFS_SEEK_END` | End of the file.

### mate_vfs_read ()

    MateVFSResult      mate_vfs_read                      (MateVFSHandle *handle,
                                                             gpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *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.

### mate_vfs_write ()

    MateVFSResult      mate_vfs_write                     (MateVFSHandle *handle,
                                                             gconstpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *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.

### mate_vfs_seek ()

    MateVFSResult      mate_vfs_seek                      (MateVFSHandle *handle,
                                                             MateVFSSeekPosition whence,
                                                             MateVFSFileOffset 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.

### mate_vfs_tell ()

    MateVFSResult      mate_vfs_tell                      (MateVFSHandle *handle,
                                                             MateVFSFileSize *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.

### mate_vfs_forget_cache ()

    MateVFSResult      mate_vfs_forget_cache              (MateVFSHandle *handle,
                                                             MateVFSFileOffset offset,
                                                             MateVFSFileSize size);

With this call you can announce to mate-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