BRL-CAD
Collaboration diagram for File Processing:

Files

file  file.c
 
file  fnmatch.c
 
file  dirent.c
 
file  realpath.c
 
file  progname.c
 Support routines to provide the executable code with information about executable name used to invoke the current program.
 
file  getcwd.c
 Routine(s) for getting the current working directory full pathname.
 
file  brlcad_path.c
 A support routine to provide the executable code with the path to where the BRL-CAD programs and libraries are installed.
 
file  temp.c
 
file  fchmod.c
 
file  argv.c
 
file  interrupt.c
 
file  dlfcn.c
 

Macros

#define BU_FNMATCH_NOESCAPE   0x01
 
#define BU_FNMATCH_PATHNAME   0x02
 
#define BU_FNMATCH_PERIOD   0x04
 
#define BU_FNMATCH_LEADING_DIR   0x08
 
#define BU_FNMATCH_CASEFOLD   0x10
 
#define BU_FNMATCH_NOMATCH   1 /* Match failed. */
 
#define BU_RTLD_LAZY   1
 
#define BU_RTLD_NOW   2
 
#define BU_RTLD_GLOBAL   0x100
 
#define BU_RTLD_LOCAL   0
 

Functions

int bu_file_exists (const char *path, int *fd)
 
int bu_same_file (const char *fn1, const char *fn2)
 
int bu_same_fd (int fd1, int fd2)
 
int bu_file_readable (const char *path)
 
int bu_file_writable (const char *path)
 
int bu_file_executable (const char *path)
 
int bu_file_directory (const char *path)
 
int bu_file_symbolic (const char *path)
 
int bu_file_delete (const char *path)
 
size_t bu_file_glob (const char *pattern, char ***matches)
 
char * bu_file_path_canonicalize (const char *path)
 
int bu_fnmatch (const char *pattern, const char *pathname, int flags)
 
size_t bu_dir_list (const char *path, const char *pattern, char ***files)
 
char * bu_realpath (const char *path, char *resolved_path)
 
const char * bu_argv0_full_path (void)
 
const char * bu_getprogname (void)
 
void bu_setprogname (const char *path)
 
char * bu_getcwd (char *buf, size_t size)
 
const char * bu_brlcad_dir (const char *dirkey, int fail_quietly)
 
const char * bu_brlcad_root (const char *rhs, int fail_quietly)
 
const char * bu_brlcad_data (const char *rhs, int fail_quietly)
 
const char * bu_which (const char *cmd)
 
const char * bu_whereis (const char *cmd)
 
FILE * bu_temp_file (char *filepath, size_t len)
 
int bu_fchmod (int fd, unsigned long pmode)
 
size_t bu_argv_from_string (char *argv[], size_t lim, char *lp)
 
void bu_free_argv (int argc, char *argv[])
 
void bu_free_array (int argc, char *argv[], const char *str)
 
char ** bu_dup_argv (int argc, const char *argv[])
 
char ** bu_dupinsert_argv (int insert, int insertArgc, const char *insertArgv[], int argc, const char *argv[])
 
char ** bu_argv_from_path (const char *path, int *ac)
 
int bu_suspend_interrupts (void)
 
int bu_restore_interrupts (void)
 
void * bu_dlopen (const char *path, int mode)
 
void * bu_dlsym (void *path, const char *symbol)
 
int bu_dlclose (void *handle)
 
const char * bu_dlerror (void)
 
int bu_fseek (FILE *stream, off_t offset, int origin)
 
off_t bu_ftell (FILE *stream)
 

Detailed Description

Macro Definition Documentation

#define BU_FNMATCH_NOESCAPE   0x01

bu_fnmatch() flag. Backslash escaping.

Definition at line 169 of file file.h.

#define BU_FNMATCH_PATHNAME   0x02

bu_fnmatch() flag. Slash must be matched by slash.

Definition at line 170 of file file.h.

#define BU_FNMATCH_PERIOD   0x04

bu_fnmatch() flag. Period must be matched by period.

Definition at line 171 of file file.h.

Referenced by bu_fnmatch().

#define BU_FNMATCH_LEADING_DIR   0x08

bu_fnmatch() flag. Ignore /<tail> after Imatch.

