gnc-filepath-utils.h File Reference

File path resolution utility functions. More...

Go to the source code of this file.

Data Structures
struct	EnvPaths

Functions
gchar *	gnc_resolve_file_path (const gchar *filefrag)
	The gnc_resolve_file_path() routine is a utility that will accept a fragmentary filename as input, and resolve it into a fully qualified path in the file system, i.e. More...
gchar *	gnc_file_path_relative_part (const gchar *prefix, const gchar *path)
	Given a prefix and a path return the relative portion of the path. More...
gchar *	gnc_file_path_absolute (const gchar *prefix, const gchar *relative)
	Given a prefix and a relative path, return the absolute path. More...
gchar *	gnc_path_find_localized_html_file (const gchar *file_name)
	Find an absolute path to a localized version of a given relative path to a html or html related file. More...
char *	gnc_filepath_init (void)
	Initializes the gnucash user data directory. More...
const gchar *	gnc_userdata_dir (void)
	Ensure that the user's configuration directory exists and is minimally populated. More...
gchar *	gnc_build_userdata_path (const gchar *filename)
	Make a path to filename in the user's gnucash data directory. More...
gchar *	gnc_build_userconfig_path (const gchar *filename)
	Make a path to filename in the user's configuration directory. More...
gchar *	gnc_build_book_path (const gchar *filename)
	Make a path to filename in the book subdirectory of the user's configuration directory. More...
gchar *	gnc_build_translog_path (const gchar *filename)
	Make a path to filename in the translog subdirectory of the user's configuration directory. More...
gchar *	gnc_build_data_path (const gchar *filename)
	Make a path to filename in the data subdirectory of the user's configuration directory. More...
gchar *	gnc_build_scm_path (const gchar *filename)
	Make a path to filename in the scm directory. More...
gchar *	gnc_build_report_path (const gchar *filename)
	Make a path to filename in the report directory. More...
gchar *	gnc_build_reports_path (const gchar *dirname)
	Make a path to dirname in the reports directory. More...
gchar *	gnc_build_stdreports_path (const gchar *filename)
	Make a path to filename in the standard reports directory. More...
const gchar *	gnc_userconfig_dir (void)
	Return the user's config directory for gnucash. More...
gchar *	gnc_filepath_locate_pixmap (const gchar *name)
	Given a pixmap/pixbuf file name, find the file in the pixmap directory associated with this application. More...
gchar *	gnc_filepath_locate_data_file (const gchar *name)
	Given a file name, find the file in the directories associated with this application. More...
gchar *	gnc_filepath_locate_ui_file (const gchar *name)
	Given a ui file name, find the file in the ui directory associated with this application. More...
gchar *	gnc_filepath_locate_doc_file (const gchar *name)
	Given a documentation file name, find the file in the doc directory associated with this application. More...
GList *	gnc_list_all_paths (void)
	Returns a GList* of the environment variables used by GnuCash. More...

Detailed Description

File path resolution utility functions.

Author

Copyright (c) 1998-2004 Linas Vepstas linas.nosp@m.@lin.nosp@m.as.or.nosp@m.g

Copyright (c) 2000 Dave Peticolas

Definition in file gnc-filepath-utils.h.

Function Documentation

gnc_build_book_path()

gchar* gnc_build_book_path

(

const gchar *

filename

)

Make a path to filename in the book subdirectory of the user's configuration directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1126 of file gnc-filepath-utils.cpp.

{
    auto path = gnc_build_userdata_subdir_path("books", filename).string();
    return g_strdup(path.c_str());
}

gnc_build_data_path()

gchar* gnc_build_data_path

(

const gchar *

filename

)

Make a path to filename in the data subdirectory of the user's configuration directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1158 of file gnc-filepath-utils.cpp.

{
    auto path = gnc_build_userdata_subdir_path("data", filename).string();
    return g_strdup(path.c_str());
}

gnc_build_report_path()

gchar* gnc_build_report_path

(

const gchar *

filename

)

Make a path to filename in the report directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1192 of file gnc-filepath-utils.cpp.

{
    gchar *rptdir = gnc_path_get_reportdir ();
    gchar *result = g_build_filename (rptdir, filename, (gchar *)NULL);
    g_free (rptdir);
    return result;
}

gnc_build_reports_path()

gchar* gnc_build_reports_path

(

const gchar *

dirname

)

Make a path to dirname in the reports directory.

Parameters

dirname

The name of the subdirectory

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1210 of file gnc-filepath-utils.cpp.

