GnomeVFSFileInfo

## GnomeVFSFileInfo GnomeVFSFileInfo — stores information about files, GnomeVFS equivalent of stat |

## Synopsis

    enum        GnomeVFSFileFlags;
    enum        GnomeVFSFileType;
    enum        GnomeVFSFileInfoFields;
    enum        GnomeVFSFilePermissions;
    enum        GnomeVFSFileInfoOptions;
    enum        GnomeVFSSetFileInfoMask;
                GnomeVFSGetFileInfoResult;
    typedef     GnomeVFSInodeNumber;
                GnomeVFSFileInfo;
    #define     GNOME_VFS_FILE_INFO_SYMLINK     (info)
    #define     GNOME_VFS_FILE_INFO_SET_SYMLINK (info, value)
    #define     GNOME_VFS_FILE_INFO_LOCAL       (info)
    #define     GNOME_VFS_FILE_INFO_SET_LOCAL   (info, value)
    #define     GNOME_VFS_FILE_INFO_SUID        (info)
    #define     GNOME_VFS_FILE_INFO_SGID        (info)
    #define     GNOME_VFS_FILE_INFO_STICKY      (info)
    #define     GNOME_VFS_FILE_INFO_SET_SUID    (info, value)
    #define     GNOME_VFS_FILE_INFO_SET_SGID    (info, value)
    #define     GNOME_VFS_FILE_INFO_SET_STICKY  (info, value)
    GnomeVFSFileInfo* gnome_vfs_file_info_new   (void);
    void        gnome_vfs_file_info_unref       (GnomeVFSFileInfo *info);
    void        gnome_vfs_file_info_ref         (GnomeVFSFileInfo *info);
    void        gnome_vfs_file_info_clear       (GnomeVFSFileInfo *info);
    const char* gnome_vfs_file_info_get_mime_type
                                                (GnomeVFSFileInfo *info);
    void        gnome_vfs_file_info_copy        (GnomeVFSFileInfo *dest,
                                                 const GnomeVFSFileInfo *src);
    GnomeVFSFileInfo* gnome_vfs_file_info_dup   (const GnomeVFSFileInfo *orig);
    gboolean    gnome_vfs_file_info_matches     (const GnomeVFSFileInfo *a,
                                                 const GnomeVFSFileInfo *b);
    GList*      gnome_vfs_file_info_list_ref    (GList *list);
    GList*      gnome_vfs_file_info_list_unref  (GList *list);
    GList*      gnome_vfs_file_info_list_copy   (GList *list);
    void        gnome_vfs_file_info_list_free   (GList *list);

## Description

## Details

### enum GnomeVFSFileFlags

    typedef enum {
    	GNOME_VFS_FILE_FLAGS_NONE = 0,
    	GNOME_VFS_FILE_FLAGS_SYMLINK = 1 << 0,
    	GNOME_VFS_FILE_FLAGS_LOCAL = 1 << 1
    } GnomeVFSFileFlags;

Packed boolean bitfield representing special flags a GnomeVFSFileInfo struct can have.

`GNOME_VFS_FILE_FLAGS_NONE` | no flags
`GNOME_VFS_FILE_FLAGS_SYMLINK` | whether the file is a symlink.
`GNOME_VFS_FILE_FLAGS_LOCAL` | whether the file is on a local filesystem

### enum GnomeVFSFileType

    typedef enum {
    	GNOME_VFS_FILE_TYPE_UNKNOWN,
    	GNOME_VFS_FILE_TYPE_REGULAR,
    	GNOME_VFS_FILE_TYPE_DIRECTORY,
    	GNOME_VFS_FILE_TYPE_FIFO,
    	GNOME_VFS_FILE_TYPE_SOCKET,
    	GNOME_VFS_FILE_TYPE_CHARACTER_DEVICE,
    	GNOME_VFS_FILE_TYPE_BLOCK_DEVICE,
    	GNOME_VFS_FILE_TYPE_SYMBOLIC_LINK
    } GnomeVFSFileType;

Identifies the kind of file represented by a GnomeVFSFileInfo struct.

