Applications

Routines for application setup and supplying information to user programs. More...

Collaboration diagram for Applications:

Files
file	app.h

Enumerations
enum	bu_dir_t {   BU_DIR_CURR =1 , BU_DIR_INIT , BU_DIR_BIN , BU_DIR_LIB ,   BU_DIR_LIBEXEC , BU_DIR_INCLUDE , BU_DIR_DATA , BU_DIR_DOC ,   BU_DIR_MAN , BU_DIR_TEMP , BU_DIR_HOME , BU_DIR_CACHE ,   BU_DIR_CONFIG , BU_DIR_EXT , BU_DIR_LIBEXT , BU_DIR_END }
	BRL-CAD specific path queries. More...

Functions
DEPRECATED const char *	bu_argv0_full_path (void)
char *	bu_getcwd (char *buf, size_t size)
char *	bu_getiwd (char *buf, size_t size)
const char *	bu_getprogname (void)
void	bu_setprogname (const char *path)
const char *	bu_which (const char *cmd)
const char *	bu_whereis (const char *cmd)
FILE *	bu_temp_file (char *filepath, size_t len)
	Routine to open a temporary file.
const char *	bu_temp_file_name (char *filename, size_t len)
int	bu_fchmod (int fd, unsigned long pmode)
	Wrapper around fchmod.
const char *	bu_dir (char *result, size_t len,...)
void	bu_mkdir (const char *path)
void	bu_dirclear (const char *d)

Detailed Description

Routines for application setup and supplying information to user programs.

Routines for inspecting and reporting characteristics of the current running application environment.

Enumeration Type Documentation

bu_dir_t

enum bu_dir_t

BRL-CAD specific path queries.

Enumerator
BU_DIR_CURR	(unknown) current working directory
BU_DIR_INIT	(unknown) initial working directory
BU_DIR_BIN	(read-only) user executables (bin)
BU_DIR_LIB	(read-only) object libraries (lib)
BU_DIR_LIBEXEC	(read-only) object libraries (libexec)
BU_DIR_INCLUDE	(read-only) C/C++ header files (include)
BU_DIR_DATA	(read-only) data files (share)
BU_DIR_DOC	(read-only) documentation, (DATA/doc)
BU_DIR_MAN	(read-only) manual pages, (DATA/man)
BU_DIR_TEMP	(read/write) temporary files (TEMP)
BU_DIR_HOME	(read/write) user home directory (HOME)
BU_DIR_CACHE	(read/write) user cache directory (BU_CACHE_DIR)
BU_DIR_CONFIG	(read/write) user config directory (HOME/.app)
BU_DIR_EXT	(n/a) optional executable extension
BU_DIR_LIBEXT	(n/a) optional library extension
BU_DIR_END	always the last entry, for iterators

Definition at line 231 of file app.h.

Function Documentation

bu_argv0_full_path()

DEPRECATED const char * bu_argv0_full_path ( void  )

extern

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.

bu_getcwd()

char * bu_getcwd ( char *  buf, size_t  size  )

extern

Routine for obtaining the current working directory.

Result is written into the provided buf, up to size chars, and returned. If buf is NULL, dynamically allocated memory will be returned and must be free'd via bu_free().

bu_getiwd()

char * bu_getiwd ( char *  buf, size_t  size  )

extern

Routine for obtaining the initial working directory during application startup.

Result is written into the provided buf, up to size chars, and returned. If buf is NULL, dynamically allocated memory will be returned and must be free'd via bu_free().

bu_getprogname()

const char * bu_getprogname ( void  )

extern

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.

bu_setprogname()

void bu_setprogname ( const char *  path )

extern

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.

bu_which()

const char * bu_which ( const char *  cmd )

extern

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.

bu_whereis()

const char * bu_whereis ( const char *  cmd )

extern

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.

bu_temp_file()

FILE * bu_temp_file ( char *  filepath, size_t  len  )

extern

Routine to open a temporary file.

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.

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 guaranteed to return a new unique file or return NULL on failure. The file should be closed via fclose() when it is no longer needed. 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 temporary file may no longer exist after a call to fclose(), so do not close a handle until you are are done accessing it. Calling fileno()+dup()+fdopen() can obtain a second handle on an open file.

This routine is NOT thread-safe.

Typical Use:

FILE *fp;
char filename[MAXPATHLEN];
fp = bu_temp_file(&filename, MAXPATHLEN); // get a named temp file
...
fclose(fp); // close the file when you're done
...
fp = bu_temp_file(NULL, 0); // get an anonymous temp file
bu_fchmod(fileno(fp), 0777);
...
rewind(fp);
while (fputc(0, fp) == 0);
fclose(fp);

bu_temp_file_name()

const char * bu_temp_file_name ( char *  filename, size_t  len  )

extern

Generate a temporary file name using a prefix (if supplied), the current process ID, and the current thread's ID

This function writes into buffer and returns a temporary file name that is unique to a process / thread pair. The caller can further distinguish the generated name using a specified filename prefix. When not supplied, the PACKAGE_NAME (BRL-CAD) is used as the prefix.

Note that the filename parameter doubles as both a prefix specifier as well as a return buffer.

Parameters

filename	prefixes the name, doubles as return buffer if len is set
len	total size of the available filename buffer

Returns

name in the form of prefix_procID_threadID. This will be 'filename' or, when NULL, a read-only STATIC buffer will be returned that will be the caller's responsibility to bu_strdup() or otherwise save before a subsequent call.

// e.g., BRL-CAD_123_456
const char *generic = bu_temp_file_name(NULL, 0);
 
// e.g., BRL-CAD_123_456 -> saved to supplied buffer
char generic[25] = {0};
bu_temp_file_name(generic, 25);
 
// e.g., prefix_123_456
const char *prefix = bu_temp_file_name("prefix", 0);
 
// e.g., prefix_123_456 -> saved to supplied buffer
char prefix[25] = "prefix";
bu_temp_file_name(prefix, 25);
 
// e.g., /path/to/temp/dir/BRL-CAD_123_456 -> combine with bu_dir for fullpath
char tmpfil[MAXPATHLEN];
const char* tmp_filename = bu_temp_file_name(NULL, 0);
bu_dir(tmpfil, MAXPATHLEN, BU_DIR_TEMP, tmp_filename, NULL);

bu_fchmod()

int bu_fchmod ( int  fd, unsigned long  pmode  )

extern

Wrapper around fchmod.

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

bu_dir()

const char * bu_dir ( char *  result, size_t  len,   ...  )

extern

Find a particular user, system, or runtime directory.

This function writes into buffer and returns, if found, the path to a given filesystm resource. The caller may specify paths to subdirectories and/or filenames as a NULL-terminated vararg list.

Paths returned will use the native directory separator. Callers may also manually concatenate subdirectory resources (e.g., "share/db/moss.g") using forward slashes and they will be converted to the native separator.

Parameters

result	if non-NULL, buffer should have >= MAXPATHLEN chars
len	is the size of the result buffer
...	must be one of the above enumerations or a string/path

Returns

Full path to the specified resource will be returned. This will be 'buffer' or, when NULL, a read-only STATIC buffer will be returned that will be the caller's responsibility to bu_strdup() or otherwise save before a subsequent call to bu_dir() returns.

// e.g., /home/user
const char *pwd = bu_dir(NULL, 0, BU_DIR_CURR, NULL);
 
// e.g., /opt/brlcad/bin/rt
char rt[MAXPATHLEN] = {0};
bu_dir(rt, MAXPATHLEN, BU_DIR_BIN, "rt", BU_DIR_EXT, NULL);
execl(rt, "rt", NULL);
 
// e.g., C:\\BRL-CAD 7.123.4\\bin\\librt.dll
const char *lib = bu_dir(NULL, 0, BU_DIR_LIB, "librt", BU_DIR_LIBEXT, NULL);
 
// e.g., /opt/app-7.123.4/share/tclscripts/mged/help.tcl
char ts[MAXPATHLEN] = {0};
bu_dir(ts, MAXPATHLEN, BU_DIR_DATA, "tclscripts/mged", NULL);
bu_dir(ts, MAXPATHLEN, ts, "help.tcl", NULL);
 
// e.g., C:\\BRL-CAD 7.123.4\\libexec\\mged\\tops.exe
const char *tops = bu_dir(NULL, 0, BU_DIR_LIBEXEC, "mged/tops", BU_DIR_EXT, NULL);

bu_mkdir()

void bu_mkdir ( const char *  path )

extern

Create a directory specified by the string "path". Default mode on platforms using mkdir will be "775"

bu_dirclear()

void bu_dirclear ( const char *  d )

extern

Recursively delete all files and subfolders in directory d