Tool front-end API. Use these functions to search for and query the properties of a target application file, check environment variables, and perform other common actions in a tool front-end executable. The library provides cross-platform utilities that support internationalization. More...

#include <tchar.h>

Enumerations
enum	drfront_status_t { DRFRONT_SUCCESS, DRFRONT_ERROR, DRFRONT_ERROR_INVALID_PARAMETER, DRFRONT_ERROR_INVALID_SIZE, DRFRONT_ERROR_FILE_EXISTS, DRFRONT_ERROR_INVALID_PATH, DRFRONT_ERROR_ACCESS_DENIED, DRFRONT_ERROR_LIB_UNSUPPORTED }

enum	drfront_access_mode_t { DRFRONT_EXIST = 0x00, DRFRONT_EXEC = 0x01, DRFRONT_WRITE = 0x02, DRFRONT_READ = 0x04 }

Functions
drfront_status_t	drfront_access (const char fname, drfront_access_mode_t mode, OUT bool ret)

drfront_status_t	drfront_searchenv (const char fname, const char env_var, OUT char full_path, const size_t full_path_size, OUT bool ret)

drfront_status_t	drfront_bufprint (INOUT char buf, size_t bufsz, INOUT size_t sofar, OUT ssize_t len, const char fmt,...)

drfront_status_t	drfront_tchar_to_char (const TCHAR wstr, OUT char buf, size_t buflen)

drfront_status_t	drfront_tchar_to_char_size_needed (const TCHAR wstr, OUT size_t needed)

drfront_status_t	drfront_char_to_tchar (const char str, OUT TCHAR wbuf, size_t wbuflen)

drfront_status_t	drfront_get_env_var (const char name, OUT char buf, size_t buflen)

drfront_status_t	drfront_get_absolute_path (const char src, OUT char buf, size_t buflen)

drfront_status_t	drfront_get_app_full_path (const char app, OUT char buf, size_t buflen)

drfront_status_t	drfront_is_64bit_app (const char exe, OUT bool is_64, OUT bool *also_32)

drfront_status_t	drfront_is_graphical_app (const char exe, OUT bool is_graphical)

drfront_status_t	drfront_convert_args (const TCHAR targv, OUT char *argv, int argc)

drfront_status_t	drfront_cleanup_args (char **argv, int argc)

drfront_status_t	drfront_appdata_logdir (const char root, const char subdir, OUT bool use_root, OUT char buf, size_t buflen)

void	drfront_string_replace_character (OUT char *str, char old_char, char new_char)

void	drfront_string_replace_character_wide (OUT TCHAR *str, TCHAR old_char, TCHAR new_char)

drfront_status_t	drfront_set_client_symbol_search_path (const char symdir, bool ignore_env, OUT char symsrv_path, size_t symsrv_path_sz)

drfront_status_t	drfront_set_symbol_search_path (const char *symsrv_path)

drfront_status_t	drfront_sym_init (const char wsymsrv_path, const char dbghelp_path)

drfront_status_t	drfront_sym_exit (void)

drfront_status_t	drfront_fetch_module_symbols (const char modpath, OUT char symbol_path, size_t symbol_path_sz)

drfront_status_t	drfront_create_dir (const char *dir)

drfront_status_t	drfront_remove_dir (const char *dir)

drfront_status_t	drfront_dir_exists (const char path, OUT bool is_dir)

drfront_status_t	drfront_dir_try_writable (const char path, OUT bool is_writable)

Detailed Description

Tool front-end API. Use these functions to search for and query the properties of a target application file, check environment variables, and perform other common actions in a tool front-end executable. The library provides cross-platform utilities that support internationalization.

The general usage model is for the front-end executable to always deal with UTF-8 strings and let this front-end library perform conversion back and forth to UTF-16 when interacting with Windows library. The executable should declare its main routine as follows:

int _tmain(int argc, TCHAR *targv[])

And then invoke drfront_convert_args() to convert them to UTF-8. All further references to the arguments should use the UTF-8 versions. On Linux or MacOS, _tmain and TCHAR will turn into regular symbols.

