FmFileInfo

## FmFileInfo FmFileInfo — File information cache for libfm. |

## Synopsis

    #define             FM_FILE_INFO                        (ptr)
                        FmFileInfo;
    gboolean            fm_file_info_can_set_hidden         (FmFileInfo *fi);
    gboolean            fm_file_info_can_set_icon           (FmFileInfo *fi);
    gboolean            fm_file_info_can_set_name           (FmFileInfo *fi);
    gboolean            fm_file_info_can_thumbnail          (FmFileInfo *fi);
    time_t              fm_file_info_get_atime              (FmFileInfo *fi);
    goffset             fm_file_info_get_blocks             (FmFileInfo *fi);
    const char *        fm_file_info_get_collate_key        (FmFileInfo *fi);
    const char *        fm_file_info_get_collate_key_nocasefold
                                                            (FmFileInfo *fi);
    time_t              fm_file_info_get_ctime              (FmFileInfo *fi);
    const char *        fm_file_info_get_desc               (FmFileInfo *fi);
    dev_t               fm_file_info_get_dev                (FmFileInfo *fi);
    const char *        fm_file_info_get_disp_group         (FmFileInfo *fi);
    const char *        fm_file_info_get_disp_mtime         (FmFileInfo *fi);
    const char *        fm_file_info_get_disp_name          (FmFileInfo *fi);
    const char *        fm_file_info_get_disp_owner         (FmFileInfo *fi);
    const char *        fm_file_info_get_disp_size          (FmFileInfo *fi);
    const char *        fm_file_info_get_fs_id              (FmFileInfo *fi);
    gid_t               fm_file_info_get_gid                (FmFileInfo *fi);
    FmIcon *            fm_file_info_get_icon               (FmFileInfo *fi);
    FmMimeType *        fm_file_info_get_mime_type          (FmFileInfo *fi);
    mode_t              fm_file_info_get_mode               (FmFileInfo *fi);
    time_t              fm_file_info_get_mtime              (FmFileInfo *fi);
    const char *        fm_file_info_get_name               (FmFileInfo *fi);
    FmPath *            fm_file_info_get_path               (FmFileInfo *fi);
    goffset             fm_file_info_get_size               (FmFileInfo *fi);
    const char *        fm_file_info_get_target             (FmFileInfo *fi);
    uid_t               fm_file_info_get_uid                (FmFileInfo *fi);
    gboolean            fm_file_info_is_accessible          (FmFileInfo *fi);
    gboolean            fm_file_info_is_backup              (FmFileInfo *fi);
    gboolean            fm_file_info_is_desktop_entry       (FmFileInfo *fi);
    gboolean            fm_file_info_is_dir                 (FmFileInfo *fi);
    gboolean            fm_file_info_is_executable_type     (FmFileInfo *fi);
    gboolean            fm_file_info_is_hidden              (FmFileInfo *fi);
    gboolean            fm_file_info_is_image               (FmFileInfo *fi);
    gboolean            fm_file_info_is_mountable           (FmFileInfo *fi);
    gboolean            fm_file_info_is_native              (FmFileInfo *fi);
    gboolean            fm_file_info_is_shortcut            (FmFileInfo *fi);
    gboolean            fm_file_info_is_symlink             (FmFileInfo *fi);
    gboolean            fm_file_info_is_text                (FmFileInfo *fi);
    gboolean            fm_file_info_is_unknown_type        (FmFileInfo *fi);
    gboolean            fm_file_info_is_writable_directory  (FmFileInfo *fi);
    gboolean            fm_file_info_list_is_same_fs        (FmFileInfoList *list);
    gboolean            fm_file_info_list_is_same_type      (FmFileInfoList *list);
    FmFileInfoList *    fm_file_info_list_new               ();
    FmFileInfo *        fm_file_info_new                    ();
    FmFileInfo *        fm_file_info_new_from_g_file_data   (GFile *gf,
                                                             GFileInfo *inf,
                                                             FmPath *path);
    FmFileInfo *        fm_file_info_new_from_gfileinfo     (FmPath *path,
                                                             GFileInfo *inf);
    FmFileInfo *        fm_file_info_new_from_menu_cache_item
                                                            (FmPath *path,
                                                             struct _MenuCacheItem *item);
    FmFileInfo *        fm_file_info_new_from_native_file   (FmPath *path,
                                                             const char *path_str,
                                                             GError **err);
    FmFileInfo *        fm_file_info_ref                    (FmFileInfo *fi);
    void                fm_file_info_set_disp_name          (FmFileInfo *fi,
                                                             const char *name);
    void                fm_file_info_set_from_g_file_data   (FmFileInfo *fi,
                                                             GFile *gf,
                                                             GFileInfo *inf);
    void                fm_file_info_set_from_gfileinfo     (FmFileInfo *fi,
                                                             GFileInfo *inf);
    void                fm_file_info_set_from_menu_cache_item
                                                            (FmFileInfo *fi,
                                                             struct _MenuCacheItem *item);
    gboolean            fm_file_info_set_from_native_file   (FmFileInfo *fi,
                                                             const char *path,
                                                             GError **err);
    void                fm_file_info_set_icon               (FmFileInfo *fi,
                                                             GIcon *icon);
    void                fm_file_info_set_path               (FmFileInfo *fi,
                                                             FmPath *path);
    void                fm_file_info_unref                  (FmFileInfo *fi);
    void                fm_file_info_update                 (FmFileInfo *fi,
                                                             FmFileInfo *src);