Definition at line 172 of file file.h.

Referenced by bu_fnmatch().

#define BU_FNMATCH_CASEFOLD   0x10

bu_fnmatch() flag. Case-insensitive searching.

Definition at line 173 of file file.h.

Referenced by f_iname().

#define BU_FNMATCH_NOMATCH   1 /* Match failed. */

bu_fnmatch() return value when no match is found (0 if found)

Definition at line 178 of file file.h.

Referenced by bu_fnmatch().

#define BU_RTLD_LAZY   1

Definition at line 549 of file file.h.

#define BU_RTLD_NOW   2

Definition at line 550 of file file.h.

#define BU_RTLD_GLOBAL   0x100

Definition at line 551 of file file.h.

#define BU_RTLD_LOCAL   0

Definition at line 552 of file file.h.

Function Documentation

int bu_file_exists ( const char *  path,
int *  fd 
)

Returns truthfully whether the given file path exists or not. An empty or NULL path name is treated as a non-existent file and, as such, will return false. If fd is non-NULL, it will be set to an open file descriptor for the provided path.

Returns
>0 The given filename exists.
0 The given filename does not exist.

Definition at line 57 of file file.c.

References bu_debug, BU_DEBUG_PATHS, bu_log(), and UNLIKELY.

Referenced by _ged_editit(), _ged_open_dbip(), bu_argv0_full_path(), bu_bomb(), bu_brlcad_data(), bu_file_delete(), bu_getcwd(), bu_same_file(), bu_whereis(), bu_which(), find_path(), ged_lc(), ged_loadview(), ged_saveview(), main(), and tclcad_auto_path().

Here is the call graph for this function:

int bu_same_file ( const char *  fn1,
const char *  fn2 
)

Returns truthfully as to whether the two provided filenames are the same file. If either file does not exist, the result is false. If either filename is empty or NULL, it is treated as non-existent and, as such, will also return false.

Definition at line 101 of file file.c.

References bu_file_exists(), and UNLIKELY.

Referenced by ged_loadview(), and tclcad_auto_path().

Here is the call graph for this function:

int bu_same_fd ( int  fd1,
int  fd2 
)

returns truthfully as to whether or not the two provided file descriptors are the same file. if either file does not exist, the result is false.

Definition at line 129 of file file.c.

References UNLIKELY.

int bu_file_readable ( const char *  path)

returns truthfully if current user can read the specified file or directory.

Definition at line 223 of file file.c.

References file_access(), and R_OK.

Referenced by _ged_open_dbip().

Here is the call graph for this function:

int bu_file_writable ( const char *  path)

returns truthfully if current user can write to the specified file or directory.

Definition at line 230 of file file.c.

References file_access(), and W_OK.

Referenced by bu_temp_file().

Here is the call graph for this function:

int bu_file_executable ( const char *  path)

returns truthfully if current user can run the specified file or directory.

Definition at line 237 of file file.c.

References file_access(), and X_OK.

Referenced by bu_temp_file().

Here is the call graph for this function:

int bu_file_directory ( const char *  path)

Returns truthfully whether the given file path is a directory. An empty or NULL path name is treated as a non-existent directory and, as such, will return false.

Returns
>0 The given filename is a directory
0 The given filename is not a directory.

Definition at line 244 of file file.c.

References UNLIKELY.

int bu_file_symbolic ( const char *  path)

Returns truthfully whether the given file path is a symbolic link. An empty or NULL path name is treated as a non-existent link and, as such, will return false.

Returns
>0 The given filename is a symbolic link
0 The given filename is not a symbolic link.

Definition at line 261 of file file.c.

References UNLIKELY.

int bu_file_delete ( const char *  path)

forcibly attempts to delete a specified file. if the file can be deleted by relaxing file permissions, they will be changed in order to delete the file.

returns truthfully if the specified file was deleted.

Definition at line 278 of file file.c.

References bu_fchmod(), bu_file_exists(), and BU_STR_EQUAL.

Referenced by dsk_free(), ged_edcodes(), ged_edmater(), ged_put_comb(), ged_red(), ged_tables(), and temp_close_files().

Here is the call graph for this function:

size_t bu_file_glob ( const char *  pattern,
char ***  matches 
)

matches a filepath pattern to directory entries. if non-NULL, matching paths are dynamically allocated, stored into the provided 'matches' array, and followed by a terminating NULL entry.

If '*matches' is NULL, the caller is expected to free the matches array with bu_free_argv() If '*matches' is non-NULL (i.e., string array is already allocated or on the stack), the caller is expected to ensure adequate entries are allocated and call bu_free_array() to clean up. If 'matches' is NULL, no entries will be allocated or stored, but the number of matches will still be returned.

Example:

char **my_matches = NULL; bu_file_glob("src/libbu/[a-e]*.c", &my_matches);

This will allocate an array for storing glob matches, filling in the array with all of the directory entries starting with 'a' through 'e' and ending with a '.c' suffix in the src/libbu directory.

returns the number of matches

char* bu_file_path_canonicalize ( const char *  path)

Call canonicalization routines to both expand and validate a path name.

returns a pointer to the canonical path. Caller must free the path.

int bu_fnmatch ( const char *  pattern,
const char *  pathname,
int  flags 
)

Function fnmatch() as specified in POSIX 1003.2-1992, section B.6. Compares a string filename or pathname to a pattern.

Returns 0 if a match is found or BU_FNMATCH_NOMATCH otherwise.

Definition at line 311 of file fnmatch.c.

References BU_FNMATCH_LEADING_DIR, BU_FNMATCH_NOMATCH, BU_FNMATCH_PERIOD, FNMATCH_EOS, FNMATCH_RANGE_ERROR, FNMATCH_RANGE_MATCH, FNMATCH_RANGE_NOMATCH, and strchr().

Referenced by avs_check(), bu_dir_list(), c_bool(), db_ls(), db_regexp_match_all(), f_iname(), f_name(), f_path(), f_type(), ged_expand(), ged_glob(), and ged_match().

Here is the call graph for this function:

size_t bu_dir_list ( const char *  path,
const char *  pattern,
char ***  files 
)

Returns the number of directory entries for a given path matching an optional glob pattern. If the caller provides a pointer to an argv-style 'files' array, this function will allocate the array with dynamically allocated strings for any matching file(s).

It is the caller's responsibility to free a non-NULL 'files' array with bu_free_argv().

Definition at line 34 of file dirent.c.

References bu_calloc(), bu_fnmatch(), and bu_strdup.

Here is the call graph for this function:

char* bu_realpath ( const char *  path,
char *  resolved_path 
)

Call canonicalization routines to both expand and validate a path name.

Returns a pointer to the canonical path. If resolved_path is NULL, caller is responsible for freeing the returned path via bu_free. If supplying a result string, the string must hold at least MAXPATHLEN characters.

Definition at line 33 of file realpath.c.

References bu_calloc(), bu_strlcpy, and MAXPATHLEN.

Referenced by bu_brlcad_root(), bu_getcwd(), bu_open_mapped_file(), and ged_lc().

Here is the call graph for this function:

const char* bu_argv0_full_path ( void  )

DEPRECATED: This routine is replaced by bu_getcwd(). Do not use.

returns the full path to argv0, regardless of how the application was invoked.

this routine will return "(BRL-CAD)" if argv[0] cannot be identified but should never return NULL. this routine is not thread-safe.

Definition at line 48 of file progname.c.

References BU_DIR_SEPARATOR, bu_file_exists(), bu_getcwd(), bu_which(), and MAXPATHLEN.

Referenced by bu_backtrace(), bu_brlcad_root(), bu_crashreport(), main(), and tclcad_auto_path().

Here is the call graph for this function:

const char* bu_getprogname ( void  )

Get the name of the running application. application codes should call bu_setprogname() first to ensure that the program name is stored appropriately on platforms that do not have an intrinsic method for tracking the program name automatically.

while this routine is thread-safe and reentrant, the static string returned is shared amongst all threads.

Definition at line 96 of file progname.c.

References bu_basename(), bu_calloc(), bu_free(), BU_SEM_SYSCALL, bu_semaphore_acquire(), bu_semaphore_release(), BU_STR_EQUAL, bu_strlcpy, DEFAULT_PROGNAME, and MAXPATHLEN.