Enumeration Type Documentation

◆ drfront_access_mode_t

enum drfront_access_mode_t

Permission modes for drfront_access()

Enumerator
DRFRONT_EXIST	Test existence
DRFRONT_EXEC	Test for execute access
DRFRONT_WRITE	Test for write access
DRFRONT_READ	Test for read access

◆ drfront_status_t

enum drfront_status_t

Status code for each DRFront operation

Enumerator
DRFRONT_SUCCESS	Operation succeeded
DRFRONT_ERROR	Operation failed
DRFRONT_ERROR_INVALID_PARAMETER	Operation failed: invalid parameter
DRFRONT_ERROR_INVALID_SIZE	Operation failed: invalid size
DRFRONT_ERROR_FILE_EXISTS	Operation failed: dir or file already exists
DRFRONT_ERROR_INVALID_PATH	Operation failed: wrong path
DRFRONT_ERROR_ACCESS_DENIED	Operation failed: access denied
DRFRONT_ERROR_LIB_UNSUPPORTED	Operation failed: old version or invalid library

Function Documentation

◆ drfront_access()

drfront_status_t drfront_access	(	const char *	fname,
		drfront_access_mode_t	mode,
		OUT bool *	ret
	)

Checks fname for the permssions specified by mode for the current effective user. If fname is a directory and mode includes DRFRONT_WRITE, this function additionally attempts to create a temporary file (by calling drfront_dir_try_writable()) to ensure that the filesystem is not mounted read-only. On Linux or Mac, if the current effective user is 0, this routine assumes that the user has read and write access to every file and has execute access to any file with at least one execute bit set.

Note: DRFRONT_EXEC is ignored on Windows because _waccess doesn't test it.

Parameters

[in]	fname	The filename to test permission to.
[in]	mode	The permission to test the file for.
[out]	ret	True iff `fname` has the permission specified by `mode`.

◆ drfront_appdata_logdir()

drfront_status_t drfront_appdata_logdir	(	const char *	root,
		const char *	subdir,
		OUT bool *	use_root,
		OUT char *	buf,
		size_t	buflen
	)

If a tool is installed into a "Program Files" directory on Windows, or into "/usr/..." on Linux, it needs to store its log files elsewhere. This utility function helps to select that alternative location. First, it checks whether root is in a location where log files should not be created, and returns that result in use_root. If use_root is false, this function returns a suggested alternative directory for log files in buf. It looks in standard locations such as "$APPDATA" or "$USERPROFILE/Application Data" on Windows or in temp directories if those fail or if on Linux. It appends subdir to the base application data or temp directory. It is up to the caller to create the returned directory if it does not exist.

Parameters

[in]	root	The location where the tool's binaries are installed.
[in]	subdir	A directory to append to the application data directory to form a result in `buf`.
[out]	use_root	Returns whether `root` is suitable for storing log files.
[out]	buf	If `use_root` is false, this buffer is filled with a suggested directory for storing log files. The directory ends with `subdir`. If `use_root` is true, `buf's` contents are undefined.
[in]	buflen	The maximum capacity of `buf`, in elements.

◆ drfront_bufprint()

drfront_status_t drfront_bufprint	(	INOUT char *	buf,
		size_t	bufsz,
		INOUT size_t *	sofar,
		OUT ssize_t *	len,
		const char *	fmt,
			...
	)

Concatenate onto a buffer. The buffer is not resized if the content does not fit.

Parameters

[in,out]	buf	The buffer to concatenate onto.
[in]	bufsz	The allocated size of `buf`.
[in,out]	sofar	The number of bytes added so far. Cumulative between calls.
[out]	len	The number of bytes sucessfully written to `buf` this call.
[in]	fmt	The format string to be added to `buf`.
[in]	...	Any data needed for the format string.

◆ drfront_char_to_tchar()

drfront_status_t drfront_char_to_tchar	(	const char *	str,
		OUT TCHAR *	wbuf,
		size_t	wbuflen
	)