## Description

`include`: libfm/fm.h

## Details

### FM_FILE_INFO()

    #define FM_FILE_INFO(ptr)    ((FmFileInfo*)ptr)

### FmFileInfo

    typedef struct _FmFileInfo FmFileInfo;

### fm_file_info_can_set_hidden ()

    gboolean            fm_file_info_can_set_hidden         (FmFileInfo *fi);

Checks if file system supports "hidden" attribute change for `fi`. Returned value `TRUE` is just a potential possibility, the attribute still may be unable to change due to access reasons for example.

`fi` : | a FmFileInfo to inspect
Returns : | `TRUE` if change is supported for `fi`.

Since 1.2.0

### fm_file_info_can_set_icon ()

    gboolean            fm_file_info_can_set_icon           (FmFileInfo *fi);

Checks if file system supports icon change for `fi`. Returned value `TRUE` is just a potential possibility, icon still may be unable to change due to access reasons for example.

`fi` : | a FmFileInfo to inspect
Returns : | `TRUE` if change is supported for `fi`.

Since 1.2.0

### fm_file_info_can_set_name ()

    gboolean            fm_file_info_can_set_name           (FmFileInfo *fi);

Checks if file system supports name change for `fi`. Returned value `TRUE` is just a potential possibility, name still may be unable to change due to access reasons for example.

`fi` : | a FmFileInfo to inspect
Returns : | `TRUE` if change is supported for `fi`.

Since 1.2.0

### fm_file_info_can_thumbnail ()

    gboolean            fm_file_info_can_thumbnail          (FmFileInfo *fi);

### fm_file_info_get_atime ()

    time_t              fm_file_info_get_atime              (FmFileInfo *fi);

`fi` : | A FmFileInfo struct
Returns : | file access time.

### fm_file_info_get_blocks ()

    goffset             fm_file_info_get_blocks             (FmFileInfo *fi);

`fi` : | A FmFileInfo struct
Returns : | how many filesystem blocks used by the file.

### fm_file_info_get_collate_key ()

    const char *        fm_file_info_get_collate_key        (FmFileInfo *fi);

Get the collate key used for locale-dependent filename sorting. The keys of different files can be compared with `strcmp()` directly.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed.

### fm_file_info_get_collate_key_nocasefold ()

    const char *        fm_file_info_get_collate_key_nocasefold
                                                            (FmFileInfo *fi);

Get the collate key used for locale-dependent filename sorting but in case-sensitive manner. The keys of different files can be compared with `strcmp()` directly. Returned data are owned by FmFileInfo and should be not freed by caller.

This API is not thread-safe and should be used only in default context.

See also: `fm_file_info_get_collate_key()`.

`fi` : | a FmFileInfo struct
Returns : | collate string.

Since 1.0.2

### fm_file_info_get_ctime ()

    time_t              fm_file_info_get_ctime              (FmFileInfo *fi);

Retrieves time when access right were changed last time for file `fi`.

`fi` : | a file info to inspect
Returns : | file access change time.

Since 1.2.0

### fm_file_info_get_desc ()

    const char *        fm_file_info_get_desc               (FmFileInfo *fi);

Get a human-readable description for the file.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed.

### fm_file_info_get_dev ()

    dev_t               fm_file_info_get_dev                (FmFileInfo *fi);

Get the filesystem device id (POSIX dev_t) This is only applicable when the file is native. e.g. `fm_file_info_is_native()` returns TRUE.

`fi` : | A FmFileInfo struct
Returns : | device id (POSIX dev_t, st_dev member of struct stat).

### fm_file_info_get_disp_group ()

    const char *        fm_file_info_get_disp_group         (FmFileInfo *fi);

