GnomeVFS - Filesystem Abstraction library
<<< Previous Page | Home | Up | Next Page >>>

# Basic File I/O

## Name

Basic File I/O -- synchronous file operations similar to posix calls, but using uris

## Synopsis

    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_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_close              (GnomeVFSHandle *handle);
    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_get_file_info      (const gchar *text_uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSFileInfoOptionsoptions);
    GnomeVFSResult gnome_vfs_get_file_info_uri  (GnomeVFSURI *uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSFileInfoOptionsoptions);
    GnomeVFSResult gnome_vfs_get_file_info_from_handle
                                                (GnomeVFSHandle *handle,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSFileInfoOptionsoptions);
    GnomeVFSResult gnome_vfs_truncate           (const gchar *text_uri,
                                                 GnomeVFSFileSize length);
    GnomeVFSResult gnome_vfs_truncate_uri       (GnomeVFSURI *uri,
                                                 GnomeVFSFileSize length);
    GnomeVFSResult gnome_vfs_truncate_handle    (GnomeVFSHandle *handle,
                                                 GnomeVFSFileSize length);
    GnomeVFSResult gnome_vfs_make_directory_for_uri
                                                (GnomeVFSURI *uri,
                                                 guint perm);
    GnomeVFSResult gnome_vfs_make_directory     (const gchar *text_uri,
                                                 guint perm);
    GnomeVFSResult gnome_vfs_remove_directory_from_uri
                                                (GnomeVFSURI *uri);
    GnomeVFSResult gnome_vfs_remove_directory   (const gchar *text_uri);
    GnomeVFSResult gnome_vfs_unlink_from_uri    (GnomeVFSURI *uri);
    GnomeVFSResult gnome_vfs_create_symbolic_link
                                                (GnomeVFSURI *uri,
                                                 const gchar *target_reference);
    GnomeVFSResult gnome_vfs_unlink             (const gchar *text_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_set_file_info_uri  (GnomeVFSURI *uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSSetFileInfoMask mask);
    GnomeVFSResult gnome_vfs_set_file_info      (const gchar *text_uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSSetFileInfoMask mask);

## Description

## Details

### 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` : | A 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` : | A 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_create ()

    GnomeVFSResult gnome_vfs_create             (GnomeVFSHandle **handle,
                                                 const gchar *text_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` : | A pointer to a pointer to a GnomeVFSHandle object
`text_uri` : | String representing the URI 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_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` : | A 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_close ()

    GnomeVFSResult gnome_vfs_close              (GnomeVFSHandle *handle);

Close file associated with `handle`.

`handle` : | A pointer to a GnomeVFSHandle object
Returns : | An integer representing the result of the operation.

### 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` : |
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 : |

### gnome_vfs_tell ()

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

Return the current position on `handle`.

`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_get_file_info ()

    GnomeVFSResult gnome_vfs_get_file_info      (const gchar *text_uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSFileInfoOptionsoptions);

Retrieve information about `text_uri`. The information will be stored in @*info.

`text_uri` : | URI of the file for which information will be retrieved
`info` : | Pointer to a GnomeVFSFileInfo object that will hold the information for the file on return
`Param3` : |
Returns : | An integer representing the result of the operation

### gnome_vfs_get_file_info_uri ()

    GnomeVFSResult gnome_vfs_get_file_info_uri  (GnomeVFSURI *uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSFileInfoOptionsoptions);

Retrieve information about `text_uri`. The information will be stored in `info`.

`uri` : | URI of the file for which information will be retrieved
`info` : | Pointer to a GnomeVFSFileInfo object that will hold the information for the file on return
`Param3` : |
Returns : | An integer representing the result of the operation

### gnome_vfs_get_file_info_from_handle ()

    GnomeVFSResult gnome_vfs_get_file_info_from_handle
                                                (GnomeVFSHandle *handle,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSFileInfoOptionsoptions);

Retrieve information about an open file. The information will be stored in @*info.

`handle` : | Handle of the file for which information must be retrieved
`info` : | Pointer to a GnomeVFSFileInfo object that will hold the information for the file on return
`Param3` : |
Returns : | An integer representing the result of the operation

### gnome_vfs_truncate ()

    GnomeVFSResult gnome_vfs_truncate           (const gchar *text_uri,
                                                 GnomeVFSFileSize length);

`text_uri` : |
`length` : |
Returns : |

### gnome_vfs_truncate_uri ()

    GnomeVFSResult gnome_vfs_truncate_uri       (GnomeVFSURI *uri,
                                                 GnomeVFSFileSize length);

`uri` : |
`length` : |
Returns : |

### gnome_vfs_truncate_handle ()

    GnomeVFSResult gnome_vfs_truncate_handle    (GnomeVFSHandle *handle,
                                                 GnomeVFSFileSize length);

`handle` : |
`length` : |
Returns : |

### gnome_vfs_make_directory_for_uri ()

    GnomeVFSResult gnome_vfs_make_directory_for_uri
                                                (GnomeVFSURI *uri,
                                                 guint perm);

Create `uri` as a directory.

`uri` : | URI of the directory to be created
`perm` : | Unix-style permissions for the newly created directory
Returns : | An integer representing the result of the operation

### gnome_vfs_make_directory ()

    GnomeVFSResult gnome_vfs_make_directory     (const gchar *text_uri,
                                                 guint perm);

Create `text_uri` as a directory.

`text_uri` : | URI of the directory to be created
`perm` : | Unix-style permissions for the newly created directory
Returns : | An integer representing the result of the operation

### gnome_vfs_remove_directory_from_uri ()

    GnomeVFSResult gnome_vfs_remove_directory_from_uri
                                                (GnomeVFSURI *uri);

Remove `uri`. `uri` must be an empty directory.

`uri` : | URI of the directory to be removed
Returns : | An integer representing the result of the operation

### gnome_vfs_remove_directory ()

    GnomeVFSResult gnome_vfs_remove_directory   (const gchar *text_uri);

`text_uri` : |
Returns : |

### gnome_vfs_unlink_from_uri ()

    GnomeVFSResult gnome_vfs_unlink_from_uri    (GnomeVFSURI *uri);

Unlink `text_uri`.

`uri` : |
Returns : | An integer representing the result of the operation

### 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

### gnome_vfs_unlink ()

    GnomeVFSResult gnome_vfs_unlink             (const gchar *text_uri);

`text_uri` : |
Returns : |

### 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` : |
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 URI `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` : | Source URI
`new_text_uri` : | Destination URI
`force_replace` : |
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 `a` and `b` are on the same file system.

`source_uri` : |
`target_uri` : |
`same_fs_return` : | Pointer to a boolean variable which will be set to `TRUE` if `a` and `b` are on the same file system on return.
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 `a` and `b` are on the same file system.

`source` : |
`target` : |
`same_fs_return` : | Pointer to a boolean variable which will be set to `TRUE` if `a` and `b` are on the same file system on return.
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_set_file_info_uri ()

    GnomeVFSResult gnome_vfs_set_file_info_uri  (GnomeVFSURI *uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSSetFileInfoMask mask);

Set file information for `uri`; only the information for which the corresponding bit in `mask` is set is actually modified.

`uri` : | A URI
`info` : | Information that must be set for the file
`mask` : | Bit mask representing which fields of `info` need to be set
Returns : | An integer representing the result of the operation.

### gnome_vfs_set_file_info ()

    GnomeVFSResult gnome_vfs_set_file_info      (const gchar *text_uri,
                                                 GnomeVFSFileInfo *info,
                                                 GnomeVFSSetFileInfoMask mask);

Set file information for `uri`; only the information for which the corresponding bit in `mask` is set is actually modified.

`text_uri` : | A URI
`info` : | Information that must be set for the file
`mask` : | Bit mask representing which fields of `info` need to be set
Returns : | An integer representing the result of the operation.

<<< Previous Page | Home | Up | Next Page >>>
Basic File Operations | Directory Operations