## FmPath

FmPath — Path representation for libfm.

## Functions

#define | FM_PATH()
FmPath * | fm_path_new_for_path ()
FmPath * | fm_path_new_for_uri ()
FmPath * | fm_path_new_for_display_name ()
FmPath * | fm_path_new_for_str ()
FmPath * | fm_path_new_for_commandline_arg ()
FmPath * | fm_path_new_child ()
FmPath * | fm_path_new_child_len ()
FmPath * | fm_path_new_relative ()
FmPath * | fm_path_new_for_gfile ()
FmPath * | fm_path_get_root ()
FmPath * | fm_path_get_home ()
FmPath * | fm_path_get_desktop ()
FmPath * | fm_path_get_trash ()
FmPath * | fm_path_get_apps_menu ()
FmPath * | fm_path_ref ()
void | fm_path_unref ()
FmPath * | fm_path_get_parent ()
const char * | fm_path_get_basename ()
FmPathFlags | fm_path_get_flags ()
gboolean | fm_path_has_prefix ()
FmPath * | fm_path_get_scheme_path ()
#define | fm_path_is_native()
#define | fm_path_is_trash()
#define | fm_path_is_trash_root()
#define | fm_path_is_native_or_trash()
#define | fm_path_is_local()
#define | fm_path_is_virtual()
#define | fm_path_is_xdg_menu()
char * | fm_path_to_str ()
char * | fm_path_to_uri ()
GFile * | fm_path_to_gfile ()
char * | fm_path_display_name ()
char * | fm_path_display_basename ()
guint | fm_path_hash ()
gboolean | fm_path_equal ()
int | fm_path_compare ()
gboolean | fm_path_equal_str ()
int | fm_path_depth ()
FmPathList * | fm_path_list_new ()
FmPathList * | fm_path_list_new_from_uri_list ()
FmPathList * | fm_path_list_new_from_uris ()
FmPathList * | fm_path_list_new_from_file_info_list ()
FmPathList * | fm_path_list_new_from_file_info_glist ()
FmPathList * | fm_path_list_new_from_file_info_gslist ()
char * | fm_path_list_to_uri_list ()
void | fm_path_list_write_uri_list ()

## Types and Values

enum | FmPathFlags
| FmFileInfoList
| FmPath
| FmPathList

## Description

`include` : libfm/fm.h

## Functions

### FM_PATH()

    #define FM_PATH(path)   ((FmPath*)path)

### fm_path_new_for_path ()

    FmPath *
    fm_path_new_for_path (const char *path_name);

#### Parameters

path_name | a POSIX path. | [allow-none]

#### Returns

a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_uri ()

    FmPath *
    fm_path_new_for_uri (const char *uri);

Creates new FmPath by given `uri` . You have to call `fm_path_unref()` when it's no longer needed.

You can call `fm_path_to_uri()` to convert a FmPath to a escaped URI string.

This function never fail but it may return root path if URI is local and contains illegal characters in path elements such as '/'.

#### Parameters

uri | a URI with special characters escaped. | [allow-none]

#### Returns

a new FmPath for the `uri` .

[transfer full]

### fm_path_new_for_display_name ()

    FmPath *
    fm_path_new_for_display_name (const char *path_name);

The `path_name` can either be a POSIX path in UTF-8 encoding, or an unescaped URI (can contain non-ASCII characters and spaces). Returned data should be freed with `fm_path_unref()` when it's no longer needed. Display name may be fully unrelated to it's path name and built path may be inexistant. Use FmJob to check and validate its existance.

#### Parameters

path_name | an UTF-8 encoded display path name |

#### Returns

a newly created FmPath.

Since: 0.1.14

### fm_path_new_for_str ()

    FmPath *
    fm_path_new_for_str (const char *path_str);

You can call `fm_path_to_str()` to convert a FmPath back to its string presentation.

#### Parameters

path_str | a string representing the file path in its native encoding (can be non-UTF-8). It can either be a native path or an unescaped URI (can contain non-ASCII characters and spaces). The function will try to figure out what to do. | [allow-none]

#### Returns

a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_commandline_arg ()

    FmPath *
    fm_path_new_for_commandline_arg (const char *arg);

#### Parameters

arg | a file path passed in command line argv to the program. The `arg` can be a POSIX path in glib filename encoding (can be non-UTTF-8) and can be a URI with non-ASCII characters escaped, like http://wiki.lxde.org/zh/%E9%A6%96%E9%A0%81. |

#### Returns

