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