Converts from UTF-8 to UTF-16.

Note: On UNIX the information is simply copied from str to wbuf.; Always null-terminates.

Parameters

[in]	str	The UTF-8 string to be converted to UTF-16.
[out]	wbuf	The destination of the new UTF-16 string.
[in]	wbuflen	The allocated size of `wbuf` in elements.

◆ drfront_cleanup_args()

drfront_status_t drfront_cleanup_args	(	char **	argv,
		int	argc
	)

Frees the UTF-8 array of command-line arguments.

Parameters

[in]	argv	The array of command-line arguments.
[in]	argc	The number of command-line arguments.

◆ drfront_convert_args()

drfront_status_t drfront_convert_args	(	const TCHAR **	targv,
		OUT char ***	argv,
		int	argc
	)

Converts the command-line arguments to UTF-8.

Note: This function allocates memory on the heap that must be freed by calling drfront_cleanup_args().; On UNIX the data is simply copied.

Parameters

[in]	targv	The original command-line arguments.
[out]	argv	The original command-line arguments in UTF-8.
[in]	argc	The number of command-line arguments.

◆ drfront_create_dir()

drfront_status_t drfront_create_dir ( const char * dir )

This routine creates the directory specified in dir.

Parameters

[in] dir New directory name.

◆ drfront_dir_exists()

drfront_status_t drfront_dir_exists	(	const char *	path,
		OUT bool *	is_dir
	)

This routine checks whether path is a valid directory.

Parameters

[in]	path	The path to be checked
[out]	is_dir	Returns whether `path` is a valid directory.

◆ drfront_dir_try_writable()

drfront_status_t drfront_dir_try_writable	(	const char *	path,
		OUT bool *	is_writable
	)

This routine checks whether a file can be created inside the directory specified by path.

Parameters

[in]	path	The path to be checked
[out]	is_writable	Returns whether files can be created in `path`.

◆ drfront_fetch_module_symbols()

drfront_status_t drfront_fetch_module_symbols	(	const char *	modpath,
		OUT char *	symbol_path,
		size_t	symbol_path_sz
	)

This routine tries to fetch all missed symbols for module specified in modpath using _NT_SYMBOL_PATH environment var. User should call drfront_sym_init, drfront_sym_set_search_path() and drfront_sym_set_search_path() before calling this routine. If success function returns full path to fetched symbol file in symbol_path.

Note: The routine will fetch symbols from remote MS Symbol Server only if symbols don't exist in the search paths and _NT_SYMBOL_PATH has right srv* path & link. The routine requires DbgHelp.dll 6.0 or later.

Warning: The routine will fail when using the system copy of dbghelp.dll on Windows XP or 2003. The client should use its own copy of dbghelp.dll version 6.0 or later.

Parameters

[in]	modpath	The name of the image to be loaded. This name can contain a partial path, a full path, or no path at all. If the file cannot be located by the name provided, the routine returns DRFRONT_OBJ_NOEXIST.
[in]	symbol_path	The full path to fetched symbols file.
[in]	symbol_path_sz	Size of `symbol_path` argument in characters.

◆ drfront_get_absolute_path()

drfront_status_t drfront_get_absolute_path	(	const char *	src,
		OUT char *	buf,
		size_t	buflen
	)

Gets the absolute path of src.

Parameters

[in]	src	The path to expand.
[out]	buf	The buffer to place the absolute path in.
[in]	buflen	The allocated size of `buf` in elements.

◆ drfront_get_app_full_path()

drfront_status_t drfront_get_app_full_path	(	const char *	app,
		OUT char *	buf,
		size_t	buflen
	)

Gets the full path of app, which is located by searching the PATH if necessary.

Parameters

[in]	app	The executable to get the full path of.
[out]	buf	The buffer to place the full path in if found.
[in]	buflen	The allocated size of `buf` in elements.

◆ drfront_get_env_var()