a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_child ()

    FmPath *
    fm_path_new_child (FmPath *parent,
                       const char *basename);

Creates new FmPath for child of `parent` directory which have name `basename` . `basename` is in glib filename encoding (can be non-UTF-8) of target filesystem.

#### Parameters

parent | a parent path. | [allow-none]
basename | basename of a direct child of `parent` directory. | [allow-none]

#### Returns

a new FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

[transfer full]

### fm_path_new_child_len ()

    FmPath *
    fm_path_new_child_len (FmPath *parent,
                           const char *basename,
                           int name_len);

Creates new FmPath for child of `parent` directory which have name `basename` . The string length of `basename` is `name_len` . `basename` is in glib filename encoding (can be non-UTF-8) of target filesystem. If `parent` is `NULL` then `basename` assumed to be root of some file system.

#### Parameters

parent | a parent path. | [allow-none]
basename | basename of a direct child of `parent` directory. | [allow-none]
name_len | length of `basename` |

#### Returns

a new FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

[transfer full]

### fm_path_new_relative ()

    FmPath *
    fm_path_new_relative (FmPath *parent,
                          const char *rel);

Creates new FmPath which is relative to `parent` directory by the relative path string `rel` . `rel` is in glib filename encoding (can be non-UTF-8) if `parent` is native and should be escaped URI subpath otherwise. For example, if `parent` is "http://wiki.lxde.org/" and `rel` is "zh/%E9%A6%96%E9%A0%81", the resulting path will be "http://wiki.lxde.org/zh/%E9%A6%96%E9%A0%81".

If `parent` is NULL, this works the same as fm_path_new_for_str(`rel` )

#### Parameters

parent | a parent path. | [allow-none]
rel | a path relative to `parent` . | [allow-none]

#### Returns

a new FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

[transfer full]

### fm_path_new_for_gfile ()

    FmPath *
    fm_path_new_for_gfile (GFile *gf);

This function converts a GFile object to FmPath.

#### Parameters

gf | a GFile object |

#### Returns

a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_get_root ()

    FmPath *
    fm_path_get_root (void);

Retrieves FmPath for root directory. Returned data are owned by `path` and should be not freed by caller.

#### Returns

a path.

Since: 0.1.0

### fm_path_get_home ()

    FmPath *
    fm_path_get_home (void);

Retrieves FmPath for home directory. Returned data are owned by `path` and should be not freed by caller.

#### Returns

a path.

Since: 0.1.0

### fm_path_get_desktop ()

    FmPath *
    fm_path_get_desktop (void);

Retrieves FmPath for desktop directory. Returned data are owned by `path` and should be not freed by caller.

#### Returns

a path.

Since: 0.1.0

### fm_path_get_trash ()

    FmPath *
    fm_path_get_trash (void);

Retrieves FmPath for Trash can. Returned data are owned by `path` and should be not freed by caller.

#### Returns

a path.

Since: 0.1.0

### fm_path_get_apps_menu ()

    FmPath *
    fm_path_get_apps_menu (void);

Retrieves FmPath for menu:// virtual directory. Returned data are owned by `path` and should be not freed by caller.

#### Returns

a path.

Since: 0.1.0

### fm_path_ref ()

    FmPath *
    fm_path_ref (FmPath *path);

Increases reference count on `path` .

#### Parameters

path | an existing FmPath |

#### Returns

`path` .

### fm_path_unref ()

    void
    fm_path_unref (FmPath *path);

Decreases reference count on `path` . When reference count becomes 0 the `path` will be destroyed.

#### Parameters

path | an existing FmPath |

### fm_path_get_parent ()

    FmPath *
    fm_path_get_parent (FmPath *path);

Retrieves path of directory containing `path` . Returned data are owned by `path` and should be not freed by caller.

#### Parameters

path | a path |

#### Returns

path of parent directory or `NULL` if `path` is root path.

[transfer none]

Since: 0.1.0

### fm_path_get_basename ()

    const char *
    fm_path_get_basename (FmPath *path);

Retrieves basename of `path` . Returned data are owned by `path` and should be not freed by caller.

#### Parameters

path | a path |

#### Returns

basename of path.

Since: 0.1.0

### fm_path_get_flags ()

    FmPathFlags
    fm_path_get_flags (FmPath *path);

Retrieves attributes of `path` .

#### Parameters

path | a path |

#### Returns

attributes of path.

Since: 0.1.0