{
    gchar *rptsdir = gnc_path_get_reportsdir ();
    gchar *result = g_build_filename (rptsdir, dirname, (gchar *)NULL);
    g_free (rptsdir);
    return result;
}

gnc_build_scm_path()

gchar* gnc_build_scm_path

(

const gchar *

filename

)

Make a path to filename in the scm directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1174 of file gnc-filepath-utils.cpp.

{
    gchar *scmdir = gnc_path_get_scmdir ();
    gchar *result = g_build_filename (scmdir, filename, (gchar *)NULL);
    g_free (scmdir);
    return result;
}

gnc_build_stdreports_path()

gchar* gnc_build_stdreports_path

(

const gchar *

filename

)

Make a path to filename in the standard reports directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1228 of file gnc-filepath-utils.cpp.

{
    gchar *stdrptdir = gnc_path_get_stdreportsdir ();
    gchar *result = g_build_filename (stdrptdir, filename, (gchar *)NULL);
    g_free (stdrptdir);
    return result;
}

gnc_build_translog_path()

gchar* gnc_build_translog_path

(

const gchar *

filename

)

Make a path to filename in the translog subdirectory of the user's configuration directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1142 of file gnc-filepath-utils.cpp.

{
    auto path = gnc_build_userdata_subdir_path("translog", filename).string();
    return g_strdup(path.c_str());
}

gnc_build_userconfig_path()

gchar* gnc_build_userconfig_path

(

const gchar *

filename

)

Make a path to filename in the user's configuration directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1092 of file gnc-filepath-utils.cpp.

{
    return g_strdup((gnc_userconfig_dir_as_path() / filename).string().c_str());
}

gnc_build_userdata_path()

gchar* gnc_build_userdata_path

(

const gchar *

filename

)

Make a path to filename in the user's gnucash data directory.

Parameters

filename

The name of the file

Returns

An absolute path. The returned string should be freed by the user using g_free().

Definition at line 1077 of file gnc-filepath-utils.cpp.

{
    return g_strdup((gnc_userdata_dir_as_path() / filename).string().c_str());
}

gnc_file_path_absolute()

gchar* gnc_file_path_absolute	(	const gchar *	prefix,
		const gchar *	relative
	)

Given a prefix and a relative path, return the absolute path.

Parameters

prefix	The prefix that is the head of the path
relative	The path to add to the prefix to form an absolute path

Returns

a char* that must be g_freed containing the absolute path.

If prefix is null, then the gnc_userdata_home is used as the prefix.

Definition at line 1038 of file gnc-filepath-utils.cpp.

{
    bfs::path path_relative (relative);
    path_relative.imbue (bfs_locale);
    bfs::path path_absolute;
    bfs::path path_head;

    if (prefix == nullptr)
    {
        const gchar *doc_dir = g_get_user_special_dir (G_USER_DIRECTORY_DOCUMENTS);
        if (doc_dir == nullptr)
            path_head = bfs::path (gnc_userdata_dir ()); // running as root maybe
        else
            path_head = bfs::path (doc_dir);

        path_head.imbue (bfs_locale);
        path_absolute = absolute (path_relative, path_head);
    }
    else
    {
        bfs::path path_head (prefix);
        path_head.imbue (bfs_locale);
        path_absolute = absolute (path_relative, path_head);
    }
    path_absolute.imbue (bfs_locale);

    return g_strdup (path_absolute.string().c_str());
}

gnc_file_path_relative_part()

gchar* gnc_file_path_relative_part	(	const gchar *	prefix,
		const gchar *	path
	)

Given a prefix and a path return the relative portion of the path.

Parameters

prefix	The prefix that might be the first part of the path
path	The path from which the prefix might be removed

Returns

a char* that must be g_freed containing the path without the prefix if path begins with prefix, otherwise a copy of path.

Definition at line 209 of file gnc-filepath-utils.cpp.

{
    std::string p{path};
    if (p.find(prefix) == 0)
        return g_strdup(p.substr(strlen(prefix)).c_str());
    return g_strdup(path);
}

gnc_filepath_init()

char* gnc_filepath_init

(

void

)

Initializes the gnucash user data directory.

This function should be called very early at startup (before any other of the user data directory related function gets called).

Note

If the necessary directories did get created this function will also try to copy files from $HOME/.gnucash to there if that old location exists.

Returns

a migration message when files got copied from the old location, NULL otherwise

Definition at line 910 of file gnc-filepath-utils.cpp.