Retrieves human-readable string value for group of `fi`. Returned value is either group name or numeric string if grop has no entry in the /etc/group file. Returned value is owned by `fi` and should be not altered by caller.

`fi` : | file info to inspect
Returns : | string value for file group. [transfer none]

Since 1.2.0

### fm_file_info_get_disp_mtime ()

    const char *        fm_file_info_get_disp_mtime         (FmFileInfo *fi);

Get a human-readable string for showing file modification time in the UI.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed.

### fm_file_info_get_disp_name ()

    const char *        fm_file_info_get_disp_name          (FmFileInfo *fi);

Get the display name used to show the file in the file manager UI. The display name is guaranteed to be UTF-8 and may be different from the real file name on the filesystem.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const strin owned by FmFileInfo which should not be freed.

### fm_file_info_get_disp_owner ()

    const char *        fm_file_info_get_disp_owner         (FmFileInfo *fi);

Retrieves human-readable string value for owner of `fi`. Returned value is either owner login name or numeric string if owner has no entry in /etc/passwd file. Returned value is owned by `fi` and should be not altered by caller.

`fi` : | file info to inspect
Returns : | string value for owner. [transfer none]

Since 1.2.0

### fm_file_info_get_disp_size ()

    const char *        fm_file_info_get_disp_size          (FmFileInfo *fi);

Get the size of the file as a human-readable string. It's convinient for show the file size to the user.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed. (non-NULL)

### fm_file_info_get_fs_id ()

    const char *        fm_file_info_get_fs_id              (FmFileInfo *fi);

Get the filesystem id string This is only applicable when the file is on a remote filesystem. e.g. `fm_file_info_is_native()` returns FALSE.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed.

### fm_file_info_get_gid ()

    gid_t               fm_file_info_get_gid                (FmFileInfo *fi);

`fi` : | A FmFileInfo struct
Returns : | group id (gid) of the file owner.

### fm_file_info_get_icon ()

    FmIcon *            fm_file_info_get_icon               (FmFileInfo *fi);

Get the icon used to show the file in the file manager.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a FmIcon struct. The returned FmIcon struct is owned by FmFileInfo and should not be freed. If you need to keep it, use `g_object_ref()` to obtain a reference.

### fm_file_info_get_mime_type ()

    FmMimeType *        fm_file_info_get_mime_type          (FmFileInfo *fi);

Get the mime-type of the file.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a FmMimeType struct owned by FmFileInfo which should not be freed. If you need to keep it, use `fm_mime_type_ref()` to obtain a reference.

### fm_file_info_get_mode ()

    mode_t              fm_file_info_get_mode               (FmFileInfo *fi);

Get the mode of the file. For detail about the meaning of mode, see manpage of `stat()` and the st_mode struct field.

`fi` : | A FmFileInfo struct
Returns : | mode_t value of the file as defined in POSIX struct stat.

### fm_file_info_get_mtime ()

    time_t              fm_file_info_get_mtime              (FmFileInfo *fi);

`fi` : | A FmFileInfo struct
Returns : | file modification time.

### fm_file_info_get_name ()

    const char *        fm_file_info_get_name               (FmFileInfo *fi);

Get the base name of the file in filesystem encoding.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed.

### fm_file_info_get_path ()

    FmPath *            fm_file_info_get_path               (FmFileInfo *fi);

Get the path of the file

`fi` : | A FmFileInfo struct
Returns : | a FmPath struct. The returned FmPath struct is owned by FmFileInfo and should not be freed. If you need to keep it, use `fm_path_ref()` to obtain a reference.

### fm_file_info_get_size ()

    goffset             fm_file_info_get_size               (FmFileInfo *fi);

`fi` : | A FmFileInfo struct
Returns : | the size of the file in bytes.

### fm_file_info_get_target ()

    const char *        fm_file_info_get_target             (FmFileInfo *fi);

Get the target of a symlink or a shortcut.

This API is not thread-safe and should be used only in default context.

`fi` : | A FmFileInfo struct
Returns : | a const string owned by FmFileInfo which should not be freed. NULL if the file is not a symlink or shortcut.

### fm_file_info_get_uid ()

    uid_t               fm_file_info_get_uid                (FmFileInfo *fi);

`fi` : | A FmFileInfo struct
Returns : | user id (uid) of the file owner.

### fm_file_info_is_accessible ()

    gboolean            fm_file_info_is_accessible          (FmFileInfo *fi);

Checks if the user has read access to file or directory `fi`.

`fi` : | a file info descriptor
Returns : | `TRUE` if `fi` is accessible for user.