### enum GnomeVFSFileInfoFields

    typedef enum {
    	GNOME_VFS_FILE_INFO_FIELDS_NONE = 0,
    	GNOME_VFS_FILE_INFO_FIELDS_TYPE = 1 << 0,
    	GNOME_VFS_FILE_INFO_FIELDS_PERMISSIONS = 1 << 1,
    	GNOME_VFS_FILE_INFO_FIELDS_FLAGS = 1 << 2,
    	GNOME_VFS_FILE_INFO_FIELDS_DEVICE = 1 << 3,
    	GNOME_VFS_FILE_INFO_FIELDS_INODE = 1 << 4,
    	GNOME_VFS_FILE_INFO_FIELDS_LINK_COUNT = 1 << 5,
    	GNOME_VFS_FILE_INFO_FIELDS_SIZE = 1 << 6,
    	GNOME_VFS_FILE_INFO_FIELDS_BLOCK_COUNT = 1 << 7,
    	GNOME_VFS_FILE_INFO_FIELDS_IO_BLOCK_SIZE = 1 << 8,
    	GNOME_VFS_FILE_INFO_FIELDS_ATIME = 1 << 9,
    	GNOME_VFS_FILE_INFO_FIELDS_MTIME = 1 << 10,
    	GNOME_VFS_FILE_INFO_FIELDS_CTIME = 1 << 11,
    	GNOME_VFS_FILE_INFO_FIELDS_SYMLINK_NAME = 1 << 12,
    	GNOME_VFS_FILE_INFO_FIELDS_MIME_TYPE = 1 << 13,
    	GNOME_VFS_FILE_INFO_FIELDS_ACCESS = 1 << 14
    } GnomeVFSFileInfoFields;

Flags indicating what fields in a GnomeVFSFileInfo struct are valid. Name is always assumed valid (how else would you have gotten a FileInfo struct otherwise?)

`GNOME_VFS_FILE_INFO_FIELDS_NONE` | No fields are valid
`GNOME_VFS_FILE_INFO_FIELDS_TYPE` | Type field is valid
`GNOME_VFS_FILE_INFO_FIELDS_PERMISSIONS` | Permissions field is valid
`GNOME_VFS_FILE_INFO_FIELDS_FLAGS` | Flags field is valid
`GNOME_VFS_FILE_INFO_FIELDS_DEVICE` | Device field is valid
`GNOME_VFS_FILE_INFO_FIELDS_INODE` | Inode field is valid
`GNOME_VFS_FILE_INFO_FIELDS_LINK_COUNT` | Link count field is valid
`GNOME_VFS_FILE_INFO_FIELDS_SIZE` | Size field is valid
`GNOME_VFS_FILE_INFO_FIELDS_BLOCK_COUNT` | Block count field is valid
`GNOME_VFS_FILE_INFO_FIELDS_IO_BLOCK_SIZE` | I/O Block Size field is valid
`GNOME_VFS_FILE_INFO_FIELDS_ATIME` | Access time field is valid
`GNOME_VFS_FILE_INFO_FIELDS_MTIME` | Modification time field is valid
`GNOME_VFS_FILE_INFO_FIELDS_CTIME` | Creating time field is valid
`GNOME_VFS_FILE_INFO_FIELDS_SYMLINK_NAME` | Symlink name field is valid
`GNOME_VFS_FILE_INFO_FIELDS_MIME_TYPE` | Mime type field is valid
`GNOME_VFS_FILE_INFO_FIELDS_ACCESS` | Access bits of the permissions bitfield are valid

### enum GnomeVFSFilePermissions

    typedef enum {
    	GNOME_VFS_PERM_SUID = S_ISUID,
    	GNOME_VFS_PERM_SGID = S_ISGID,
    	GNOME_VFS_PERM_STICKY = 01000,	/* S_ISVTX not defined on all systems */
    	GNOME_VFS_PERM_USER_READ = S_IRUSR,
    	GNOME_VFS_PERM_USER_WRITE = S_IWUSR,
    	GNOME_VFS_PERM_USER_EXEC = S_IXUSR,
    	GNOME_VFS_PERM_USER_ALL = S_IRUSR | S_IWUSR | S_IXUSR,
    	GNOME_VFS_PERM_GROUP_READ = S_IRGRP,
    	GNOME_VFS_PERM_GROUP_WRITE = S_IWGRP,
    	GNOME_VFS_PERM_GROUP_EXEC = S_IXGRP,
    	GNOME_VFS_PERM_GROUP_ALL = S_IRGRP | S_IWGRP | S_IXGRP,
    	GNOME_VFS_PERM_OTHER_READ = S_IROTH,
    	GNOME_VFS_PERM_OTHER_WRITE = S_IWOTH,
    	GNOME_VFS_PERM_OTHER_EXEC = S_IXOTH,
    	GNOME_VFS_PERM_OTHER_ALL = S_IROTH | S_IWOTH | S_IXOTH,
    	GNOME_VFS_PERM_ACCESS_READABLE   = 1 << 16,
    	GNOME_VFS_PERM_ACCESS_WRITABLE   = 1 << 17,
    	GNOME_VFS_PERM_ACCESS_EXECUTABLE = 1 << 18
    } GnomeVFSFilePermissions;

