BRL-CAD
file.h
Go to the documentation of this file.
1 /* F I L E . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /** @defgroup io Input/Output */
22 /** @defgroup file File Processing */
23 
24 /** @file file.h
25  *
26  */
27 #ifndef BU_FILE_H
28 #define BU_FILE_H
29 
30 #include "common.h"
31 
32 #include <stdio.h> /* For FILE */
33 #include <sys/types.h> /* for off_t */
34 #include <stddef.h> /* for size_t */
35 #include <stdlib.h> /* for getenv */
36 
37 #ifdef HAVE_DLFCN_H
38 # include <dlfcn.h> /* for RTLD_* */
39 #endif
40 
41 #include "bu/defines.h"
42 #include "bu/magic.h"
43 
45 
46 /** @addtogroup file */
47 /** @{ */
48 
49 /** @file libbu/file.c
50  *
51  * Support routines for identifying properties of files and
52  * directories such as whether they exist or are the same as another
53  * given file.
54  *
55  */
56 
57 /**
58  * Returns truthfully whether the given file path exists or not. An
59  * empty or NULL path name is treated as a non-existent file and, as
60  * such, will return false. If fd is non-NULL, it will be set to an
61  * open file descriptor for the provided path.
62  *
63  * @return >0 The given filename exists.
64  * @return 0 The given filename does not exist.
65  */
66 BU_EXPORT extern int bu_file_exists(const char *path, int *fd);
67 
68 /**
69  * Returns truthfully as to whether the two provided filenames are the
70  * same file. If either file does not exist, the result is false. If
71  * either filename is empty or NULL, it is treated as non-existent
72  * and, as such, will also return false.
73  */
74 BU_EXPORT extern int bu_same_file(const char *fn1, const char *fn2);
75 
76 /**
77  * returns truthfully as to whether or not the two provided file
78  * descriptors are the same file. if either file does not exist, the
79  * result is false.
80  */
81 BU_EXPORT extern int bu_same_fd(int fd1, int fd2);
82 
83 /**
84  * returns truthfully if current user can read the specified file or
85  * directory.
86  */
87 BU_EXPORT extern int bu_file_readable(const char *path);
88 
89 /**
90  * returns truthfully if current user can write to the specified file
91  * or directory.
92  */
93 BU_EXPORT extern int bu_file_writable(const char *path);
94 
95 /**
96  * returns truthfully if current user can run the specified file or
97  * directory.
98  */
99 BU_EXPORT extern int bu_file_executable(const char *path);
100 
101 /**
102  * Returns truthfully whether the given file path is a directory. An
103  * empty or NULL path name is treated as a non-existent directory and,
104  * as such, will return false.
105  *
106  * @return >0 The given filename is a directory
107  * @return 0 The given filename is not a directory.
108  */
109 BU_EXPORT extern int bu_file_directory(const char *path);
110 
111 /**
112  * Returns truthfully whether the given file path is a symbolic link.
113  * An empty or NULL path name is treated as a non-existent link and,
114  * as such, will return false.
115  *
116  * @return >0 The given filename is a symbolic link
117  * @return 0 The given filename is not a symbolic link.
118  */
119 BU_EXPORT extern int bu_file_symbolic(const char *path);
120 
121 /**
122  * forcibly attempts to delete a specified file. if the file can be
123  * deleted by relaxing file permissions, they will be changed in order
124  * to delete the file.
125  *
126  * returns truthfully if the specified file was deleted.
127  */
128 BU_EXPORT extern int bu_file_delete(const char *path);
129 
130 /**
131  * matches a filepath pattern to directory entries. if non-NULL,
132  * matching paths are dynamically allocated, stored into the provided
133  * 'matches' array, and followed by a terminating NULL entry.
134  *
135  * If '*matches' is NULL, the caller is expected to free the matches
136  * array with bu_free_argv() If '*matches' is non-NULL (i.e., string
137  * array is already allocated or on the stack), the caller is expected
138  * to ensure adequate entries are allocated and call bu_free_array()
139  * to clean up. If 'matches' is NULL, no entries will be allocated or
140  * stored, but the number of matches will still be returned.
141  *
142  * Example:
143  *
144  * char **my_matches = NULL;
145  * bu_file_glob("src/libbu/[a-e]*.c", &my_matches);
146  *
147  * This will allocate an array for storing glob matches, filling in
148  * the array with all of the directory entries starting with 'a'
149  * through 'e' and ending with a '.c' suffix in the src/libbu
150  * directory.
151  *
152  * returns the number of matches
153  */
154 BU_EXPORT extern size_t bu_file_glob(const char *pattern, char ***matches);
155 
156 /**
157  * Call canonicalization routines to both expand and validate
158  * a path name.
159  *
160  * returns a pointer to the canonical path. Caller must free
161  * the path.
162  */
163 BU_EXPORT extern char * bu_file_path_canonicalize(const char *path);
164 
165 /** @file libbu/fnmatch.c
166  *
167  */
168 
169 #define BU_FNMATCH_NOESCAPE 0x01 /**< bu_fnmatch() flag. Backslash escaping. */
170 #define BU_FNMATCH_PATHNAME 0x02 /**< bu_fnmatch() flag. Slash must be matched by slash. */
171 #define BU_FNMATCH_PERIOD 0x04 /**< bu_fnmatch() flag. Period must be matched by period. */
172 #define BU_FNMATCH_LEADING_DIR 0x08 /**< bu_fnmatch() flag. Ignore `/<tail>` after Imatch. */
173 #define BU_FNMATCH_CASEFOLD 0x10 /**< bu_fnmatch() flag. Case-insensitive searching. */
174 
175 /**
176  * bu_fnmatch() return value when no match is found (0 if found)
177  */
178 #define BU_FNMATCH_NOMATCH 1 /* Match failed. */
179 
180 /**
181  * Function fnmatch() as specified in POSIX 1003.2-1992, section B.6.
182  * Compares a string filename or pathname to a pattern.
183  *
184  * Returns 0 if a match is found or BU_FNMATCH_NOMATCH otherwise.
185  *
186  */
187 BU_EXPORT extern int bu_fnmatch(const char *pattern, const char *pathname, int flags);
188 
189 
190 /** @file libbu/dirent.c
191  *
192  * Functionality for accessing all files in a directory.
193  *
194  */
195 
196 /**
197  * Returns the number of directory entries for a given path matching
198  * an optional glob pattern. If the caller provides a pointer to an
199  * argv-style 'files' array, this function will allocate the array
200  * with dynamically allocated strings for any matching file(s).
201  *
202  * It is the caller's responsibility to free a non-NULL 'files' array
203  * with bu_free_argv().
204  */
205 BU_EXPORT extern size_t bu_dir_list(const char *path, const char *pattern, char ***files);
206 
207 
208 /** @file libbu/realpath.c
209  *
210  */
211 
212 /**
213  * Call canonicalization routines to both expand and validate
214  * a path name.
215  *
216  * Returns a pointer to the canonical path. If resolved_path is
217  * NULL, caller is responsible for freeing the returned path
218  * via bu_free. If supplying a result string, the string must hold
219  * at least MAXPATHLEN characters.
220  */
221 BU_EXPORT extern char * bu_realpath(const char *path, char *resolved_path);
222 
223 /** @file libbu/progname.c
224  *
225  * @brief
226  * Support routines to provide the executable code with information
227  * about executable name used to invoke the current program.
228  *
229  */
230 /**
231  * DEPRECATED: This routine is replaced by bu_getcwd().
232  * Do not use.
233  *
234  * returns the full path to argv0, regardless of how the application
235  * was invoked.
236  *
237  * this routine will return "(BRL-CAD)" if argv[0] cannot be
238  * identified but should never return NULL. this routine is not
239  * thread-safe.
240  */
241 BU_EXPORT extern const char *bu_argv0_full_path(void);
242 
243 /**
244  * Get the name of the running application. application codes should
245  * call bu_setprogname() first to ensure that the program name is
246  * stored appropriately on platforms that do not have an intrinsic
247  * method for tracking the program name automatically.
248  *
249  * while this routine is thread-safe and reentrant, the static string
250  * returned is shared amongst all threads.
251  */
252 BU_EXPORT extern const char *bu_getprogname(void);
253 
254 /**
255  * Set the name of the running application. This isn't strictly
256  * necessary on platforms that have an intrinsic method for tracking
257  * the program name automatically, but is still recommended for
258  * portability and is necessary on some strict modes of compilation.
259  *
260  * while the implementation relies on a static string shared across
261  * all threads, this routine is thread-safe and reentrant.
262  */
263 BU_EXPORT extern void bu_setprogname(const char *path);
264 
265 /** @file libbu/getcwd.c
266  *
267  * @brief
268  * Routine(s) for getting the current working directory full pathname.
269  */
270 /**
271  * returns the pathname for the current working directory.
272  */
273 BU_EXPORT extern char *bu_getcwd(char *buf, size_t size);
274 
275 /**
276  * Report the relative paths being used to hold BRL-CAD applications,
277  * libraries, and data.
278  *
279  * Recognized keys include:
280  *
281  * bin - Directory containing binary applications
282  * lib - Directory containing libraries
283  * include - Directory containing headers
284  * data - Directory containing shared data
285  * share - Directory containing shared data
286  * doc - Directory containing documentation
287  * man - Directory containing Unix man pages
288  *
289  * @return
290  * A STATIC buffer is returned. It is the caller's responsibility to
291  * call bu_strdup() or make other provisions to save the returned
292  * string, before calling again.
293  */
294 
295 /** @file libbu/brlcad_path.c
296  *
297  * @brief
298  * A support routine to provide the executable code with the path
299  * to where the BRL-CAD programs and libraries are installed.
300  *
301  */
302 BU_EXPORT extern const char *bu_brlcad_dir(const char *dirkey, int fail_quietly);
303 
304 /**
305  * Locate where the BRL-CAD applications and libraries are installed.
306  *
307  * The BRL-CAD root is searched for in the following order of
308  * precedence by testing for the rhs existence if provided or the
309  * directory existence otherwise:
310  *
311  * BRLCAD_ROOT environment variable if set
312  * BRLCAD_ROOT compile-time path
313  * run-time path identification
314  * /usr/brlcad static path
315  * current directory
316  *
317  * @return
318  * A STATIC buffer is returned. It is the caller's responsibility to
319  * call bu_strdup() or make other provisions to save the returned
320  * string, before calling again.
321  */
322 BU_EXPORT extern const char *bu_brlcad_root(const char *rhs, int fail_quietly);
323 
324 /**
325  * Locate where the BRL-CAD data resources are installed.
326  *
327  * The BRL-CAD data resources are searched for in the following order
328  * of precedence by testing for the existence of rhs if provided or
329  * the directory existence otherwise:
330  *
331  * BRLCAD_DATA environment variable if set
332  * BRLCAD_DATA compile-time path
333  * bu_brlcad_root/DATA_DIR path
334  * bu_brlcad_root/share path
335  * current directory
336  *
337  * A STATIC buffer is returned. It is the caller's responsibility to
338  * call bu_strdup() or make other provisions to save the returned
339  * string, before calling again.
340  */
341 BU_EXPORT extern const char *bu_brlcad_data(const char *rhs, int fail_quietly);
342 
343 /**
344  * returns the first USER path match to a given executable name.
345  *
346  * Routine to provide BSD "which" functionality, locating binaries of
347  * specified programs from the user's PATH. This is useful to locate
348  * binaries and resources at run-time.
349  *
350  * caller should not free the result, though it will not be preserved
351  * between calls either. the caller should strdup the result if they
352  * need to keep it around.
353  *
354  * routine will return NULL if the executable command cannot be found.
355  */
356 BU_EXPORT extern const char *bu_which(const char *cmd);
357 
358 /**
359  * returns the first SYSTEM path match to a given executable cmd name.
360  *
361  * Routine to provide BSD "whereis" functionality, locating binaries
362  * of specified programs from the SYSTEM path. This is useful to
363  * locate binaries and resources at run-time.
364  *
365  * caller should not free the result, though it will not be preserved
366  * between calls either. the caller should strdup the result if they
367  * need to keep it around.
368  *
369  * routine will return NULL if the executable command cannot be found.
370  */
371 BU_EXPORT extern const char *bu_whereis(const char *cmd);
372 
373 /** @file libbu/temp.c
374  *
375  * Routine to open a temporary file.
376  *
377  */
378 
379 /**
380  * Create a temporary file. The first readable/writable directory
381  * will be used, searching TMPDIR/TEMP/TMP environment variable
382  * directories followed by default system temp directories and
383  * ultimately trying the current directory.
384  *
385  * This routine is guaranteed to return a new unique file or return
386  * NULL on failure. The temporary file will be automatically unlinked
387  * on application exit. It is the caller's responsibility to set file
388  * access settings, preserve file contents, or destroy file contents
389  * if the default behavior is non-optimal.
390  *
391  * The name of the temporary file will be copied into a user-provided
392  * (filepath) buffer if it is a non-NULL pointer and of a sufficient
393  * (len) length to contain the filename.
394  *
395  * This routine is NOT thread-safe.
396  *
397  * Typical Use:
398  @code
399  FILE *fp;
400  char filename[MAXPATHLEN];
401  fp = bu_temp_file(&filename, MAXPATHLEN); // get file name
402  ...
403  fclose(fp); // close the file when you're done
404  ...
405  fp = bu_temp_file(NULL, 0); // don't need file name
406  bu_fchmod(fileno(fp), 0777);
407  ...
408  rewind(fp);
409  while (fputc(0, fp) == 0);
410  fclose(fp);
411  @endcode
412  */
413 BU_EXPORT extern FILE *bu_temp_file(char *filepath, size_t len);
414 
415 /** @file libbu/fchmod.c
416  *
417  * Wrapper around fchmod.
418  *
419  */
420 
421 /**
422  * Portable wrapper for setting a file descriptor's permissions ala
423  * fchmod().
424  */
425 BU_EXPORT extern int bu_fchmod(int fd, unsigned long pmode);
426 
427 
428 /** @file libbu/argv.c
429  *
430  * Functions related to argv processing.
431  *
432  */
433 
434 /**
435  * Build argv[] array from input buffer, by splitting whitespace
436  * separated "words" into null terminated strings.
437  *
438  * 'lim' indicates the maximum number of elements that can be stored
439  * in the argv[] array not including a terminating NULL.
440  *
441  * The 'lp' input buffer is altered by this process. The argv[] array
442  * points into the input buffer.
443  *
444  * The argv[] array needs to have at least lim+1 pointers allocated
445  * for lim items plus a terminating pointer to NULL. The input buffer
446  * should not be freed until argv has been freed or passes out of
447  * scope.
448  *
449  * Returns -
450  * 0 no words in input
451  * argc number of words of input, now in argv[]
452  */
453 BU_EXPORT extern size_t bu_argv_from_string(char *argv[],
454  size_t lim,
455  char *lp);
456 
457 /**
458  * Deallocate all strings in a given argv array and the array itself
459  *
460  * This call presumes the array has been allocated with bu_dup_argv()
461  * or bu_argv_from_path().
462  */
463 BU_EXPORT extern void bu_free_argv(int argc, char *argv[]);
464 
465 /**
466  * free up to argc elements of memory allocated to an array without
467  * free'ing the array itself.
468  */
469 BU_EXPORT extern void bu_free_array(int argc, char *argv[], const char *str);
470 
471 /**
472  * Dynamically duplicate an argv array and all elements in the array
473  *
474  * Duplicate an argv array by duplicating all strings and the array
475  * itself. It is the caller's responsibility to free the array
476  * returned including all elements in the array by calling bu_free()
477  * or bu_free_argv().
478  */
479 BU_EXPORT extern char **bu_dup_argv(int argc, const char *argv[]);
480 
481 /**
482  * Combine two argv arrays into one new (duplicated) argv array.
483  *
484  * If insert is negative, the insertArgv array elements will be
485  * prepended into the new argv array. If insert is greater than or
486  * equal to argc, the insertArgv array elements will be appended after
487  * all duplicated elements in the specified argv array. Otherwise,
488  * the insert argument is the position where the insertArgv array
489  * elements will be merged with the specified argv array.
490  */
491 BU_EXPORT extern char **bu_dupinsert_argv(int insert, int insertArgc, const char *insertArgv[], int argc, const char *argv[]);
492 
493 /**
494  * Generate an argv array from a path
495  *
496  * Given a path string, separate the path elements into a dynamically
497  * allocated argv array with the path separators removed. It is the
498  * caller's responsibility to free the array that is returned as well
499  * as all elements in the array using bu_free_argv() or manually
500  * calling bu_free().
501  */
502 BU_EXPORT extern char **bu_argv_from_path(const char *path, int *ac);
503 
504 
505 /** @file libbu/interrupt.c
506  *
507  * Routines for managing signals. In particular, provide a common
508  * means to temporarily buffer processing a signal during critical
509  * write operations.
510  *
511  */
512 
513 /**
514  * Defer signal processing and interrupts before critical sections.
515  *
516  * Signal processing for a variety of signals that would otherwise
517  * disrupt the logic of an application are put on hold until
518  * bu_restore_interrupts() is called.
519  *
520  * If an interrupt signal is received while suspended, it will be
521  * raised when/if interrupts are restored.
522  *
523  * Returns 0 on success.
524  * Returns non-zero on error (with perror set if signal() failure).
525  */
526 BU_EXPORT extern int bu_suspend_interrupts(void);
527 
528 /**
529  * Resume signal processing and interrupts after critical sections.
530  *
531  * If a signal was raised since bu_suspend_interrupts() was called,
532  * the previously installed signal handler will be immediately called
533  * albeit only once even if multiple signals were received.
534  *
535  * Returns 0 on success.
536  * Returns non-zero on error (with perror set if signal() failure).
537  */
538 BU_EXPORT extern int bu_restore_interrupts(void);
539 
540 /** @file libbu/dlfcn.c
541  * Dynamic Library functionality
542  */
543 #ifdef HAVE_DLOPEN
544 # define BU_RTLD_LAZY RTLD_LAZY
545 # define BU_RTLD_NOW RTLD_NOW
546 # define BU_RTLD_GLOBAL RTLD_GLOBAL
547 # define BU_RTLD_LOCAL RTLD_LOCAL
548 #else
549 # define BU_RTLD_LAZY 1
550 # define BU_RTLD_NOW 2
551 # define BU_RTLD_GLOBAL 0x100
552 # define BU_RTLD_LOCAL 0
553 #endif
554 BU_EXPORT extern void *bu_dlopen(const char *path, int mode);
555 BU_EXPORT extern void *bu_dlsym(void *path, const char *symbol);
556 BU_EXPORT extern int bu_dlclose(void *handle);
557 BU_EXPORT extern const char *bu_dlerror(void);
558 
559 /** NEW: Do not use. */
560 BU_EXPORT extern int bu_fseek(FILE *stream, off_t offset, int origin);
561 /** NEW: Do not use. */
562 BU_EXPORT extern off_t bu_ftell(FILE *stream);
563 
564 /** @} */
565 
567 
568 #endif /* BU_FILE_H */
569 
570 /*
571  * Local Variables:
572  * mode: C
573  * tab-width: 8
574  * indent-tabs-mode: t
575  * c-file-style: "stroustrup"
576  * End:
577  * ex: shiftwidth=4 tabstop=8
578  */
int bu_restore_interrupts(void)
Definition: interrupt.c:217
int bu_fchmod(int fd, unsigned long pmode)
Definition: fchmod.c:131
off_t bu_ftell(FILE *stream)
Definition: file.c:344
void bu_free_argv(int argc, char *argv[])
Definition: argv.c:165
char ** bu_argv_from_path(const char *path, int *ac)
Definition: argv.c:267
int bu_fseek(FILE *stream, off_t offset, int origin)
Definition: file.c:330
Header file for the BRL-CAD common definitions.
int bu_file_readable(const char *path)
Definition: file.c:223
void bu_free_array(int argc, char *argv[], const char *str)
Definition: argv.c:186
size_t bu_file_glob(const char *pattern, char ***matches)
const char * bu_brlcad_data(const char *rhs, int fail_quietly)
Definition: brlcad_path.c:405
int bu_file_writable(const char *path)
Definition: file.c:230
const char * bu_dlerror(void)
Definition: dlfcn.c:76
#define __BEGIN_DECLS
Definition: common.h:73
const char * bu_which(const char *cmd)
Definition: which.c:43
FILE * bu_temp_file(char *filepath, size_t len)
Definition: temp.c:180
const char * bu_getprogname(void)
Definition: progname.c:96
int bu_fnmatch(const char *pattern, const char *pathname, int flags)
Definition: fnmatch.c:311
int bu_file_symbolic(const char *path)
Definition: file.c:261
int bu_same_file(const char *fn1, const char *fn2)
Definition: file.c:101
int bu_file_directory(const char *path)
Definition: file.c:244
void * bu_dlsym(void *path, const char *symbol)
Definition: dlfcn.c:50
const char * bu_brlcad_dir(const char *dirkey, int fail_quietly)
Definition: brlcad_path.c:231
char * bu_getcwd(char *buf, size_t size)
Definition: getcwd.c:45
int bu_same_fd(int fd1, int fd2)
Definition: file.c:129
int bu_dlclose(void *handle)
Definition: dlfcn.c:63
char ** bu_dup_argv(int argc, const char *argv[])
Definition: argv.c:207
size_t bu_dir_list(const char *path, const char *pattern, char ***files)
Definition: dirent.c:34
const char * bu_whereis(const char *cmd)
Definition: whereis.c:52
int bu_suspend_interrupts(void)
Definition: interrupt.c:191
void * bu_dlopen(const char *path, int mode)
Definition: dlfcn.c:37
#define __END_DECLS
Definition: common.h:74
size_t bu_argv_from_string(char *argv[], size_t lim, char *lp)
Definition: argv.c:32
const char * bu_brlcad_root(const char *rhs, int fail_quietly)
Definition: brlcad_path.c:292
char * bu_realpath(const char *path, char *resolved_path)
Definition: realpath.c:33
int bu_file_executable(const char *path)
Definition: file.c:237
char ** bu_dupinsert_argv(int insert, int insertArgc, const char *insertArgv[], int argc, const char *argv[])
Definition: argv.c:225
char * bu_file_path_canonicalize(const char *path)
int bu_file_exists(const char *path, int *fd)
Definition: file.c:57
const char * bu_argv0_full_path(void)
Definition: progname.c:48
void bu_setprogname(const char *path)
Definition: progname.c:143
int bu_file_delete(const char *path)
Definition: file.c:278