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