File permissions. These are the same as the Unix ones, but we wrap them into a nicer VFS-like enum.

`GNOME_VFS_PERM_SUID` | UID bit
`GNOME_VFS_PERM_SGID` | GID bit
`GNOME_VFS_PERM_STICKY` | Sticky bit.
`GNOME_VFS_PERM_USER_READ` | Owner has read permission
`GNOME_VFS_PERM_USER_WRITE` | Owner has write permission
`GNOME_VFS_PERM_USER_EXEC` | Owner has execution permission
`GNOME_VFS_PERM_USER_ALL` | Owner has all permissions
`GNOME_VFS_PERM_GROUP_READ` | Group has read permission
`GNOME_VFS_PERM_GROUP_WRITE` | Group has write permission
`GNOME_VFS_PERM_GROUP_EXEC` | Group has execution permission
`GNOME_VFS_PERM_GROUP_ALL` | Group has all permissions
`GNOME_VFS_PERM_OTHER_READ` | Others have read permission
`GNOME_VFS_PERM_OTHER_WRITE` | Others have write permission
`GNOME_VFS_PERM_OTHER_EXEC` | Others have execution permission
`GNOME_VFS_PERM_OTHER_ALL` | Others have all permissions
`GNOME_VFS_PERM_ACCESS_READABLE` |
`GNOME_VFS_PERM_ACCESS_WRITABLE` |
`GNOME_VFS_PERM_ACCESS_EXECUTABLE` |

### enum GnomeVFSFileInfoOptions

    typedef enum {
    	GNOME_VFS_FILE_INFO_DEFAULT = 0,
    	GNOME_VFS_FILE_INFO_GET_MIME_TYPE = 1 << 0,
    	GNOME_VFS_FILE_INFO_FORCE_FAST_MIME_TYPE = 1 << 1,
    	GNOME_VFS_FILE_INFO_FORCE_SLOW_MIME_TYPE = 1 << 2,
    	GNOME_VFS_FILE_INFO_FOLLOW_LINKS = 1 << 3,
    	GNOME_VFS_FILE_INFO_GET_ACCESS_RIGHTS = 1 << 4
    } GnomeVFSFileInfoOptions;

Packed boolean bitfield representing options that can be passed into a `gnome_vfs_get_file_info()` call (or other related calls that return file info) and affect the operation of get_file_info.

`GNOME_VFS_FILE_INFO_DEFAULT` | default flags
`GNOME_VFS_FILE_INFO_GET_MIME_TYPE` | detect the MIME type
`GNOME_VFS_FILE_INFO_FORCE_FAST_MIME_TYPE` | only use fast MIME type detection (extensions)
`GNOME_VFS_FILE_INFO_FORCE_SLOW_MIME_TYPE` | force slow MIME type detection where available (sniffing, algorithmic detection, etc)
`GNOME_VFS_FILE_INFO_FOLLOW_LINKS` | automatically follow symbolic links and retrieve the properties of their target (recommended)
`GNOME_VFS_FILE_INFO_GET_ACCESS_RIGHTS` | tries to get data similar to what would return access(2) on a local file system (ie is the file readable, writable and/or executable). Can be really slow on remote file systems

### enum GnomeVFSSetFileInfoMask

    typedef enum {
    	GNOME_VFS_SET_FILE_INFO_NONE = 0,
    	GNOME_VFS_SET_FILE_INFO_NAME = 1 << 0,
    	GNOME_VFS_SET_FILE_INFO_PERMISSIONS = 1 << 1,
    	GNOME_VFS_SET_FILE_INFO_OWNER = 1 << 2,
    	GNOME_VFS_SET_FILE_INFO_TIME = 1 << 3
    } GnomeVFSSetFileInfoMask;

Packed boolean bitfield representing the aspects of the file to be changed in a `gnome_vfs_set_file_info()` call.