{
    gnc_userconfig_home = get_userconfig_home() / path_package;
    gnc_userconfig_home_str = gnc_userconfig_home.string();

    gnc_file_path_init_config_home ();
    auto gnc_userdata_home_exists = gnc_file_path_init_data_home ();

    /* Run migration code before creating the default directories
       If migrating, these default directories are copied instead of created. */
    auto migration_notice = std::string ();
    if (!gnc_userdata_home_exists)
        migration_notice = migrate_gnc_datahome();

    /* Try to create the standard subdirectories for gnucash' user data */
    try
    {
        gnc_validate_directory (gnc_userdata_home / "books");
        gnc_validate_directory (gnc_userdata_home / "checks");
        gnc_validate_directory (gnc_userdata_home / "translog");
    }
    catch (const bfs::filesystem_error& ex)
    {
        g_warning ("Default user data subdirectories don't exist, yet could not be created. Proceed with caution.\n"
        "(Error: %s)", ex.what());
    }

    return migration_notice.empty() ? NULL : g_strdup (migration_notice.c_str());
}

gnc_filepath_locate_data_file()

gchar* gnc_filepath_locate_data_file

(

const gchar *

name

)

Given a file name, find the file in the directories associated with this application.

This routine will display an error message if it can't find the file.

Parameters

name	The name of the file to be found.

Returns

the full path name of the file, or NULL of the file can't be found.

Note

It is the caller's responsibility to free the returned string.

Definition at line 1261 of file gnc-filepath-utils.cpp.

{
    gchar *pkgdatadir = gnc_path_get_pkgdatadir ();
    gchar *result = gnc_filepath_locate_file (pkgdatadir, name);
    g_free (pkgdatadir);
    return result;
}

gnc_filepath_locate_doc_file()

gchar* gnc_filepath_locate_doc_file

(

const gchar *

name

)

Given a documentation file name, find the file in the doc directory associated with this application.

This routine will display an error message if it can't find the file.

Parameters

name	The name of the file to be found.

Returns

the full path name of the file, or NULL of the file can't be found.

Note

It is the caller's responsibility to free the returned string.

Definition at line 1300 of file gnc-filepath-utils.cpp.

{
    gchar *docdir = gnc_path_get_pkgdocdir ();
    gchar *result = gnc_filepath_locate_file (docdir, name);
    g_free (docdir);
    return result;
}

gnc_filepath_locate_pixmap()

gchar* gnc_filepath_locate_pixmap

(

const gchar *

name

)

Given a pixmap/pixbuf file name, find the file in the pixmap directory associated with this application.

This routine will display an error message if it can't find the file.

Parameters

name	The name of the file to be found.

Returns

the full path name of the file, or NULL of the file can't be found.

Note

It is the caller's responsibility to free the returned string.

Definition at line 1270 of file gnc-filepath-utils.cpp.

{
    gchar *default_path;
    gchar *fullname;
    gchar* pkgdatadir = gnc_path_get_pkgdatadir ();

    default_path = g_build_filename (pkgdatadir, "pixmaps", nullptr);
    g_free(pkgdatadir);
    fullname = gnc_filepath_locate_file (default_path, name);
    g_free(default_path);

    return fullname;
}

gnc_filepath_locate_ui_file()

gchar* gnc_filepath_locate_ui_file

(

const gchar *

name

)

Given a ui file name, find the file in the ui directory associated with this application.

This routine will display an error message if it can't find the file.

Parameters

name	The name of the file to be found.

Returns

the full path name of the file, or NULL of the file can't be found.

Note

It is the caller's responsibility to free the returned string.

Definition at line 1285 of file gnc-filepath-utils.cpp.

{
    gchar *default_path;
    gchar *fullname;
    gchar* pkgdatadir = gnc_path_get_pkgdatadir ();

    default_path = g_build_filename (pkgdatadir, "ui", nullptr);
    g_free(pkgdatadir);
    fullname = gnc_filepath_locate_file (default_path, name);
    g_free(default_path);

    return fullname;
}

gnc_list_all_paths()

GList* gnc_list_all_paths

(

void

)

Returns a GList* of the environment variables used by GnuCash.

Returns

a GList* of EnvPaths structs, describing the environment variables used by GnuCash.

Note

It is the caller's responsibility to free the GList with g_list_free_full (paths, g_free)

Definition at line 1309 of file gnc-filepath-utils.cpp.