Referenced by _ged_editit(), bu_argv0(), bu_bomb(), bu_crashreport(), main(), and tclcad_auto_path().

Here is the call graph for this function:

void bu_setprogname ( const char *  path)

Set the name of the running application. This isn't strictly necessary on platforms that have an intrinsic method for tracking the program name automatically, but is still recommended for portability and is necessary on some strict modes of compilation.

while the implementation relies on a static string shared across all threads, this routine is thread-safe and reentrant.

Definition at line 143 of file progname.c.

References BU_SEM_SYSCALL, bu_semaphore_acquire(), bu_semaphore_release(), bu_strlcpy, and MAXPATHLEN.

Referenced by icv_rot(), and main().

Here is the call graph for this function:

char* bu_getcwd ( char *  buf,
size_t  size 
)

returns the pathname for the current working directory.

Definition at line 45 of file getcwd.c.

References BU_ASSERT, bu_calloc(), bu_file_exists(), bu_realpath(), bu_strlcpy, MAXPATHLEN, and memset().

Referenced by bu_argv0_full_path().

Here is the call graph for this function:

const char* bu_brlcad_dir ( const char *  dirkey,
int  fail_quietly 
)

Definition at line 231 of file brlcad_path.c.

References BU_STR_EQUAL, and MAXPATHLEN.

Referenced by tcl_bu_brlcad_dir().

const char* bu_brlcad_root ( const char *  rhs,
int  fail_quietly 
)

Locate where the BRL-CAD applications and libraries are installed.

The BRL-CAD root is searched for in the following order of precedence by testing for the rhs existence if provided or the directory existence otherwise:

BRLCAD_ROOT environment variable if set BRLCAD_ROOT compile-time path run-time path identification /usr/brlcad static path current directory

Returns
A STATIC buffer is returned. It is the caller's responsibility to call bu_strdup() or make other provisions to save the returned string, before calling again.

Definition at line 292 of file brlcad_path.c.

References BRLCAD_ROOT, bu_argv0_full_path(), bu_debug, BU_DEBUG_PATHS, bu_dirname(), bu_free(), bu_log(), bu_realpath(), bu_vls_addr(), bu_vls_free(), BU_VLS_INIT_ZERO, bu_vls_strcat(), find_path(), MAX_WHERE_SIZE, MAXPATHLEN, root_missing(), and UNLIKELY.

Referenced by bu_brlcad_data(), ged_nirt(), ged_rt(), ged_rtcheck(), ged_rtwizard(), load_dynamic_shader(), tcl_bu_brlcad_root(), and tclcad_auto_path().

Here is the call graph for this function:

const char* bu_brlcad_data ( const char *  rhs,
int  fail_quietly 
)

Locate where the BRL-CAD data resources are installed.

The BRL-CAD data resources are searched for in the following order of precedence by testing for the existence of rhs if provided or the directory existence otherwise:

BRLCAD_DATA environment variable if set BRLCAD_DATA compile-time path bu_brlcad_root/DATA_DIR path bu_brlcad_root/share path current directory

A STATIC buffer is returned. It is the caller's responsibility to call bu_strdup() or make other provisions to save the returned string, before calling again.

Definition at line 405 of file brlcad_path.c.

References _brlcad_data(), BPC, bu_brlcad_root(), bu_debug, BU_DEBUG_PATHS, bu_file_exists(), bu_log(), bu_vls_addr(), bu_vls_free(), BU_VLS_INIT_ZERO, bu_vls_strcat(), data_missing(), find_path(), MAX_WHERE_SIZE, MAXPATHLEN, and UNLIKELY.

Referenced by get_font(), tcl_bu_brlcad_data(), tclcad_auto_path(), and vfont_get().

Here is the call graph for this function:

const char* bu_which ( const char *  cmd)

returns the first USER path match to a given executable name.

Routine to provide BSD "which" functionality, locating binaries of specified programs from the user's PATH. This is useful to locate binaries and resources at run-time.

caller should not free the result, though it will not be preserved between calls either. the caller should strdup the result if they need to keep it around.

routine will return NULL if the executable command cannot be found.