`GNOME_VFS_SET_FILE_INFO_NONE` | don't set any file info fields
`GNOME_VFS_SET_FILE_INFO_NAME` | change the name
`GNOME_VFS_SET_FILE_INFO_PERMISSIONS` | change the permissions
`GNOME_VFS_SET_FILE_INFO_OWNER` | change the file's owner
`GNOME_VFS_SET_FILE_INFO_TIME` | change the file's time stamp(s)

### GnomeVFSGetFileInfoResult

    typedef struct {
    	GnomeVFSURI *uri;
    	GnomeVFSResult result;
    	GnomeVFSFileInfo *file_info;
    } GnomeVFSGetFileInfoResult;

### GnomeVFSInodeNumber

    typedef GnomeVFSFileSize GnomeVFSInodeNumber;

Represents the i-node of a file, this is a low level data structure that the operating system uses to hold information about a file.

### GnomeVFSFileInfo

    typedef struct {
    	/* Base name of the file (no path).  */
    	char *name;

    	/* Fields which are actually valid in this structure. */
    	GnomeVFSFileInfoFields valid_fields;

    	/* File type (i.e. regular, directory, block device...).  */
    	GnomeVFSFileType type;

    	/* File permissions.  */
    	GnomeVFSFilePermissions permissions;

    	/* Flags for this file.  */
    	GnomeVFSFileFlags flags;

    	/* These are only valid if `is_local' is TRUE (see below).  */
    	dev_t device;
    	GnomeVFSInodeNumber inode;

    	/* Link count.  */
    	guint link_count;

    	/* UID, GID.  */
    	guint uid;
    	guint gid;

    	/* Size in bytes.  */
    	GnomeVFSFileSize size;

    	/* Size measured in units of 512-byte blocks.  */
    	GnomeVFSFileSize block_count;

    	/* Optimal buffer size for reading/writing the file.  */
    	guint io_block_size;

    	/* Access, modification and change times.  */
    	time_t atime;
    	time_t mtime;
    	time_t ctime;

    	/* If the file is a symlink (see `flags'), this specifies the file the
               link points to.  */
    	char *symlink_name;

    	/* MIME type.  -- ascii string */
    	char *mime_type;

    	guint refcount;

    	/* Reserved for future expansions to GnomeVFSFileInfo without having
    	   to break ABI compatibility */
    	void *reserved1;
    	void *reserved2;
    	void *reserved3;
    	void *reserved4;
    	void *reserved5;
    } GnomeVFSFileInfo;

The GnomeVFSFileInfo structure contains information about a file.

### GNOME_VFS_FILE_INFO_SYMLINK()

    #define     GNOME_VFS_FILE_INFO_SYMLINK(info)

Determines whether a file is a symbolic link given `info`.

`info` : | GnomeVFSFileInfo struct

### GNOME_VFS_FILE_INFO_SET_SYMLINK()

    #define     GNOME_VFS_FILE_INFO_SET_SYMLINK(info, value)

Set the symbolic link field in `info` to `value`.

`info` : | GnomeVFSFileInfo struct
`value` : | if `TRUE`, `info` is set to indicate the file is a symbolic link

### GNOME_VFS_FILE_INFO_LOCAL()

    #define     GNOME_VFS_FILE_INFO_LOCAL(info)

Determines whether a file is local given `info`.

`info` : | GnomeVFSFileInfo struct

### GNOME_VFS_FILE_INFO_SET_LOCAL()

    #define     GNOME_VFS_FILE_INFO_SET_LOCAL(info, value)

Set the "local file" field in `info` to `value`.

`info` : | GnomeVFSFileInfo struct
`value` : | if `TRUE`, `info` is set to indicate the file is local

### GNOME_VFS_FILE_INFO_SUID()

    #define     GNOME_VFS_FILE_INFO_SUID(info)

Determines whether a file belongs to the super user.

`info` : | GnomeVFSFileInfo struct

### GNOME_VFS_FILE_INFO_SGID()

    #define     GNOME_VFS_FILE_INFO_SGID(info)

Determines whether a file belongs to the super user's group.

`info` : | GnomeVFSFileInfo struct

### GNOME_VFS_FILE_INFO_STICKY()

    #define     GNOME_VFS_FILE_INFO_STICKY(info)

Determines whether a file has the sticky bit set, given `info`

`info` : | GnomeVFSFileInfo struct

