DynamoRIO API
dr_frontend.h File Reference

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, 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

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

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_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]fnameThe filename to test permission to.
[in]modeThe permission to test the file for.
[out]retTrue iff fname has the permission specified by mode.
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]rootThe location where the tool's binaries are installed.
[in]subdirA directory to append to the application data directory to form a result in buf.
[out]use_rootReturns whether root is suitable for storing log files.
[out]bufIf 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]buflenThe maximum capacity of buf, in elements.
drfront_status_t drfront_bufprint ( INOUT char *  buf,
size_t  bufsz,
INOUT size_t *  sofar,
OUT ssize_t *  len,
char *  fmt,
  ... 
)

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

Parameters
[in,out]bufThe buffer to concatenate onto.
[in]bufszThe allocated size of buf.
[in,out]sofarThe number of bytes added so far. Cumulative between calls.
[out]lenThe number of bytes sucessfully written to buf this call.
[in]fmtThe format string to be added to buf.
[in]...Any data needed for the format string.
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]strThe UTF-8 string to be converted to UTF-16.
[out]wbufThe destination of the new UTF-16 string.
[in]wbuflenThe allocated size of wbuf in elements.
drfront_status_t drfront_cleanup_args ( char **  argv,
int  argc 
)

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

Parameters
[in]argvThe array of command-line arguments.
[in]argcThe number of command-line arguments.
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]targvThe original command-line arguments.
[out]argvThe original command-line arguments in UTF-8.
[in]argcThe number of command-line arguments.
drfront_status_t drfront_create_dir ( const char *  dir)

This routine creates the directory specified in dir.

Parameters
[in]dirNew directory name.
drfront_status_t drfront_dir_exists ( const char *  path,
OUT bool *  is_dir 
)

This routine checks whether path is a valid directory.

Parameters
[in]pathThe path to be checked
[out]is_dirReturns whether path is a valid directory.
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]pathThe path to be checked
[out]is_writableReturns whether files can be created in path.
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]modpathThe 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_pathThe full path to fetched symbols file.
[in]symbol_path_szSize of symbol_path argument in characters.
drfront_status_t drfront_get_absolute_path ( const char *  src,
OUT char *  buf,
size_t  buflen 
)

Gets the absolute path of src.

Parameters
[in]srcThe path to expand.
[out]bufThe buffer to place the absolute path in.
[in]buflenThe allocated size of buf in elements.
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]appThe executable to get the full path of.
[out]bufThe buffer to place the full path in if found.
[in]buflenThe allocated size of buf in elements.
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]nameThe name of the environment variable.
[out]bufThe destination to store the contents of name.
[in]buflenThe allocated size of buf in elements.
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]exeThe executable to check for the 64-bit flag.
[out]is_64True if exe is a 64-bit application.
[out]also_32True if exe is a multi-part binary that also contains a 32-bit application.
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]exeThe executable to check the subsystem of.
[out]is_graphicalTrue if exe's subsystem is graphical.
drfront_status_t drfront_remove_dir ( const char *  dir)

This routine removes the empty directory specified in dir.

Parameters
[in]dirName of directory to remove.
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]fnameThe filename to search for.
[in]env_varThe environment variable that contains the paths to search for fname. Paths are ;-separated on Windows and :-separated on UNIX.
[out]full_pathThe full path of fname if it is found.
[in]full_path_sizeThe maximum size of full_path.
[out]retTrue iff fname is found.
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]symdirA local symbol cache directory. It can be passed without srv* prepended. It will have "/symbols" appended to it.
[in]ignore_envIf TRUE, any existing _NT_SYMBOL_PATH value is ignored.
[out]symsrv_pathReturns a symbol path that includes the Microsoft symbol server.
[in]symsrv_path_szThe maximum length, in characters, of symsrv_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_pathThe symbol search path to use.
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]strThe string whose characters should be replaced.
[in]old_charOld character to be replaced.
[in]new_charNew character to use.
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]strA string whose characters should be replaced.
[in]old_charOld character to be replaced.
[in]new_charNew character to use.
drfront_status_t drfront_sym_exit ( void  )

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

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_pathThe 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_pathThe 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_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]wstrThe UTF-16 string to be converted to UTF-8.
[out]bufThe destination of the new UTF-8 string.
[in]buflenThe allocated size of buf in elements.
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]wstrThe UTF-16 string to be converted later.
[out]neededThe size a buffer has to be to hold wstr in UTF-8.