{
    if (gnc_userdata_home.empty())
        gnc_filepath_init ();

    std::vector<EnvPaths> paths
        { { "GNC_USERDATA_DIR", gnc_userdata_home_str.c_str(), true},
          { "GNC_USERCONFIG_DIR", gnc_userconfig_home_str.c_str(), true },
          { "GNC_BIN", g_getenv ("GNC_BIN"), false },
          { "GNC_LIB", g_getenv ("GNC_LIB"), false },
          { "GNC_CONF", g_getenv ("GNC_CONF"), false },
          { "GNC_DATA", g_getenv ("GNC_DATA"), false },
        };
    auto accum = [](const auto& a, const auto& b)
    {
        EnvPaths *ep = g_new0 (EnvPaths, 1);
        *ep = b;
        return g_list_prepend (a, ep);
    };
    return std::accumulate (paths.rbegin(), paths.rend(), (GList*) nullptr, accum);
}

gnc_path_find_localized_html_file()

gchar* gnc_path_find_localized_html_file

(

const gchar *

file_name

)

Find an absolute path to a localized version of a given relative path to a html or html related file.

If no localized version exists, an absolute path to the file is searched for. If that file doesn't exist either, returns NULL.

Warning

file_name should be a simple path fragment. It shouldn't contain xml:// or http:// or <whatever>:// other protocol specifiers.

If passed a string which g_path_is_absolute declares an absolute path, return the argument.

Otherwise, assume that file_name is a well-formed relative path and try to find a file with its path relative to

• a localized subdirectory in the html directory of the user's configuration directory (e.g. $HOME/.gnucash/html/de_DE, $HOME/.gnucash/html/en,...)
• a localized subdirectory in the gnucash documentation directory (e.g. /usr/share/doc/gnucash/C,...)
• the html directory of the user's configuration directory (e.g. $HOME/.gnucash/html)
• the gnucash documentation directory (e.g. /usr/share/doc/gnucash/)

The paths are searched for in that order. If a matching file is found, return the absolute path to it.

If one isn't found, return NULL.

Parameters

file_name

The file path to resolve

Returns

An absolute file path or NULL if no file is found.

If no localized version exists, an absolute path to the file is searched for. If that file doesn't exist either, returns NULL.

Warning

file_name should be a simple path fragment. It shouldn't contain xml:// or http:// or <whatever>:// other protocol specifiers.

If passed a string which g_path_is_absolute declares an absolute path, return the argument.

Otherwise, assume that file_name is a well-formed relative path and try to find a file with its path relative to

• a localized subdirectory in the html directory of the user's configuration directory (e.g. $HOME/.gnucash/html/de_DE, $HOME/.gnucash/html/en,...)
• a localized subdirectory in the gnucash documentation directory (e.g. /usr/share/doc/gnucash/C,...)
• the html directory of the user's configuration directory (e.g. $HOME/.gnucash/html)
• the gnucash documentation directory (e.g. /usr/share/doc/gnucash/)
• last resort option: the gnucash data directory (e.g. /usr/share/gnucash/)

The paths are searched for in that order. If a matching file is found, return the absolute path to it.

If one isn't found, return NULL.

Parameters

file_name

The file path to resolve

Returns

An absolute file path or NULL if no file is found.

Definition at line 301 of file gnc-filepath-utils.cpp.

{
    gchar *loc_file_name = NULL;
    gchar *full_path = NULL;
    const gchar * const *lang;

    if (!file_name || *file_name == '\0')
        return NULL;

    /* An absolute path is returned unmodified. */
    if (g_path_is_absolute (file_name))
        return g_strdup (file_name);

    /* First try to find the file in any of the localized directories
     * the user has set up on his system
     */
    for (lang = g_get_language_names (); *lang; lang++)
    {
        loc_file_name = g_build_filename (*lang, file_name, (gchar *)NULL);
        full_path = gnc_path_find_localized_html_file_internal (loc_file_name);
        g_free (loc_file_name);
        if (full_path != NULL)
            return full_path;
    }

    /* If not found in a localized directory, try to find the file
     * in any of the base directories
     */
    return gnc_path_find_localized_html_file_internal (file_name);

}

gnc_resolve_file_path()

gchar* gnc_resolve_file_path

(

const gchar *

filefrag

)

The gnc_resolve_file_path() routine is a utility that will accept a fragmentary filename as input, and resolve it into a fully qualified path in the file system, i.e.

a path that begins with a leading slash. First, the current working directory is searched for the file. Next, the directory $HOME/.gnucash/data, and finally, a list of other (configurable) paths. If the file is not found, then the path $HOME/.gnucash/data is used. If $HOME is not defined, then the current working directory is used.

