GnuCash  4.901
Data Structures | Functions
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
filenameThe 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.

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

◆ 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
filenameThe 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.

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

◆ gnc_build_report_path()

gchar* gnc_build_report_path ( const gchar *  filename)

Make a path to filename in the report directory.

Parameters
filenameThe 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.

1193 {
1194  gchar *rptdir = gnc_path_get_reportdir ();
1195  gchar *result = g_build_filename (rptdir, filename, (gchar *)NULL);
1196  g_free (rptdir);
1197  return result;
1198 }

◆ gnc_build_reports_path()

gchar* gnc_build_reports_path ( const gchar *  dirname)

Make a path to dirname in the reports directory.

Parameters
dirnameThe 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.

1211 {
1212  gchar *rptsdir = gnc_path_get_reportsdir ();
1213  gchar *result = g_build_filename (rptsdir, dirname, (gchar *)NULL);
1214  g_free (rptsdir);
1215  return result;
1216 }

◆ gnc_build_scm_path()

gchar* gnc_build_scm_path ( const gchar *  filename)

Make a path to filename in the scm directory.

Parameters
filenameThe 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.

1175 {
1176  gchar *scmdir = gnc_path_get_scmdir ();
1177  gchar *result = g_build_filename (scmdir, filename, (gchar *)NULL);
1178  g_free (scmdir);
1179  return result;
1180 }

◆ gnc_build_stdreports_path()

gchar* gnc_build_stdreports_path ( const gchar *  filename)

Make a path to filename in the standard reports directory.

Parameters
filenameThe 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.

1229 {
1230  gchar *stdrptdir = gnc_path_get_stdreportsdir ();
1231  gchar *result = g_build_filename (stdrptdir, filename, (gchar *)NULL);
1232  g_free (stdrptdir);
1233  return result;
1234 }

◆ 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
filenameThe 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.

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

◆ gnc_build_userconfig_path()

gchar* gnc_build_userconfig_path ( const gchar *  filename)

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

Parameters
filenameThe 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.

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

◆ 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
filenameThe 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.

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

◆ 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
prefixThe prefix that is the head of the path
relativeThe 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.

1039 {
1040  bfs::path path_relative (relative);
1041  path_relative.imbue (bfs_locale);
1042  bfs::path path_absolute;
1043  bfs::path path_head;
1044 
1045  if (prefix == nullptr)
1046  {
1047  const gchar *doc_dir = g_get_user_special_dir (G_USER_DIRECTORY_DOCUMENTS);
1048  if (doc_dir == nullptr)
1049  path_head = bfs::path (gnc_userdata_dir ()); // running as root maybe
1050  else
1051  path_head = bfs::path (doc_dir);
1052 
1053  path_head.imbue (bfs_locale);
1054  path_absolute = absolute (path_relative, path_head);
1055  }
1056  else
1057  {
1058  bfs::path path_head (prefix);
1059  path_head.imbue (bfs_locale);
1060  path_absolute = absolute (path_relative, path_head);
1061  }
1062  path_absolute.imbue (bfs_locale);
1063 
1064  return g_strdup (path_absolute.string().c_str());
1065 }
const gchar * gnc_userdata_dir(void)
Ensure that the user's configuration directory exists and is minimally populated. ...

◆ 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
prefixThe prefix that might be the first part of the path
pathThe 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.

210 {
211  std::string p{path};
212  if (p.find(prefix) == 0)
213  return g_strdup(p.substr(strlen(prefix)).c_str());
214  return g_strdup(path);
215 }

◆ 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.

911 {
912  gnc_userconfig_home = get_userconfig_home() / path_package;
913  gnc_userconfig_home_str = gnc_userconfig_home.string();
914 
915  gnc_file_path_init_config_home ();
916  auto gnc_userdata_home_exists = gnc_file_path_init_data_home ();
917 
918  /* Run migration code before creating the default directories
919  If migrating, these default directories are copied instead of created. */
920  auto migration_notice = std::string ();
921  if (!gnc_userdata_home_exists)
922  migration_notice = migrate_gnc_datahome();
923 
924  /* Try to create the standard subdirectories for gnucash' user data */
925  try
926  {
927  gnc_validate_directory (gnc_userdata_home / "books");
928  gnc_validate_directory (gnc_userdata_home / "checks");
929  gnc_validate_directory (gnc_userdata_home / "translog");
930  }
931  catch (const bfs::filesystem_error& ex)
932  {
933  g_warning ("Default user data subdirectories don't exist, yet could not be created. Proceed with caution.\n"
934  "(Error: %s)", ex.what());
935  }
936 
937  return migration_notice.empty() ? NULL : g_strdup (migration_notice.c_str());
938 }

◆ 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
nameThe 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.

1262 {
1263  gchar *pkgdatadir = gnc_path_get_pkgdatadir ();
1264  gchar *result = gnc_filepath_locate_file (pkgdatadir, name);
1265  g_free (pkgdatadir);
1266  return result;
1267 }

◆ 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
nameThe 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.

1301 {
1302  gchar *docdir = gnc_path_get_pkgdocdir ();
1303  gchar *result = gnc_filepath_locate_file (docdir, name);
1304  g_free (docdir);
1305  return result;
1306 }

◆ 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
nameThe 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.

1271 {
1272  gchar *default_path;
1273  gchar *fullname;
1274  gchar* pkgdatadir = gnc_path_get_pkgdatadir ();
1275 
1276  default_path = g_build_filename (pkgdatadir, "pixmaps", nullptr);
1277  g_free(pkgdatadir);
1278  fullname = gnc_filepath_locate_file (default_path, name);
1279  g_free(default_path);
1280 
1281  return fullname;
1282 }