drfront_status_t drfront_get_env_var	(	const char *	name,
		OUT char *	buf,
		size_t	buflen
	)

Stores the contents of the environment variable name in buf.

Parameters

[in]	name	The name of the environment variable.
[out]	buf	The destination to store the contents of `name`.
[in]	buflen	The allocated size of `buf` in elements.

◆ drfront_is_64bit_app()

drfront_status_t drfront_is_64bit_app	(	const char *	exe,
		OUT bool *	is_64,
		OUT bool *	also_32
	)

Reads the file header to determine if exe is a 64-bit application.

Parameters

[in]	exe	The executable to check for the 64-bit flag.
[out]	is_64	True if `exe` is a 64-bit application.
[out]	also_32	True if `exe` is a multi-part binary that also contains a 32-bit application.

◆ drfront_is_graphical_app()

drfront_status_t drfront_is_graphical_app	(	const char *	exe,
		OUT bool *	is_graphical
	)

Reads the PE header to determine if exe has a GUI.

Note: This function always returns false on UNIX because it is not relevant.

Parameters

[in]	exe	The executable to check the subsystem of.
[out]	is_graphical	True if `exe's` subsystem is graphical.

◆ drfront_remove_dir()

drfront_status_t drfront_remove_dir ( const char * dir )

This routine removes the empty directory specified in dir.

Parameters

[in] dir Name of directory to remove.

◆ drfront_searchenv()

drfront_status_t drfront_searchenv	(	const char *	fname,
		const char *	env_var,
		OUT char *	full_path,
		const size_t	full_path_size,
		OUT bool *	ret
	)

Implements a normal path search for fname on the paths in env_var. Resolves symlinks.

Parameters

[in]	fname	The filename to search for.
[in]	env_var	The environment variable that contains the paths to search for `fname`. Paths are ;-separated on Windows and :-separated on UNIX.
[out]	full_path	The full path of `fname` if it is found.
[in]	full_path_size	The maximum size of `full_path`.
[out]	ret	True iff `fname` is found.

◆ drfront_set_client_symbol_search_path()

drfront_status_t drfront_set_client_symbol_search_path	(	const char *	symdir,
		bool	ignore_env,
		OUT char *	symsrv_path,
		size_t	symsrv_path_sz
	)

Sets the environment variable _NT_SYMBOL_PATH and the dbghelp search path for symbol lookup in a client, without any network symbol server component (such components are unsafe in a client).

If the _NT_SYMBOL_PATH is already specified, this routine validates it and if invalid replaces it.

This routine also takes the client symbol lookup path and adds the Microsoft symbol server for use in a frontend itself (not in a client) and returns that path in symsrv_path. The frontend can enable use of this path by calling drfront_set_symbol_search_path().

drfront_sym_init() must be called before calling this routine.

Note: This routine requires DbgHelp.dll 6.0 or later.

Warning: This routine will fail when using the system copy of dbghelp.dll on Windows XP or 2003. The client should use its own copy of dbghelp.dll version 6.0 or later.

Parameters

[in]	symdir	A local symbol cache directory. It can be passed without srv* prepended. It will have "/symbols" appended to it.
[in]	ignore_env	If TRUE, any existing _NT_SYMBOL_PATH value is ignored.
[out]	symsrv_path	Returns a symbol path that includes the Microsoft symbol server.
[in]	symsrv_path_sz	The maximum length, in characters, of `symsrv_path`.

◆ drfront_set_symbol_search_path()

drfront_status_t drfront_set_symbol_search_path ( const char * symsrv_path )

Sets the symbol search path for this frontend process to the specified value. Typically this would be used with the output value from drfront_set_client_symbol_search_path().

drfront_sym_init() must be called before calling this routine.

Note: The routine requires DbgHelp.dll 6.0 or later.

Warning: The routine will fail when using the system copy of dbghelp.dll on Windows XP or 2003. The client should use its own copy of dbghelp.dll version 6.0 or later.

Parameters

[in] symsrv_path The symbol search path to use.

◆ drfront_string_replace_character()