Since 1.0.1

### fm_file_info_is_backup ()

    gboolean            fm_file_info_is_backup              (FmFileInfo *fi);

Checks if file is backup. Native files are considered backup if they have ~ suffix.

`fi` : | A FmFileInfo struct
Returns : | `TRUE` if the file is a backup file.

Since 1.2.0

### fm_file_info_is_desktop_entry ()

    gboolean            fm_file_info_is_desktop_entry       (FmFileInfo *fi);

### fm_file_info_is_dir ()

    gboolean            fm_file_info_is_dir                 (FmFileInfo *fi);

### fm_file_info_is_executable_type ()

    gboolean            fm_file_info_is_executable_type     (FmFileInfo *fi);

### fm_file_info_is_hidden ()

    gboolean            fm_file_info_is_hidden              (FmFileInfo *fi);

### fm_file_info_is_image ()

    gboolean            fm_file_info_is_image               (FmFileInfo *fi);

### fm_file_info_is_mountable ()

    gboolean            fm_file_info_is_mountable           (FmFileInfo *fi);

Checks if `fi` is "inode/mount-point" type.

`fi` : | file info to inspect
Returns : | `TRUE` if `fi` is mountable type.

### fm_file_info_is_native ()

    gboolean            fm_file_info_is_native              (FmFileInfo *fi);

### fm_file_info_is_shortcut ()

    gboolean            fm_file_info_is_shortcut            (FmFileInfo *fi);

### fm_file_info_is_symlink ()

    gboolean            fm_file_info_is_symlink             (FmFileInfo *fi);

### fm_file_info_is_text ()

    gboolean            fm_file_info_is_text                (FmFileInfo *fi);

### fm_file_info_is_unknown_type ()

    gboolean            fm_file_info_is_unknown_type        (FmFileInfo *fi);

### fm_file_info_is_writable_directory ()

    gboolean            fm_file_info_is_writable_directory  (FmFileInfo *fi);

Checks if directory `fi` lies on writable file system. Returned value `TRUE` is just a potential possibility, it may still not allow write due to access reasons for example.

`fi` : | a FmFileInfo to inspect
Returns : | `TRUE` if `fi` may be writable.

Since 1.2.0

### fm_file_info_list_is_same_fs ()

    gboolean            fm_file_info_list_is_same_fs        (FmFileInfoList *list);

Checks if all files in the list are on the same file system.

`list` : | a FmFileInfoList
Returns : | `TRUE` if all files in the list are on the same fs.

### fm_file_info_list_is_same_type ()

    gboolean            fm_file_info_list_is_same_type      (FmFileInfoList *list);

Checks if all files in the list are of the same type.

`list` : | a FmFileInfoList
Returns : | `TRUE` if all files in the list are of the same type

### fm_file_info_list_new ()

    FmFileInfoList *    fm_file_info_list_new               ();

Creates a new FmFileInfoList.

Returns : | new FmFileInfoList object.

### fm_file_info_new ()

    FmFileInfo *        fm_file_info_new                    ();

Returns : | a new FmFileInfo struct which needs to be freed with `fm_file_info_unref()` when it's no more needed.

### fm_file_info_new_from_g_file_data ()

    FmFileInfo *        fm_file_info_new_from_g_file_data   (GFile *gf,
                                                             GFileInfo *inf,
                                                             FmPath *path);

Creates a new FmFileInfo for file pointed by `path` and `gf` based on information stored in the `inf`. Returned data should be freed with `fm_file_info_unref()` when no longer needed.

`gf` : | a GFile of a file
`inf` : | a GFileInfo object
`path` : | a FmPath of a file. [allow-none]
Returns : | a new FmFileInfo struct. [transfer full]

Since 1.2.0

### fm_file_info_new_from_gfileinfo ()

    FmFileInfo *        fm_file_info_new_from_gfileinfo     (FmPath *path,
                                                             GFileInfo *inf);

### Warning

`fm_file_info_new_from_gfileinfo` has been deprecated since version 1.2.0 and should not be used in newly-written code. Use `fm_file_info_new_from_g_file_data()` instead.

Create a new FmFileInfo for file pointed by `path` based on information stored in the GFileInfo object.

`path` : | FmPath of a file
`inf` : | a GFileInfo object
Returns : | A new FmFileInfo struct which should be freed with `fm_file_info_unref()` when no longer needed.

### fm_file_info_new_from_menu_cache_item ()

    FmFileInfo *        fm_file_info_new_from_menu_cache_item
                                                            (FmPath *path,
                                                             struct _MenuCacheItem *item);

