wsutil/filesystem.h

   1 /** @file
   2  * Filesystem utility definitions
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef FILESYSTEM_H
  12 #define FILESYSTEM_H
  13
  14 #include <wireshark.h>
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 /*
  21  * Default profile name.
  22  */
  23 #define DEFAULT_PROFILE      "Default"
  24
  25 /**
  26  * Initialize our configuration environment.
  27  *
  28  * Get the pathname of the directory from which the executable came,
  29  * and save it for future use.
  30  *
  31  * @param arg0 Executable name hint. Should be argv[0].
  32  * @return NULL on success, and a g_mallocated string containing an error on failure.
  33  */
  34 WS_DLL_PUBLIC char *configuration_init(const char *arg0);
  35
  36 /*
  37  * Get the directory in which the main (Wireshark, TShark, Stratoshark, etc)
  38  * program resides.
  39  * Extcaps should use get_extcap_dir() to get their path.
  40  *
  41  * @return The main program file directory.
  42  */
  43 WS_DLL_PUBLIC const char *get_progfile_dir(void);
  44
  45 /*
  46  * Construct the path name of a non-extcap Wireshark executable file,
  47  * given the program name.  The executable name doesn't include ".exe";
  48  * append it on Windows, so that callers don't have to worry about that.
  49  *
  50  * This presumes that all non-extcap executables are in the same directory.
  51  *
  52  * The returned file name was g_malloc()'d so it must be g_free()d when the
  53  * caller is done with it.
  54  */
  55 WS_DLL_PUBLIC char *get_executable_path(const char *filename);
  56
  57 /*
  58  * Get the directory in which plugins are stored; this must not be called
  59  * before configuration_init() is called, as they might be stored in a
  60  * subdirectory of the program file directory.
  61  */
  62 WS_DLL_PUBLIC const char *get_plugins_dir(void);
  63
  64 /*
  65  * Append VERSION_MAJOR.VERSION_MINOR to the plugin dir.
  66  */
  67 WS_DLL_PUBLIC const char *get_plugins_dir_with_version(void);
  68
  69 /*
  70  * Get the personal plugin dir.
  71  */
  72 WS_DLL_PUBLIC const char *get_plugins_pers_dir(void);
  73
  74 /*
  75  * Append VERSION_MAJOR.VERSION_MINOR to the plugin personal dir.
  76  */
  77 WS_DLL_PUBLIC const char *get_plugins_pers_dir_with_version(void);
  78
  79 /*
  80  * Get the directory in which extcap hooks are stored; this must not be called
  81  * before configuration_init() is called, as they might be stored in a
  82  * subdirectory of the program file directory.
  83  */
  84 WS_DLL_PUBLIC const char *get_extcap_dir(void);
  85
  86 /*
  87  * Get the personal extcap dir.
  88  */
  89 WS_DLL_PUBLIC const char *get_extcap_pers_dir(void);
  90
  91 /*
  92  * Get the flag indicating whether we're running from a build
  93  * directory.
  94  */
  95 WS_DLL_PUBLIC bool running_in_build_directory(void);
  96
  97 /*
  98  * Get the directory in which global configuration files are
  99  * stored.
 100  */
 101 WS_DLL_PUBLIC const char *get_datafile_dir(void);
 102
 103 /*
 104  * Construct the path name of a global configuration file, given the
 105  * file name.
 106  *
 107  * The returned file name was g_malloc()'d so it must be g_free()d when the
 108  * caller is done with it.
 109  */
 110 WS_DLL_PUBLIC char *get_datafile_path(const char *filename);
 111
 112 /*
 113  * Get the directory in which global documentation files are
 114  * stored.
 115  */
 116 WS_DLL_PUBLIC const char *get_doc_dir(void);
 117
 118 /*
 119  * Construct the path name of a global documentation file, given the
 120  * file name.
 121  *
 122  * The returned file name was g_malloc()'d so it must be g_free()d when the
 123  * caller is done with it.
 124  */
 125 WS_DLL_PUBLIC char *get_docfile_path(const char *filename);
 126
 127 /*
 128  * Construct the path URL of a global documentation file, given the
 129  * file name.
 130  *
 131  * The returned file name was g_malloc()'d so it must be g_free()d when the
 132  * caller is done with it.
 133  */
 134 WS_DLL_PUBLIC char *doc_file_url(const char *filename);
 135
 136 /*
 137  * Get the directory in which files that, at least on UNIX, are
 138  * system files (such as "/etc/ethers") are stored; on Windows,
 139  * there's no "/etc" directory, so we get them from the Wireshark
 140  * global configuration and data file directory.
 141  */
 142 WS_DLL_PUBLIC const char *get_systemfile_dir(void);
 143
 144 /*
 145  * Set the configuration profile name to be used for storing
 146  * personal configuration files.
 147  */
 148 WS_DLL_PUBLIC void set_profile_name(const char *profilename);
 149
 150 /*
 151  * Get the current configuration profile name used for storing
 152  * personal configuration files.
 153  */
 154 WS_DLL_PUBLIC const char *get_profile_name(void);
 155
 156 /*
 157  * Check if current profile is default profile.
 158  */
 159 WS_DLL_PUBLIC bool is_default_profile(void);
 160
 161 /*
 162  * Check if we have global profiles.
 163  */
 164 WS_DLL_PUBLIC bool has_global_profiles(void);
 165
 166 /*
 167  * Get the directory used to store configuration profile directories.
 168  * Caller must free the returned string
 169  */
 170 WS_DLL_PUBLIC char *get_profiles_dir(void);
 171
 172 /*
 173  * Get the directory used to store configuration files for a given profile.
 174  * Caller must free the returned string.
 175  */
 176 WS_DLL_PUBLIC char *get_profile_dir(const char *profilename, bool is_global);
 177
 178 /*
 179  * Create the directory used to store configuration profile directories.
 180  */
 181 WS_DLL_PUBLIC int create_profiles_dir(char **pf_dir_path_return);
 182
 183 /*
 184  * Get the directory used to store global configuration profile directories.
 185  * Caller must free the returned string
 186  */
 187 WS_DLL_PUBLIC char *get_global_profiles_dir(void);
 188
 189
 190 /*
 191  * Store filenames used for personal config files so we know which
 192  * files to copy when duplicate a configuration profile.
 193  */
 194 WS_DLL_PUBLIC void profile_store_persconffiles(bool store);
 195
 196 /*
 197  * Register a filename to the personal config files storage.
 198  * This is for files which are not read using get_persconffile_path() during startup.
 199  */
 200 WS_DLL_PUBLIC void profile_register_persconffile(const char *filename);
 201
 202 /*
 203  * Check if given configuration profile exists.
 204  */
 205 WS_DLL_PUBLIC bool profile_exists(const char *profilename, bool global);
 206
 207 /*
 208  * Create a directory for the given configuration profile.
 209  * If we attempted to create it, and failed, return -1 and
 210  * set "*pf_dir_path_return" to the pathname of the directory we failed
 211  * to create (it's g_mallocated, so our caller should free it); otherwise,
 212  * return 0.
 213  */
 214 WS_DLL_PUBLIC int create_persconffile_profile(const char *profilename,
 215                                        char **pf_dir_path_return);
 216
 217 /*
 218  * Returns the list of known profile config filenames
 219  */
 220 WS_DLL_PUBLIC const GHashTable * allowed_profile_filenames(void);
 221
 222 /*
 223  * Delete the directory for the given configuration profile.
 224  * If we attempted to delete it, and failed, return -1 and
 225  * set "*pf_dir_path_return" to the pathname of the directory we failed
 226  * to delete (it's g_mallocated, so our caller should free it); otherwise,
 227  * return 0.
 228  */
 229 WS_DLL_PUBLIC int delete_persconffile_profile(const char *profilename,
 230                                        char **pf_dir_path_return);
 231
 232 /*
 233  * Rename the directory for the given confinguration profile.
 234  */
 235 WS_DLL_PUBLIC int rename_persconffile_profile(const char *fromname, const char *toname,
 236                                        char **pf_from_dir_path_return,
 237                                        char **pf_to_dir_path_return);
 238
 239 /*
 240  * Copy files in one profile to the other.
 241  */
 242 WS_DLL_PUBLIC int copy_persconffile_profile(const char *toname, const char *fromname,
 243                                      bool from_global,
 244                                      char **pf_filename_return,
 245                                      char **pf_to_dir_path_return,
 246                                      char **pf_from_dir_path_return);
 247
 248 /*
 249  * Create the directory that holds personal configuration files, if
 250  * necessary.  If we attempted to create it, and failed, return -1 and
 251  * set "*pf_dir_path_return" to the pathname of the directory we failed
 252  * to create (it's g_mallocated, so our caller should free it); otherwise,
 253  * return 0.
 254  */
 255 WS_DLL_PUBLIC int create_persconffile_dir(char **pf_dir_path_return);
 256
 257 /*
 258  * Construct the path name of a personal configuration file, given the
 259  * file name.  If using configuration profiles this directory will be
 260  * used if "from_profile" is true.
 261  *
 262  * The returned file name was g_malloc()'d so it must be g_free()d when the
 263  * caller is done with it.
 264  */
 265 WS_DLL_PUBLIC char *get_persconffile_path(const char *filename, bool from_profile);
 266
 267 /*
 268  * Set the path of the personal configuration file directory.
 269  */
 270 WS_DLL_PUBLIC void set_persconffile_dir(const char *p);
 271
 272 /*
 273  * Get the (default) directory in which personal data is stored.
 274  *
 275  * On Win32, this is the "My Documents" folder in the personal profile.
 276  * On UNIX this is simply the current directory.
 277  */
 278 WS_DLL_PUBLIC const char *get_persdatafile_dir(void);
 279
 280 /*
 281  * Set the path of the directory in which personal data is stored.
 282  */
 283 WS_DLL_PUBLIC void set_persdatafile_dir(const char *p);
 284
 285 /*
 286  * Get the current working directory.
 287  */
 288 WS_DLL_PUBLIC WS_RETNONNULL const char *get_current_working_dir(void);
 289
 290 /*
 291  * Return an error message for UNIX-style errno indications on open or
 292  * create operations.
 293  */
 294 WS_DLL_PUBLIC const char *file_open_error_message(int err, bool for_writing);
 295
 296 /*
 297  * Return an error message for UNIX-style errno indications on write
 298  * operations.
 299  */
 300 WS_DLL_PUBLIC const char *file_write_error_message(int err);
 301
 302 /*
 303  * Given a pathname, return the last component.
 304  */
 305 WS_DLL_PUBLIC const char *get_basename(const char *);
 306
 307  /*
 308   * Given a pathname, return a pointer to the last pathname separator
 309   * character in the pathname, or NULL if the pathname contains no
 310   * separators.
 311   */
 312 WS_DLL_PUBLIC char *find_last_pathname_separator(const char *path);
 313
 314 /*
 315  * Given a pathname, return a string containing everything but the
 316  * last component.  NOTE: this overwrites the pathname handed into
 317  * it....
 318  */
 319 WS_DLL_PUBLIC char *get_dirname(char *);
 320
 321 /*
 322  * Given a pathname, return:
 323  *
 324  *      the errno, if an attempt to "stat()" the file fails;
 325  *
 326  *      EISDIR, if the attempt succeeded and the file turned out
 327  *      to be a directory;
 328  *
 329  *      0, if the attempt succeeded and the file turned out not
 330  *      to be a directory.
 331  */
 332 WS_DLL_PUBLIC int test_for_directory(const char *);
 333
 334 /*
 335  * Given a pathname, return:
 336  *
 337  *      the errno, if an attempt to "stat()" the file fails;
 338  *
 339  *      ESPIPE, if the attempt succeeded and the file turned out
 340  *      to be a FIFO;
 341  *
 342  *      0, if the attempt succeeded and the file turned out not
 343  *      to be a FIFO.
 344  */
 345 WS_DLL_PUBLIC int test_for_fifo(const char *);
 346
 347 /*
 348  * Given a pathname, return true if the attempt to "stat()" the file
 349  * succeeds, and it turns out to be a regular file. "stat()" follows
 350  * links, so returns true if the pathname is a link to a regular file.
 351  */
 352 WS_DLL_PUBLIC bool test_for_regular_file(const char *);
 353
 354 /*
 355  * Check if a file exists.
 356  */
 357 WS_DLL_PUBLIC bool file_exists(const char *fname);
 358
 359 /*
 360  * Check if file is existing and has text entries which does not start
 361  * with the comment character.
 362  */
 363 WS_DLL_PUBLIC bool config_file_exists_with_entries(const char *fname, char comment_char);
 364
 365 /*
 366  * Check if two filenames are identical (with absolute and relative paths).
 367  */
 368 WS_DLL_PUBLIC bool files_identical(const char *fname1, const char *fname2);
 369
 370 /*
 371  * Check if file has been recreated since it was opened.
 372  */
 373 WS_DLL_PUBLIC bool file_needs_reopen(int fd, const char* filename);
 374
 375 /*
 376  * Write content to a file in binary mode, for those operating systems that
 377  * care about such things. This should be OK for all files, even text files, as
 378  * we'll write the raw bytes, and we don't look at the bytes as we copy them.
 379  *
 380  * Returns true on success, false on failure. If a failure, it also
 381  * displays a simple dialog window with the error message.
 382  */
 383 WS_DLL_PUBLIC bool write_file_binary_mode(const char *filename,
 384     const void *content, size_t content_len);
 385
 386 /*
 387  * Copy a file in binary mode, for those operating systems that care about
 388  * such things.  This should be OK for all files, even text files, as
 389  * we'll copy the raw bytes, and we don't look at the bytes as we copy
 390  * them.
 391  *
 392  * Returns true on success, false on failure. If a failure, it also
 393  * displays a simple dialog window with the error message.
 394  */
 395 WS_DLL_PUBLIC bool copy_file_binary_mode(const char *from_filename,
 396     const char *to_filename);
 397
 398
 399 /*
 400  * Given a filename return a filesystem URL. Relative paths are prefixed with
 401  * the datafile directory path.
 402  *
 403  * @param filename A file name or path. Relative paths will be prefixed with
 404  * the data file directory path.
 405  * @return A filesystem URL for the file or NULL on failure. A non-NULL return
 406  * value must be freed with g_free().
 407  */
 408 WS_DLL_PUBLIC char* data_file_url(const char *filename);
 409
 410 /*
 411  * Free the internal structtures
 412  */
 413 WS_DLL_PUBLIC void free_progdirs(void);
 414
 415 #ifdef __cplusplus
 416 }
 417 #endif /* __cplusplus */
 418
 419 #endif /* FILESYSTEM_H */