void drfront_string_replace_character	(	OUT char *	str,
		char	old_char,
		char	new_char
	)

Replace occurences of old_char with new_char in str. Typically used to canonicalize Windows paths into using forward slashes.

Parameters

[out]	str	The string whose characters should be replaced.
[in]	old_char	Old character to be replaced.
[in]	new_char	New character to use.

◆ drfront_string_replace_character_wide()

void drfront_string_replace_character_wide	(	OUT TCHAR *	str,
		TCHAR	old_char,
		TCHAR	new_char
	)

Replace occurences of old_char with new_char in TCHAR str. Typically used to canonicalize Windows paths into using forward slashes.

Parameters

[out]	str	A string whose characters should be replaced.
[in]	old_char	Old character to be replaced.
[in]	new_char	New character to use.

◆ drfront_sym_exit()

drfront_status_t drfront_sym_exit ( void )

This routine deallocates all symbol-related resources associated with the current process.

◆ drfront_sym_init()

drfront_status_t drfront_sym_init	(	const char *	wsymsrv_path,
		const char *	dbghelp_path
	)

This routine initializes the symbol handler for the current process. Should be called before drfront_set_symbol_search_path() and drfront_fetch_module_symbols().

Note: The routine requires DbgHelp.dll 6.0 or later.

Warning: The routine will fail when using the system copy of dbghelp.dll on Windows XP or 2003. The client should use its own copy of dbghelp.dll version 6.0 or later.

Parameters

[in]	wsymsrv_path	The path, or series of paths separated by a semicolon (;), that is used to search for symbol files. If this parameter is NULL, the library attempts to form a symbol path from the following sources: the current working directory, _NT_SYMBOL_PATH, _NT_ALTERNATE_SYMBOL_PATH.
[in]	dbghelp_path	The path to dbghelp.dll. If the string specifies a full path, the routine looks only in that path for the module. If the string specifies a relative path or a module name without a path, the function uses a standard Windows library search strategy to find the module.

◆ drfront_tchar_to_char()

drfront_status_t drfront_tchar_to_char	(	const TCHAR *	wstr,
		OUT char *	buf,
		size_t	buflen
	)

Converts from UTF-16 to UTF-8.

Note: On UNIX the information is simply copied from wstr to buf.; Always null-terminates.

Parameters

[in]	wstr	The UTF-16 string to be converted to UTF-8.
[out]	buf	The destination of the new UTF-8 string.
[in]	buflen	The allocated size of `buf` in elements.

◆ drfront_tchar_to_char_size_needed()

drfront_status_t drfront_tchar_to_char_size_needed	(	const TCHAR *	wstr,
		OUT size_t *	needed
	)

Gets the necessary size of a UTF-8 buffer to hold the content in wstr.

Note: needed includes the terminating null character.

Parameters

[in]	wstr	The UTF-16 string to be converted later.
[out]	needed	The size a buffer has to be to hold `wstr` in UTF-8.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ drfront_access_mode_t

◆ drfront_status_t

Function Documentation

◆ drfront_access()

◆ drfront_appdata_logdir()

◆ drfront_bufprint()

◆ drfront_char_to_tchar()

◆ drfront_cleanup_args()

◆ drfront_convert_args()

◆ drfront_create_dir()

◆ drfront_dir_exists()

◆ drfront_dir_try_writable()

◆ drfront_fetch_module_symbols()

◆ drfront_get_absolute_path()

◆ drfront_get_app_full_path()

◆ drfront_get_env_var()

◆ drfront_is_64bit_app()

◆ drfront_is_graphical_app()

◆ drfront_remove_dir()

◆ drfront_searchenv()

◆ drfront_set_client_symbol_search_path()

◆ drfront_set_symbol_search_path()

◆ drfront_string_replace_character()

◆ drfront_string_replace_character_wide()

◆ drfront_sym_exit()

◆ drfront_sym_init()

◆ drfront_tchar_to_char()

◆ drfront_tchar_to_char_size_needed()