### fm_path_has_prefix ()

    gboolean
    fm_path_has_prefix (FmPath *path,
                        FmPath *prefix);

Check if `prefix` is a prefix of `path` . For example: /usr/share is the prefix of /usr/share/docs/libfm but /etc is not.

#### Parameters

path | a sub path |
prefix | a prefix |

#### Returns

TRUE if `prefix` is the prefix of `path` .

### fm_path_get_scheme_path ()

    FmPath *
    fm_path_get_scheme_path (FmPath *path);

Retrieves a root path for scheme used by `path` . If `path` is a local path then returned data are the same as returned with `fm_path_get_root()`. Returned data are owned by `path` and should be not freed by caller.

#### Parameters

path | a path |

#### Returns

path of root of `path` scheme.

[transfer none]

Since: 1.2.0

### fm_path_is_native()

    #define fm_path_is_native(path) ((fm_path_get_flags(path)&FM_PATH_IS_NATIVE)!=0)

### fm_path_is_trash()

    #define fm_path_is_trash(path) ((fm_path_get_flags(path)&FM_PATH_IS_TRASH)!=0)

### fm_path_is_trash_root()

    #define fm_path_is_trash_root(path) (path == fm_path_get_trash())

### fm_path_is_native_or_trash()

    #define fm_path_is_native_or_trash(path) ((fm_path_get_flags(path)&(FM_PATH_IS_NATIVE|FM_PATH_IS_TRASH))!=0)

### fm_path_is_local()

    #define fm_path_is_local(path) ((fm_path_get_flags(path)&FM_PATH_IS_LOCAL)!=0)

`fm_path_is_local` is deprecated and should not be used in newly-written code.

### fm_path_is_virtual()

    #define fm_path_is_virtual(path) ((fm_path_get_flags(path)&FM_PATH_IS_VIRTUAL)!=0)

`fm_path_is_virtual` is deprecated and should not be used in newly-written code.

### fm_path_is_xdg_menu()

    #define fm_path_is_xdg_menu(path) ((fm_path_get_flags(path)&FM_PATH_IS_XDG_MENU)!=0)

`fm_path_is_xdg_menu` is deprecated and should not be used in newly-written code.

### fm_path_to_str ()

    char *
    fm_path_to_str (FmPath *path);

Creates string representation of `path` . It can be either file path in local encoding or URI with non-ASCII characters escaped (RFC 3986). Returned data should be freed with `g_free()` after usage.

#### Parameters

path | a path |

#### Returns

path string.

[transfer full]

Since: 0.1.0

### fm_path_to_uri ()

    char *
    fm_path_to_uri (FmPath *path);

Creates URI representation of `path` . Returned data should be freed with `g_free()` after usage.

#### Parameters

path | a path |

#### Returns

path URI.

Since: 0.1.0

### fm_path_to_gfile ()

    GFile *
    fm_path_to_gfile (FmPath *path);

Creates GFile representation of `path` . Returned data should be freed with `g_object_unref()` after usage.

#### Parameters

path | a path |

#### Returns

a GFile object.

[transfer full]

Since: 0.1.0

### fm_path_display_name ()

    char *
    fm_path_display_name (FmPath *path,
                          gboolean human_readable);

Creates string representation of `path` as displayable UTF-8 string. The conversion is the most probably unreversible so returned value should be used only for displaying purposes. The displayable path may be reliable only if there was already FmFileInfo retrieved for the `path` , otherwise some estimation will be returned instead, be careful with this API. The main purpose for this API is to create displayable path for the path entry. Applications are encouraged to use `g_file_get_parse_name()` instead for any other purposes. Returned data should be freed with `g_free()` after usage.

See also: `fm_path_display_basename()`, `fm_path_to_str()`.

#### Parameters

path | a path |
human_readable | ignored since 1.2.0 |

#### Returns

path string.

[transfer full]

Since: 0.1.0

### fm_path_display_basename ()

    char *
    fm_path_display_basename (FmPath *path);

Creates displayable basename of `path` . If `path` is a scheme root path (i.e. "/", "sftp://", etc.) then returns basename of `path` . For other paths displayable basename may be reliable only if there was already FmFileInfo retrieved for the `path` , otherwise some estimation will be done instead, be careful with this API. Returned data should be freed with `g_free()` after usage.

See also: `fm_file_info_get_disp_name()`.

#### Parameters

path | a path |

#### Returns

displayable basename of path.

[transfer full]

Since: 0.1.0

### fm_path_hash ()

    guint
    fm_path_hash (FmPath *path);