Definition at line 43 of file which.c.

References bu_debug, BU_DEBUG_PATHS, BU_DIR_SEPARATOR, bu_file_exists(), bu_log(), BU_PATH_SEPARATOR, BU_STR_EQUAL, bu_strlcpy, MAXPATHENV, MAXPATHLEN, memset(), strchr(), and UNLIKELY.

Referenced by _ged_editit(), bu_argv0_full_path(), bu_backtrace(), bu_crashreport(), and tclcad_auto_path().

Here is the call graph for this function:

const char* bu_whereis ( const char *  cmd)

returns the first SYSTEM path match to a given executable cmd name.

Routine to provide BSD "whereis" functionality, locating binaries of specified programs from the SYSTEM path. This is useful to locate binaries and resources at run-time.

caller should not free the result, though it will not be preserved between calls either. the caller should strdup the result if they need to keep it around.

routine will return NULL if the executable command cannot be found.

Definition at line 52 of file whereis.c.

References bu_debug, BU_DEBUG_PATHS, BU_DIR_SEPARATOR, bu_file_exists(), bu_log(), BU_PATH_SEPARATOR, BU_STR_EQUAL, bu_strlcpy, MAXPATHENV, MAXPATHLEN, memset(), strchr(), and UNLIKELY.

Referenced by bu_backtrace().

Here is the call graph for this function:

FILE* bu_temp_file ( char *  filepath,
size_t  len 
)

Create a temporary file. The first readable/writable directory will be used, searching TMPDIR/TEMP/TMP environment variable directories followed by default system temp directories and ultimately trying the current directory.

This routine is guaranteed to return a new unique file or return NULL on failure. The temporary file will be automatically unlinked on application exit. It is the caller's responsibility to set file access settings, preserve file contents, or destroy file contents if the default behavior is non-optimal.

The name of the temporary file will be copied into a user-provided (filepath) buffer if it is a non-NULL pointer and of a sufficient (len) length to contain the filename.

This routine is NOT thread-safe.

Typical Use:

1 FILE *fp;
2 char filename[MAXPATHLEN];
3 fp = bu_temp_file(&filename, MAXPATHLEN); // get file name
4 ...
5 fclose(fp); // close the file when you're done
6 ...
7 fp = bu_temp_file(NULL, 0); // don't need file name
8 bu_fchmod(fileno(fp), 0777);
9 ...
10 rewind(fp);
11 while (fputc(0, fp) == 0);
12 fclose(fp);

Definition at line 180 of file temp.c.

References _TF_FAIL, BU_DIR_SEPARATOR, bu_file_executable(), bu_file_writable(), bu_log(), temp_file_list::fd, fdopen(), MAXPATHLEN, mkstemp(), temp_add_to_list(), and UNLIKELY.

Referenced by ged_edcodes(), ged_edmater(), ged_red(), and initialise_buffers().

Here is the call graph for this function:

int bu_fchmod ( int  fd,
unsigned long  pmode 
)

Portable wrapper for setting a file descriptor's permissions ala fchmod().

Definition at line 131 of file fchmod.c.

References GetFileNameFromHandle(), and MAXPATHLEN.

Referenced by bu_file_delete(), and ged_saveview().

Here is the call graph for this function:

size_t bu_argv_from_string ( char *  argv[],
size_t  lim,
char *  lp 
)

Build argv[] array from input buffer, by splitting whitespace separated "words" into null terminated strings.

'lim' indicates the maximum number of elements that can be stored in the argv[] array not including a terminating NULL.

The 'lp' input buffer is altered by this process. The argv[] array points into the input buffer.

The argv[] array needs to have at least lim+1 pointers allocated for lim items plus a terminating pointer to NULL. The input buffer should not be freed until argv has been freed or passes out of scope.

Returns - 0 no words in input argc number of words of input, now in argv[]

Definition at line 32 of file argv.c.

References bu_bomb(), and UNLIKELY.

Referenced by _ged_editit(), db_search(), ged_annotate(), ged_draw_guts(), ged_eac(), ged_erase(), ged_putmat(), ged_tree(), move_all_file(), and rt_do_cmd().

Here is the call graph for this function:

void bu_free_argv ( int  argc,
char *  argv[] 
)

Deallocate all strings in a given argv array and the array itself

This call presumes the array has been allocated with bu_dup_argv() or bu_argv_from_path().

Definition at line 165 of file argv.c.

References bu_free(), and UNLIKELY.

Referenced by db_close(), and ged_search().

Here is the call graph for this function:

void bu_free_array ( int  argc,
char *  argv[],
const char *  str 
)

free up to argc elements of memory allocated to an array without free'ing the array itself.

Definition at line 186 of file argv.c.

References bu_free(), and UNLIKELY.

Here is the call graph for this function:

char** bu_dup_argv ( int  argc,
const char *  argv[] 
)

Dynamically duplicate an argv array and all elements in the array

Duplicate an argv array by duplicating all strings and the array itself. It is the caller's responsibility to free the array returned including all elements in the array by calling bu_free() or bu_free_argv().

Definition at line 207 of file argv.c.

References bu_calloc(), bu_strdup, and UNLIKELY.

Referenced by bu_dupinsert_argv(), ged_exists(), and ged_search().

Here is the call graph for this function:

char** bu_dupinsert_argv ( int  insert,
int  insertArgc,
const char *  insertArgv[],
int  argc,
const char *  argv[] 
)

Combine two argv arrays into one new (duplicated) argv array.

If insert is negative, the insertArgv array elements will be prepended into the new argv array. If insert is greater than or equal to argc, the insertArgv array elements will be appended after all duplicated elements in the specified argv array. Otherwise, the insert argument is the position where the insertArgv array elements will be merged with the specified argv array.

Definition at line 225 of file argv.c.

References bu_calloc(), bu_dup_argv(), and bu_strdup.

Here is the call graph for this function:

char** bu_argv_from_path ( const char *  path,
int *  ac 
)

Generate an argv array from a path

Given a path string, separate the path elements into a dynamically allocated argv array with the path separators removed. It is the caller's responsibility to free the array that is returned as well as all elements in the array using bu_free_argv() or manually calling bu_free().

Definition at line 267 of file argv.c.

References bu_calloc(), bu_free(), bu_strdup, bu_ptbl::end, strchr(), and UNLIKELY.

Here is the call graph for this function:

int bu_suspend_interrupts ( void  )

Defer signal processing and interrupts before critical sections.

Signal processing for a variety of signals that would otherwise disrupt the logic of an application are put on hold until bu_restore_interrupts() is called.

If an interrupt signal is received while suspended, it will be raised when/if interrupts are restored.

Returns 0 on success. Returns non-zero on error (with perror set if signal() failure).

Definition at line 191 of file interrupt.c.

References interrupt_suspend_signal().

Referenced by db_write().

Here is the call graph for this function:

int bu_restore_interrupts ( void  )

Resume signal processing and interrupts after critical sections.

If a signal was raised since bu_suspend_interrupts() was called, the previously installed signal handler will be immediately called albeit only once even if multiple signals were received.

Returns 0 on success. Returns non-zero on error (with perror set if signal() failure).

Definition at line 217 of file interrupt.c.

References interrupt_restore_signal().

Referenced by db_write().

Here is the call graph for this function:

void* bu_dlopen ( const char *  path,
int  mode 
)

Definition at line 37 of file dlfcn.c.

References bu_log().

Here is the call graph for this function:

void* bu_dlsym ( void *  path,
const char *  symbol 
)

Definition at line 50 of file dlfcn.c.

References bu_log().

Here is the call graph for this function:

int bu_dlclose ( void *  handle)

Definition at line 63 of file dlfcn.c.

References bu_log().

Here is the call graph for this function:

const char* bu_dlerror ( void  )

Definition at line 76 of file dlfcn.c.

References bu_log().

Here is the call graph for this function:

int bu_fseek ( FILE *  stream,
off_t  offset,
int  origin 
)

NEW: Do not use.

Definition at line 330 of file file.c.

Referenced by db_read(), db_scan(), db_write(), and icv_rot().

off_t bu_ftell ( FILE *  stream)

NEW: Do not use.

Definition at line 344 of file file.c.

Referenced by db5_scan(), db_scan(), and get_font().