### GNOME_VFS_FILE_INFO_SET_SUID()

    #define     GNOME_VFS_FILE_INFO_SET_SUID(info, value)

Set the SUID field in `info` to `value`.

`info` : | GnomeVFSFileInfo struct
`value` : | if `TRUE`, `info` is set to indicate the file belongs to the super user

### GNOME_VFS_FILE_INFO_SET_SGID()

    #define     GNOME_VFS_FILE_INFO_SET_SGID(info, value)

Set the SGID field in `info` to `value`.

`info` : | GnomeVFSFileInfo struct
`value` : | if `TRUE`, `info` is set to indicate the file belongs to the super user's group

### GNOME_VFS_FILE_INFO_SET_STICKY()

    #define     GNOME_VFS_FILE_INFO_SET_STICKY(info, value)

Set the sticky bit in `info` to `value`.

`info` : | GnomeVFSFileInfo struct
`value` : | if `TRUE`, `info` is set to indicate the file has the sticky bit set

### gnome_vfs_file_info_new ()

    GnomeVFSFileInfo* gnome_vfs_file_info_new   (void);

Allocate and initialize a new file information struct.

Returns : | A pointer to the new file information struct.

### gnome_vfs_file_info_unref ()

    void        gnome_vfs_file_info_unref       (GnomeVFSFileInfo *info);

Destroy `info`

`info` : | Pointer to a file information struct

### gnome_vfs_file_info_ref ()

    void        gnome_vfs_file_info_ref         (GnomeVFSFileInfo *info);

Increment reference count

`info` : | Pointer to a file information struct

### gnome_vfs_file_info_clear ()

    void        gnome_vfs_file_info_clear       (GnomeVFSFileInfo *info);

Clear `info` so that it's ready to accept new data. This is supposed to be used when `info` already contains meaningful information which we want to replace.

`info` : | Pointer to a file information struct

### gnome_vfs_file_info_get_mime_type ()

    const char* gnome_vfs_file_info_get_mime_type
                                                (GnomeVFSFileInfo *info);

Retrieve MIME type from `info`. There is no need to free the return value.

`info` : | A pointer to a file information struct
Returns : | A pointer to a string representing the MIME type.

### gnome_vfs_file_info_copy ()

    void        gnome_vfs_file_info_copy        (GnomeVFSFileInfo *dest,
                                                 const GnomeVFSFileInfo *src);

Copy information from `src` into `dest`.

`dest` : | Pointer to a struct to copy `src`'s information into
`src` : | Pointer to the information to be copied into `dest`

### gnome_vfs_file_info_dup ()

    GnomeVFSFileInfo* gnome_vfs_file_info_dup   (const GnomeVFSFileInfo *orig);

Duplicates `orig` and returns it.

`orig` : | Pointer to a file information structure to duplicate
Returns : | a new file information struct that duplicates the information in `orig`.

### gnome_vfs_file_info_matches ()

    gboolean    gnome_vfs_file_info_matches     (const GnomeVFSFileInfo *a,
                                                 const GnomeVFSFileInfo *b);

Compare the two file info structs, return TRUE if they match exactly the same file data.

`a` : | first GnomeVFSFileInfo struct to compare
`b` : | second GnomeVFSFileInfo struct to compare
Returns : | TRUE if the two GnomeVFSFileInfos match, otherwise return FALSE.

### gnome_vfs_file_info_list_ref ()

    GList*      gnome_vfs_file_info_list_ref    (GList *list);

Increments the reference count of the items in `list` by one.

`list` : | list of GnomeVFSFileInfo elements
Returns : | `list`

### gnome_vfs_file_info_list_unref ()

    GList*      gnome_vfs_file_info_list_unref  (GList *list);

Decrements the reference count of the items in `list` by one. Note that the list is *not freed* even if each member of the list is freed.

`list` : | list of GnomeVFSFileInfo elements
Returns : | `list`

### gnome_vfs_file_info_list_copy ()

    GList*      gnome_vfs_file_info_list_copy   (GList *list);

Creates a duplicate of `list`, and references each member of that list.

`list` : | list of GnomeVFSFileInfo elements
Returns : | a newly referenced duplicate of `list`

### gnome_vfs_file_info_list_free ()

    void        gnome_vfs_file_info_list_free   (GList *list);

Decrements the reference count of each member of `list` by one, and frees the list itself.

`list` : | list of GnomeVFSFileInfo elements