Converts a path to a hash value.

#### Parameters

path | a path key |

#### Returns

a hash value corresponding to the key.

Since: 0.1.0

### fm_path_equal ()

    gboolean
    fm_path_equal (FmPath *p1,
                   FmPath *p2);

Compares two paths and returns `TRUE` if they are equal.

Note that this function is primarily meant as a hash table comparison function.

See also: `fm_path_compare()`.

#### Parameters

p1 | first path |
p2 | second path |

#### Returns

`TRUE` if paths are equal.

Since: 0.1.0

### fm_path_compare ()

    int
    fm_path_compare (FmPath *p1,
                     FmPath *p2);

### fm_path_equal_str ()

    gboolean
    fm_path_equal_str (FmPath *path,
                       const gchar *str,
                       int n);

Compares path string representation with `string` .

#### Parameters

path | a path |
str | a string |
n | length of `string` |

#### Returns

`TRUE` if path and string are equal.

Since: 0.1.0

### fm_path_depth ()

    int
    fm_path_depth (FmPath *path);

Calculates how many elements are in this path.

#### Parameters

path | a path |

#### Returns

`TRUE` if paths are equal.

Since: 1.0.0

### fm_path_list_new ()

    FmPathList *
    fm_path_list_new (void);

### fm_path_list_new_from_uri_list ()

    FmPathList *
    fm_path_list_new_from_uri_list (const char *uri_list);

Creates a FmPathList from `uri_list` .

#### Parameters

uri_list | list of URIs separated by newline characters |

#### Returns

new FmPathList.

[transfer full]

Since: 0.1.0

### fm_path_list_new_from_uris ()

    FmPathList *
    fm_path_list_new_from_uris (char * const*uris);

Creates a FmPathList from `uris` .

#### Parameters

uris | NULL-terminated list of URIs |

#### Returns

new FmPathList.

[transfer full]

Since: 0.1.0

### fm_path_list_new_from_file_info_list ()

    FmPathList *
    fm_path_list_new_from_file_info_list (FmFileInfoList *fis);

Creates a FmPathList from `fis` .

#### Parameters

fis | a file info list |

#### Returns

new FmPathList.

[transfer full]

Since: 0.1.0

### fm_path_list_new_from_file_info_glist ()

    FmPathList *
    fm_path_list_new_from_file_info_glist (GList *fis);

Creates a FmPathList from `fis` .

#### Parameters

fis | list of file infos. | [element-type FmFileInfo]

#### Returns

new FmPathList.

[transfer full]

Since: 0.1.0

### fm_path_list_new_from_file_info_gslist ()

    FmPathList *
    fm_path_list_new_from_file_info_gslist
                                   (GSList *fis);

Creates a FmPathList from `fis` .

#### Parameters

fis | list of file infos. | [element-type FmFileInfo]

#### Returns

new FmPathList.

[transfer full]

Since: 0.1.0

### fm_path_list_to_uri_list ()

    char *
    fm_path_list_to_uri_list (FmPathList *pl);

Creates newline-separated list from `pl` . Returned data should be freed with `g_free()` after usage.

#### Parameters

pl | a path list |

#### Returns

string representation of `pl` .

[transfer full]

Since: 0.1.0

### fm_path_list_write_uri_list ()

    void
    fm_path_list_write_uri_list (FmPathList *pl,
                                 GString *buf);

Creates newline-separated list of URIs from `pl` .

#### Parameters

pl | a path list |
buf | a storage for resulting list. | [out]

Since: 0.1.0

## Types and Values

### enum FmPathFlags

Flags of FmPath object.

FM_PATH_IS_VIRTUAL and FM_PATH_IS_XDG_MENU are deprecated since 1.0.2 and FM_PATH_IS_LOCAL is deprecated since 1.2.0, and should not be used in newly written code.

#### Members

FM_PATH_NONE | - |
FM_PATH_IS_NATIVE | This is a native path to UNIX, like /home |
FM_PATH_IS_LOCAL | This path refers to a file on local filesystem |
FM_PATH_IS_VIRTUAL | This path is virtual and it doesn't exist on real filesystem |
FM_PATH_IS_TRASH | This path is under trash:/// |
FM_PATH_IS_XDG_MENU | This path is under menu:/// |

### FmFileInfoList

    typedef struct _FmFileInfoList FmFileInfoList;

### FmPath

    typedef struct _FmPath FmPath;

### FmPathList

    typedef struct _FmPathList FmPathList;