GnuCash  4.12-68-g5dc52459a1+
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 1128 of file gnc-filepath-utils.cpp.

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

◆ 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 1160 of file gnc-filepath-utils.cpp.

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

◆ 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 1194 of file gnc-filepath-utils.cpp.

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

◆ 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 1212 of file gnc-filepath-utils.cpp.

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

◆ 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 1176 of file gnc-filepath-utils.cpp.

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

◆ 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 1230 of file gnc-filepath-utils.cpp.

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

◆ 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 1144 of file gnc-filepath-utils.cpp.

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

◆ 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 1094 of file gnc-filepath-utils.cpp.

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

◆ 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 1079 of file gnc-filepath-utils.cpp.

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

◆ 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 1040 of file gnc-filepath-utils.cpp.

1041 {
1042  bfs::path path_relative (relative);
1043  path_relative.imbue (bfs_locale);
1044  bfs::path path_absolute;
1045  bfs::path path_head;
1046 
1047  if (prefix == nullptr)
1048  {
1049  const gchar *doc_dir = g_get_user_special_dir (G_USER_DIRECTORY_DOCUMENTS);
1050  if (doc_dir == nullptr)
1051  path_head = bfs::path (gnc_userdata_dir ()); // running as root maybe
1052  else
1053  path_head = bfs::path (doc_dir);
1054 
1055  path_head.imbue (bfs_locale);
1056  path_absolute = absolute (path_relative, path_head);
1057  }
1058  else
1059  {
1060  bfs::path path_head (prefix);
1061  path_head.imbue (bfs_locale);
1062  path_absolute = absolute (path_relative, path_head);
1063  }
1064  path_absolute.imbue (bfs_locale);
1065 
1066  return g_strdup (path_absolute.string().c_str());
1067 }
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 211 of file gnc-filepath-utils.cpp.

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

◆ 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 912 of file gnc-filepath-utils.cpp.

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

◆ 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 1263 of file gnc-filepath-utils.cpp.

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

◆ 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 1302 of file gnc-filepath-utils.cpp.

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

◆ 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 1272 of file gnc-filepath-utils.cpp.

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

◆ 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 1287 of file gnc-filepath-utils.cpp.

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

◆ 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 1311 of file gnc-filepath-utils.cpp.

1312 {
1313  if (gnc_userdata_home.empty())
1314  gnc_filepath_init ();
1315 
1316  std::vector<EnvPaths> paths
1317  { { "GNC_USERDATA_DIR", gnc_userdata_home_str.c_str(), true},
1318  { "GNC_USERCONFIG_DIR", gnc_userconfig_home_str.c_str(), true },
1319  { "GNC_BIN", g_getenv ("GNC_BIN"), false },
1320  { "GNC_LIB", g_getenv ("GNC_LIB"), false },
1321  { "GNC_CONF", g_getenv ("GNC_CONF"), false },
1322  { "GNC_DATA", g_getenv ("GNC_DATA"), false },
1323  };
1324  auto accum = [](const auto& a, const auto& b)
1325  {
1326  EnvPaths *ep = g_new0 (EnvPaths, 1);
1327  *ep = b;
1328  return g_list_prepend (a, ep);
1329  };
1330  return std::accumulate (paths.rbegin(), paths.rend(), (GList*) nullptr, accum);
1331 }
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 303 of file gnc-filepath-utils.cpp.

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

◆ 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 157 of file gnc-filepath-utils.cpp.

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

1003 {
1004  if (gnc_userdata_home.empty())
1006 
1007  return gnc_userconfig_home_str.c_str();
1008 }
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 981 of file gnc-filepath-utils.cpp.

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