◆ 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
nameThe 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.

1286 {
1287  gchar *default_path;
1288  gchar *fullname;
1289  gchar* pkgdatadir = gnc_path_get_pkgdatadir ();
1290 
1291  default_path = g_build_filename (pkgdatadir, "ui", nullptr);
1292  g_free(pkgdatadir);
1293  fullname = gnc_filepath_locate_file (default_path, name);
1294  g_free(default_path);
1295 
1296  return fullname;
1297 }

◆ 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.

1310 {
1311  if (gnc_userdata_home.empty())
1312  gnc_filepath_init ();
1313 
1314  std::vector<EnvPaths> paths
1315  { { "GNC_USERDATA_DIR", gnc_userdata_home_str.c_str(), true},
1316  { "GNC_USERCONFIG_DIR", gnc_userconfig_home_str.c_str(), true },
1317  { "GNC_BIN", g_getenv ("GNC_BIN"), false },
1318  { "GNC_LIB", g_getenv ("GNC_LIB"), false },
1319  { "GNC_CONF", g_getenv ("GNC_CONF"), false },
1320  { "GNC_DATA", g_getenv ("GNC_DATA"), false },
1321  };
1322  auto accum = [](const auto& a, const auto& b)
1323  {
1324  EnvPaths *ep = g_new0 (EnvPaths, 1);
1325  *ep = b;
1326  return g_list_prepend (a, ep);
1327  };
1328  return std::accumulate (paths.rbegin(), paths.rend(), (GList*) nullptr, accum);
1329 }
char * gnc_filepath_init(void)
Initializes the gnucash user data directory.

◆ 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_nameThe 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_nameThe 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.

302 {
303  gchar *loc_file_name = NULL;
304  gchar *full_path = NULL;
305  const gchar * const *lang;
306 
307  if (!file_name || *file_name == '\0')
308  return NULL;
309 
310  /* An absolute path is returned unmodified. */
311  if (g_path_is_absolute (file_name))
312  return g_strdup (file_name);
313 
314  /* First try to find the file in any of the localized directories
315  * the user has set up on his system
316  */
317  for (lang = g_get_language_names (); *lang; lang++)
318  {
319  loc_file_name = g_build_filename (*lang, file_name, (gchar *)NULL);
320  full_path = gnc_path_find_localized_html_file_internal (loc_file_name);
321  g_free (loc_file_name);
322  if (full_path != NULL)
323  return full_path;
324  }
325 
326  /* If not found in a localized directory, try to find the file
327  * in any of the base directories
328  */
329  return gnc_path_find_localized_html_file_internal (file_name);
330 
331 }

◆ 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
filefragThe file path to resolve
Returns
An absolute file path.

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

156 {
157  gchar *fullpath = NULL, *tmp_path = NULL;
158 
159  /* seriously invalid */
160  if (!filefrag)
161  {
162  g_critical("filefrag is NULL");
163  return NULL;
164  }
165 
166  /* ---------------------------------------------------- */
167  /* OK, now we try to find or build an absolute file path */
168 
169  /* check for an absolute file path */
170  if (g_path_is_absolute(filefrag))
171  return g_strdup (filefrag);
172 
173  /* Look in the current working directory */
174  tmp_path = g_get_current_dir();
175  fullpath = g_build_filename(tmp_path, filefrag, (gchar *)NULL);
176  g_free(tmp_path);
177  fullpath = check_path_return_if_valid(fullpath);
178  if (fullpath != NULL)
179  return fullpath;
180 
181  /* Look in the data dir (e.g. $PREFIX/share/gnucash) */
182  tmp_path = gnc_path_get_pkgdatadir();
183  fullpath = g_build_filename(tmp_path, filefrag, (gchar *)NULL);
184  g_free(tmp_path);
185  fullpath = check_path_return_if_valid(fullpath);
186  if (fullpath != NULL)
187  return fullpath;
188 
189  /* Look in the config dir (e.g. $PREFIX/share/gnucash/accounts) */
190  tmp_path = gnc_path_get_accountsdir();
191  fullpath = g_build_filename(tmp_path, filefrag, (gchar *)NULL);
192  g_free(tmp_path);
193  fullpath = check_path_return_if_valid(fullpath);
194  if (fullpath != NULL)
195  return fullpath;
196 
197  /* Look in the users config dir (e.g. $HOME/.gnucash/data) */
198  fullpath = g_strdup(gnc_build_data_path(filefrag));
199  if (g_file_test(fullpath, G_FILE_TEST_IS_REGULAR))
200  return fullpath;
201 
202  /* OK, it's not there. Note that it needs to be created and pass it
203  * back anyway */
204  g_warning("create new file %s", fullpath);
205  return fullpath;
206 
207 }
gchar * gnc_build_data_path(const gchar *filename)
Make a path to filename in the data subdirectory of the user&#39;s configuration directory.

◆ 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.

1001 {
1002  if (gnc_userdata_home.empty())
1004 
1005  return gnc_userconfig_home_str.c_str();
1006 }
char * gnc_filepath_init(void)
Initializes the gnucash user data directory.

◆ 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.

980 {
981  if (gnc_userdata_home.empty())
983  return g_strdup(gnc_userdata_home_str.c_str());
984 }
char * gnc_filepath_init(void)
Initializes the gnucash user data directory.