The gnc_resolve_file_path() routine is a utility that will accept a fragmentary filename as input, and resolve it into a fully qualified path in the file system, i.e.

Warning

filefrag should be a simple path fragment. It shouldn't contain xml:// or http:// or <whatever>:// other protocol specifiers.

If passed a string which g_path_is_absolute declares an absolute path, return the argument.

Otherwise, assume that filefrag is a well-formed relative path and try to find a file with its path relative to

• the current working directory,
• the installed system-wide data directory (e.g., /usr/local/share/gnucash),
• the installed system configuration directory (e.g., /usr/local/etc/gnucash),
• or in the user's configuration directory (e.g., $HOME/.gnucash/data)

The paths are searched for in that order. If a matching file is found, return the absolute path to it.

If one isn't found, return a absolute path relative to the user's configuration directory and note in the trace file that it needs to be created.

Parameters

filefrag

The file path to resolve

Returns

An absolute file path.

Definition at line 155 of file gnc-filepath-utils.cpp.

{
    gchar *fullpath = NULL, *tmp_path = NULL;

    /* seriously invalid */
    if (!filefrag)
    {
        g_critical("filefrag is NULL");
        return NULL;
    }

    /* ---------------------------------------------------- */
    /* OK, now we try to find or build an absolute file path */

    /* check for an absolute file path */
    if (g_path_is_absolute(filefrag))
        return g_strdup (filefrag);

    /* Look in the current working directory */
    tmp_path = g_get_current_dir();
    fullpath = g_build_filename(tmp_path, filefrag, (gchar *)NULL);
    g_free(tmp_path);
    fullpath = check_path_return_if_valid(fullpath);
    if (fullpath != NULL)
        return fullpath;

    /* Look in the data dir (e.g. $PREFIX/share/gnucash) */
    tmp_path = gnc_path_get_pkgdatadir();
    fullpath = g_build_filename(tmp_path, filefrag, (gchar *)NULL);
    g_free(tmp_path);
    fullpath = check_path_return_if_valid(fullpath);
    if (fullpath != NULL)
        return fullpath;

    /* Look in the config dir (e.g. $PREFIX/share/gnucash/accounts) */
    tmp_path = gnc_path_get_accountsdir();
    fullpath = g_build_filename(tmp_path, filefrag, (gchar *)NULL);
    g_free(tmp_path);
    fullpath = check_path_return_if_valid(fullpath);
    if (fullpath != NULL)
        return fullpath;

    /* Look in the users config dir (e.g. $HOME/.gnucash/data) */
    fullpath = g_strdup(gnc_build_data_path(filefrag));
    if (g_file_test(fullpath, G_FILE_TEST_IS_REGULAR))
        return fullpath;

    /* OK, it's not there. Note that it needs to be created and pass it
     * back anyway */
    g_warning("create new file %s", fullpath);
    return fullpath;

}

gnc_userconfig_dir()

const gchar* gnc_userconfig_dir

(

void

)

Return the user's config directory for gnucash.

Note

the default path depends on the platform.

• Windows: CSIDL_APPDATA/Gnucash
• OS X: $HOME/Application Support/Gnucash
• Linux: $XDG_CONFIG_HOME/gnucash (or the default $HOME/.config/gnucash)

gnucash will not create this directory if it doesn't exist

Returns

An absolute path to the configuration directory. This string is owned by the gnc_filepath_utils code and should not be freed by the user.

Definition at line 1000 of file gnc-filepath-utils.cpp.

{
    if (gnc_userdata_home.empty())
        gnc_filepath_init();

    return gnc_userconfig_home_str.c_str();
}

gnc_userdata_dir()

const gchar* gnc_userdata_dir

(

void

)

Ensure that the user's configuration directory exists and is minimally populated.

Note that the default path depends on the platform.

• Windows: CSIDL_APPDATA/Gnucash
• OS X: $HOME/Application Support/Gnucash
• Linux: $XDG_DATA_HOME/gnucash (or the default $HOME/.local/share/gnucash)

If any of these paths don't exist and can't be created the function will fall back to

• $HOME/.gnucash
• <TMP_DIR>/gnucash (in that order)

Returns

An absolute path to the configuration directory. This string is owned by the gnc_filepath_utils code and should not be freed by the user.

Definition at line 979 of file gnc-filepath-utils.cpp.

{
    if (gnc_userdata_home.empty())
        gnc_filepath_init();
    return g_strdup(gnc_userdata_home_str.c_str());
}