Creates a new FmFileInfo for a file by `path` and fills it with info from a menu cache `item`. Returned data should be freed with `fm_file_info_unref()` when no longer needed.

`path` : | a file path
`item` : | a menu cache item
Returns : | a new FmFileInfo struct. [transfer full]

Since 0.1.1

### fm_file_info_new_from_native_file ()

    FmFileInfo *        fm_file_info_new_from_native_file   (FmPath *path,
                                                             const char *path_str,
                                                             GError **err);

Create a new FmFileInfo for file pointed by `path`. Returned data should be freed with `fm_file_info_unref()` after usage.

`path` : | path descriptor. [allow-none]
`path_str` : | full path to the file
`err` : | pointer to receive error. [allow-none][out]
Returns : | new file info or `NULL` in case of error. [transfer full]

Since 1.2.0

### fm_file_info_ref ()

    FmFileInfo *        fm_file_info_ref                    (FmFileInfo *fi);

Increase reference count of the FmFileInfo struct.

`fi` : | A FmFileInfo struct
Returns : | the FmFileInfo struct itself

### fm_file_info_set_disp_name ()

    void                fm_file_info_set_disp_name          (FmFileInfo *fi,
                                                             const char *name);

Set the display name used to show the file in the file manager UI. If NULL is passed for `name`, the original display will be freed and the real base name will be used for display.

`fi` : | A FmFileInfo struct
`name` : | A UTF-8 display name. (can be NULL).

### fm_file_info_set_from_g_file_data ()

    void                fm_file_info_set_from_g_file_data   (FmFileInfo *fi,
                                                             GFile *gf,
                                                             GFileInfo *inf);

Get file info from the GFile and GFileInfo objects and sets data in the FmFileInfo struct appropriately.

`fi` : | a FmFileInfo struct to update
`gf` : | a GFile object to inspect. [allow-none]
`inf` : | a GFileInfo object to inspect

Since 1.2.0

### fm_file_info_set_from_gfileinfo ()

    void                fm_file_info_set_from_gfileinfo     (FmFileInfo *fi,
                                                             GFileInfo *inf);

### Warning

`fm_file_info_set_from_gfileinfo` has been deprecated since version 1.2.0 and should not be used in newly-written code. Use `fm_file_info_set_from_g_file_data()` instead.

Get file info from the GFileInfo object and store it in the FmFileInfo struct.

`fi` : | A FmFileInfo struct
`inf` : | a GFileInfo object

### fm_file_info_set_from_menu_cache_item ()

    void                fm_file_info_set_from_menu_cache_item
                                                            (FmFileInfo *fi,
                                                             struct _MenuCacheItem *item);

### Warning

`fm_file_info_set_from_menu_cache_item` has been deprecated since version 1.2.0 and should not be used in newly-written code.

`fi` : | a file info to update
`item` : | a menu cache item

### fm_file_info_set_from_native_file ()

    gboolean            fm_file_info_set_from_native_file   (FmFileInfo *fi,
                                                             const char *path,
                                                             GError **err);

Get file info of the specified native file and store it in the FmFileInfo struct.

Prior to calling this function, the FmPath of FmFileInfo should have been set with `fm_file_info_set_path()`.

Note that this call does I/O and therefore can block.

`fi` : | A FmFileInfo struct
`path` : | full path of the file
`err` : | a GError** to retrive errors
Returns : | TRUE if no error happens.

### fm_file_info_set_icon ()

    void                fm_file_info_set_icon               (FmFileInfo *fi,
                                                             GIcon *icon);

Updates the icon used to show the file in the file manager UI.

`fi` : | a FmFileInfo
`icon` : | an icon to update

Since 1.2.0

### fm_file_info_set_path ()

    void                fm_file_info_set_path               (FmFileInfo *fi,
                                                             FmPath *path);

This API is not thread-safe and should be used only in default context.

Change the path of the FmFileInfo.

`fi` : | A FmFileInfo struct
`path` : | a FmPath struct

### fm_file_info_unref ()

    void                fm_file_info_unref                  (FmFileInfo *fi);

Decrease reference count of the FmFileInfo struct. When the last reference to the struct is released, the FmFileInfo struct is freed.

`fi` : | A FmFileInfo struct

### fm_file_info_update ()

    void                fm_file_info_update                 (FmFileInfo *fi,
                                                             FmFileInfo *src);

This API is not thread-safe and should be used only in default context.

Update the content of `fi` by copying file info stored in `src` to `fi`.

`fi` : | A FmFileInfo struct
`src` : | another FmFileInfo struct