All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
System Functions

Functions that encapsulate differing low-level system calls. More...

Files

file  errno.h
 Functions for dealing with system errors.
 
file  fileSystem.h
 Architecture dependent file system access.
 
file  fileSystem.h
 Architecture dependent file system access.
 
file  fileSystem.h
 Architecture dependent file system access.
 
file  systemInfo.h
 Provide architecture-specific system information.
 
file  timing.h
 High-resolution, low-cost timing routines.
 
file  virtualMemory.h
 Architecture dependent routines for virtual memory.
 

Macros

#define ARCH_GLOB_NOCHECK   GLOB_NOCHECK
 
#define ARCH_GLOB_MARK   GLOB_MARK
 
#define ARCH_GLOB_NOSORT   GLOB_NOSORT
 
#define ARCH_GLOB_DEFAULT   (ARCH_GLOB_NOCHECK | ARCH_GLOB_MARK)
 
#define ARCH_PATH_MAX   1024
 
#define ARCH_PATH_SEP   "/"
 
#define ARCH_PATH_LIST_SEP   ":"
 
#define ARCH_REL_PATH_IDENT   "./"
 
#define ArchChmod(path, mode)   chmod(path, mode)
 
#define ArchCloseFile(fd)   close(fd)
 
#define ArchUnlinkFile(path)   unlink(path)
 
#define ArchFileAccess(path, mode)   access(path, mode)
 
#define ArchFdOpen(fd, mode)   fdopen(fd, mode)
 
#define ArchFileNo(stream)   fileno(stream)
 
#define ArchFileIsaTTY(stream)   isatty(stream)
 
#define ArchRmDir(path)   rmdir(path)
 
#define ARCH_CLK_TCK   100
 Macro that defines the clocks per second. More...
 

Typedefs

typedef struct stat ArchStatType
 
using ArchConstFileMapping = std::unique_ptr< char const, Arch_Unmapper >
 ArchConstFileMapping and ArchMutableFileMapping are std::unique_ptr<char const *, ...> and std::unique_ptr<char *, ...> respectively. More...
 
using ArchMutableFileMapping = std::unique_ptr< char, Arch_Unmapper >
 

Enumerations

enum  ArchMemAdvice { ArchMemAdviceNormal, ArchMemAdviceWillNeed, ArchMemAdviceDontNeed, ArchMemAdviceRandomAccess }
 
enum  ArchFileAdvice { ArchFileAdviceNormal, ArchFileAdviceWillNeed, ArchFileAdviceDontNeed, ArchFileAdviceRandomAccess }
 

Functions

ARCH_API bool ArchHasEnv (const std::string &name)
 Architecture dependent access to environment variables. More...
 
ARCH_API std::string ArchGetEnv (const std::string &name)
 Gets a value from the current environment identified by name. More...
 
ARCH_API bool ArchSetEnv (const std::string &name, const std::string &value, bool overwrite)
 Creates or modifies an environment variable. More...
 
ARCH_API bool ArchRemoveEnv (const std::string &name)
 Removes an environment variable. More...
 
ARCH_API std::string ArchExpandEnvironmentVariables (const std::string &str)
 Expands environment variables in str. More...
 
ARCH_API char ** ArchEnviron ()
 Return an array of the environment variables. More...
 
ARCH_API std::string ArchStrerror ()
 Return the error string for the current value of errno. More...
 
ARCH_API std::string ArchStrerror (int errorCode)
 Return the error string for the specified value of errno. More...
 
ARCH_API FILE * ArchOpenFile (char const *fileName, char const *mode)
 Opens a file. More...
 
ARCH_API int64_t ArchGetFileLength (const char *fileName)
 Return the length of a file in bytes. More...
 
ARCH_API int64_t ArchGetFileLength (FILE *file)
 
ARCH_API std::string ArchGetFileName (FILE *file)
 Return a filename for this file, if one can be obtained. More...
 
ARCH_API bool ArchStatIsWritable (const ArchStatType *st)
 Returns true if the data in stat struct st indicates that the target file or directory is writable. More...
 
ARCH_API bool ArchGetModificationTime (const char *pathname, double *time)
 Returns the modification time (mtime) in seconds for a file. More...
 
ARCH_API double ArchGetModificationTime (const ArchStatType &st)
 Returns the modification time (mtime) in seconds from the stat struct. More...
 
ARCH_API std::string ArchNormPath (const std::string &path, bool stripDriveSpecifier=false)
 Normalizes the specified path, eliminating double slashes, etc. More...
 
ARCH_API std::string ArchAbsPath (const std::string &path)
 Returns the canonical absolute path of the specified filename. More...
 
ARCH_API bool ArchGetStatMode (const char *pathname, int *mode)
 Returns the permissions mode (mode_t) for the given pathname. More...
 
ARCH_API const char * ArchGetTmpDir ()
 Return the path to a temporary directory for this platform. More...
 
ARCH_API std::string ArchMakeTmpFileName (const std::string &prefix, const std::string &suffix=std::string())
 Make a temporary file name, in a system-determined temporary directory. More...
 
ARCH_API int ArchMakeTmpFile (const std::string &prefix, std::string *pathname=0)
 Create a temporary file, in a system-determined temporary directory. More...
 
ARCH_API int ArchMakeTmpFile (const std::string &tmpdir, const std::string &prefix, std::string *pathname=0)
 Create a temporary file, in a given temporary directory. More...
 
ARCH_API std::string ArchMakeTmpSubdir (const std::string &tmpdir, const std::string &prefix)
 Create a temporary sub-direcrory, in a given temporary directory. More...
 
size_t ArchGetFileMappingLength (ArchConstFileMapping const &m)
 Return the length of an ArchConstFileMapping. More...
 
size_t ArchGetFileMappingLength (ArchMutableFileMapping const &m)
 Return the length of an ArchMutableFileMapping. More...
 
ARCH_API ArchConstFileMapping ArchMapFileReadOnly (FILE *file, std::string *errMsg=nullptr)
 Privately map the passed file into memory and return a unique_ptr to the read-only mapped contents. More...
 
ARCH_API ArchConstFileMapping ArchMapFileReadOnly (std::string const &path, std::string *errMsg=nullptr)
 
ARCH_API ArchMutableFileMapping ArchMapFileReadWrite (FILE *file, std::string *errMsg=nullptr)
 Privately map the passed file into memory and return a unique_ptr to the copy-on-write mapped contents. More...
 
ARCH_API ArchMutableFileMapping ArchMapFileReadWrite (std::string const &path, std::string *errMsg=nullptr)
 
ARCH_API void ArchMemAdvise (void const *addr, size_t len, ArchMemAdvice adv)
 Advise the OS regarding how the application intends to access a range of memory. More...
 
ARCH_API bool ArchQueryMappedMemoryResidency (void const *addr, size_t len, unsigned char *pageMap)
 Report whether or not the mapped virtual memory pages starting at addr for len bytes are resident in RAM. More...
 
ARCH_API int64_t ArchPRead (FILE *file, void *buffer, size_t count, int64_t offset)
 Read up to count bytes from offset in file into buffer. More...
 
ARCH_API int64_t ArchPWrite (FILE *file, void const *bytes, size_t count, int64_t offset)
 Write up to count bytes from buffer to file at offset. More...
 
ARCH_API std::string ArchReadLink (const char *path)
 Returns the value of the symbolic link at path. More...
 
ARCH_API void ArchFileAdvise (FILE *file, int64_t offset, size_t count, ArchFileAdvice adv)
 Advise the OS regarding how the application intends to access a range of bytes in a file. More...
 
ARCH_API void * ArchLibraryOpen (const std::string &filename, int flag)
 library.h Architecture dependent loading and unloading of dynamic libraries. More...
 
ARCH_API std::string ArchLibraryError ()
 Obtain a description of the most recent error that occurred from ArchLibraryOpen. More...
 
ARCH_API int ArchLibraryClose (void *handle)
 Closes an object opened with ArchLibraryOpen. More...
 
ARCH_API void * ArchLibraryGetSymbolAddress (void *handle, const char *name)
 Obtain the address of a symbol defined within an object opened with ArchLibraryOpen. More...
 
ARCH_API std::string ArchGetCwd ()
 Return current working directory as a string. More...
 
ARCH_API std::string ArchGetExecutablePath ()
 Return the path to the program's executable. More...
 
ARCH_API int ArchGetPageSize ()
 Return the system's memory page size. Safe to assume power-of-two. More...
 
uint64_t ArchGetTickTime ()
 Return the current time in system-dependent units. More...
 
ARCH_API int64_t ArchTicksToNanoseconds (uint64_t nTicks)
 Convert a duration measured in "ticks", as returned by ArchGetTickTime(), to nanoseconds. More...
 
ARCH_API double ArchTicksToSeconds (uint64_t nTicks)
 Convert a duration measured in "ticks", as returned by ArchGetTickTime(), to seconds. More...
 
ARCH_API uint64_t ArchSecondsToTicks (double seconds)
 Convert a duration in seconds to "ticks", as returned by ArchGetTickTime(). More...
 
ARCH_API double ArchGetNanosecondsPerTick ()
 Get nanoseconds per tick. More...
 

Detailed Description

Functions that encapsulate differing low-level system calls.

Macro Definition Documentation

#define ARCH_CLK_TCK   100

Macro that defines the clocks per second.

Unfortunately, Red Hat 7.1 does not define CLK_TCK correctly, so ARCH_CLK_TCK is the only guaranteed way to get the value of CLK_TCK. The value is currently the same on all of our platforms.

Definition at line 54 of file timing.h.

Typedef Documentation

using ArchConstFileMapping = std::unique_ptr<char const, Arch_Unmapper>

ArchConstFileMapping and ArchMutableFileMapping are std::unique_ptr<char const *, ...> and std::unique_ptr<char *, ...> respectively.

The functions ArchMapFileReadOnly() and ArchMapFileReadWrite() return them and provide access to memory-mapped file contents.

Definition at line 316 of file fileSystem.h.

Function Documentation

ARCH_API std::string ArchAbsPath ( const std::string &  path)

Returns the canonical absolute path of the specified filename.

This makes the specified path absolute, by prepending the current working directory. If the path is already absolute, it is returned unmodified.

ARCH_API char** ArchEnviron ( )

Return an array of the environment variables.

ARCH_API std::string ArchExpandEnvironmentVariables ( const std::string &  str)

Expands environment variables in str.

ARCH_API void ArchFileAdvise ( FILE *  file,
int64_t  offset,
size_t  count,
ArchFileAdvice  adv 
)

Advise the OS regarding how the application intends to access a range of bytes in a file.

See ArchFileAdvice. This call does not change program semantics. It is only an optimization hint to the OS, and may be a no-op on some systems.

ARCH_API std::string ArchGetCwd ( )

Return current working directory as a string.

ARCH_API std::string ArchGetEnv ( const std::string &  name)

Gets a value from the current environment identified by name.

ARCH_API std::string ArchGetExecutablePath ( )

Return the path to the program's executable.

ARCH_API int64_t ArchGetFileLength ( const char *  fileName)

Return the length of a file in bytes.

Returns -1 if the file cannot be opened/read.

size_t ArchGetFileMappingLength ( ArchConstFileMapping const &  m)
inline

Return the length of an ArchConstFileMapping.

Definition at line 321 of file fileSystem.h.

size_t ArchGetFileMappingLength ( ArchMutableFileMapping const &  m)
inline

Return the length of an ArchMutableFileMapping.

Definition at line 327 of file fileSystem.h.

ARCH_API std::string ArchGetFileName ( FILE *  file)

Return a filename for this file, if one can be obtained.

ARCH_API bool ArchGetModificationTime ( const char *  pathname,
double *  time 
)

Returns the modification time (mtime) in seconds for a file.

This function stores the modification time with as much precision as is available in the stat structure for the current platform in time and returns true on success, otherwise just returns false.

ARCH_API double ArchGetModificationTime ( const ArchStatType &  st)

Returns the modification time (mtime) in seconds from the stat struct.

This function returns the modification time with as much precision as is available in the stat structure for the current platform.

ARCH_API double ArchGetNanosecondsPerTick ( )

Get nanoseconds per tick.

Useful when converting ticks obtained from ArchTickTime()

ARCH_API int ArchGetPageSize ( )

Return the system's memory page size. Safe to assume power-of-two.

ARCH_API bool ArchGetStatMode ( const char *  pathname,
int *  mode 
)

Returns the permissions mode (mode_t) for the given pathname.

This function stats the given pathname and returns the permissions flags for it and returns true. If the stat fails, returns false.

uint64_t ArchGetTickTime ( )
inline

Return the current time in system-dependent units.

The current time is returned as a number of "ticks", where each tick represents some system-dependent amount of time. The resolution of the timing routines varies, but on all systems, it is well under one microsecond. The cost of this routine is in the tens of nanoseconds on GHz class machines.

Definition at line 64 of file timing.h.

ARCH_API const char* ArchGetTmpDir ( )

Return the path to a temporary directory for this platform.

The returned temporary directory will be a location that will normally be cleaned out on a reboot. This is /var/tmp on Linux machines (for legacy reasons), but /tmp on Darwin machines (/var/tmp on Darwin is specified as a location where files are kept between system reboots - see "man hier"). The returned string will not have a trailing slash.

This routine is threadsafe and will not perform any memory allocations.

ARCH_API bool ArchHasEnv ( const std::string &  name)

Architecture dependent access to environment variables.

Returns true if and only if the current environment contains name.

ARCH_API int ArchLibraryClose ( void *  handle)

Closes an object opened with ArchLibraryOpen.

ARCH_API std::string ArchLibraryError ( )

Obtain a description of the most recent error that occurred from ArchLibraryOpen.

ARCH_API void* ArchLibraryGetSymbolAddress ( void *  handle,
const char *  name 
)

Obtain the address of a symbol defined within an object opened with ArchLibraryOpen.

Obtain the address of a symbol that is specified by name. Returning the address of the symbol if successful; nullptr otherwise.

ARCH_API void* ArchLibraryOpen ( const std::string &  filename,
int  flag 
)

library.h Architecture dependent loading and unloading of dynamic libraries.

Load an executable object file.

Opens the dynamic library that is specified by filename. Returning the handle to the module if successful; false otherwise.

ARCH_API int ArchMakeTmpFile ( const std::string &  prefix,
std::string *  pathname = 0 
)

Create a temporary file, in a system-determined temporary directory.

The result returned has the form TMPDIR/prefix.XXXXXX where TMPDIR is a system-determined temporary directory (typically /tmp or /usr/tmp) and XXXXXX is a unique suffix. Returns the file descriptor of the new file and, if pathname isn't NULL, returns the full path to the file in pathname. Returns -1 on failure and errno is set.

The call is threadsafe.

ARCH_API int ArchMakeTmpFile ( const std::string &  tmpdir,
const std::string &  prefix,
std::string *  pathname = 0 
)

Create a temporary file, in a given temporary directory.

The result returned has the form TMPDIR/prefix.XXXXXX where TMPDIR is the given temporary directory and XXXXXX is a unique suffix. Returns the file descriptor of the new file and, if pathname isn't NULL, returns the full path to the file in pathname. Returns -1 on failure and errno is set.

The call is threadsafe.

ARCH_API std::string ArchMakeTmpFileName ( const std::string &  prefix,
const std::string &  suffix = std::string() 
)

Make a temporary file name, in a system-determined temporary directory.

The result returned has the form TMPDIR/prefix.pid[.n]suffix where TMPDIR is a system-determined temporary directory (typically /tmp or /usr/tmp), pid is the process id of the process, and the optional .n records the number of times this function has been called by a process (and is ommited the first time this function is called).

The call is threadsafe.

Warning
This call opens a security hole because of the race between choosing the name and opening the file. This call should be avoided in favor of ArchMakeTmpFile().
ARCH_API std::string ArchMakeTmpSubdir ( const std::string &  tmpdir,
const std::string &  prefix 
)

Create a temporary sub-direcrory, in a given temporary directory.

The result returned has the form TMPDIR/prefix.XXXXXX/ where TMPDIR is the given temporary directory and XXXXXX is a unique suffix. Returns the the full path to the subdir in pathname. Returns empty string on failure and errno is set.

The call is threadsafe.

ARCH_API ArchConstFileMapping ArchMapFileReadOnly ( FILE *  file,
std::string *  errMsg = nullptr 
)

Privately map the passed file into memory and return a unique_ptr to the read-only mapped contents.

The contents may not be modified. If mapping fails, return a null unique_ptr and if errMsg is not null fill it with information about the failure.

ARCH_API ArchConstFileMapping ArchMapFileReadOnly ( std::string const &  path,
std::string *  errMsg = nullptr 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ARCH_API ArchMutableFileMapping ArchMapFileReadWrite ( FILE *  file,
std::string *  errMsg = nullptr 
)

Privately map the passed file into memory and return a unique_ptr to the copy-on-write mapped contents.

If modified, the affected pages are dissociated from the underlying file and become backed by the system's swap or page-file storage. Edits are not carried through to the underlying file. If mapping fails, return a null unique_ptr and if errMsg is not null fill it with information about the failure.

ARCH_API ArchMutableFileMapping ArchMapFileReadWrite ( std::string const &  path,
std::string *  errMsg = nullptr 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ARCH_API void ArchMemAdvise ( void const *  addr,
size_t  len,
ArchMemAdvice  adv 
)

Advise the OS regarding how the application intends to access a range of memory.

See ArchMemAdvice. This is primarily useful for mapped file regions. This call does not change program semantics. It is only an optimization hint to the OS, and may be a no-op on some systems.

ARCH_API std::string ArchNormPath ( const std::string &  path,
bool  stripDriveSpecifier = false 
)

Normalizes the specified path, eliminating double slashes, etc.

This canonicalizes paths, removing any double slashes, and eliminiating '.', and '..' components of the path. This emulates the behavior of os.path.normpath in Python.

On Windows, all backslashes are converted to forward slashes and drive specifiers (e.g., "C:") are lower-cased. If stripDriveSpecifier is true, these drive specifiers are removed from the path.

ARCH_API FILE* ArchOpenFile ( char const *  fileName,
char const *  mode 
)

Opens a file.

Opens the file that is specified by filename. Returning true if the file was opened successfully; false otherwise.

ARCH_API int64_t ArchPRead ( FILE *  file,
void *  buffer,
size_t  count,
int64_t  offset 
)

Read up to count bytes from offset in file into buffer.

The file position indicator for file is not changed. Return the number of bytes read, or zero if at end of file. Return -1 in case of an error, with errno set appropriately.

ARCH_API int64_t ArchPWrite ( FILE *  file,
void const *  bytes,
size_t  count,
int64_t  offset 
)

Write up to count bytes from buffer to file at offset.

The file position indicator for file is not changed. Return the number of bytes written, possibly zero if none written. Return -1 in case of an error, with errno set appropriately.

ARCH_API bool ArchQueryMappedMemoryResidency ( void const *  addr,
size_t  len,
unsigned char *  pageMap 
)

Report whether or not the mapped virtual memory pages starting at addr for len bytes are resident in RAM.

Pages that are resident will not, when accessed, cause a page fault while those that are not will. Return true on success and false in case of an error. The addr argument must be a multiple of ArchGetPageSize(). The len argument need not be a multiple of the page size; it will be rounded up to the next page boundary. Fill pageMap with 0s for pages not resident in memory and 1s for pages that are. The pageMap argument must therefore point to at least (len + ArchGetPageSize()-1)/ArchGetPageSize() bytes.

Note that currently this function is only implemented on Linux and Darwin. On Windows it currently always returns false.

ARCH_API std::string ArchReadLink ( const char *  path)

Returns the value of the symbolic link at path.

Returns the empty string on error or if path does not refer to a symbolic link.

ARCH_API bool ArchRemoveEnv ( const std::string &  name)

Removes an environment variable.

ARCH_API uint64_t ArchSecondsToTicks ( double  seconds)

Convert a duration in seconds to "ticks", as returned by ArchGetTickTime().

ARCH_API bool ArchSetEnv ( const std::string &  name,
const std::string &  value,
bool  overwrite 
)

Creates or modifies an environment variable.

ARCH_API bool ArchStatIsWritable ( const ArchStatType *  st)

Returns true if the data in stat struct st indicates that the target file or directory is writable.

This returns true if the struct pointer is valid, and the stat indicates the target is writable by the effective user, effective group, or all users.

ARCH_API std::string ArchStrerror ( )

Return the error string for the current value of errno.

This function provides a thread-safe method of fetching the error string from errno. POSIX.1c defines errno as a macro which provides access to a thread-local integer. This function is thread-safe. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ARCH_API std::string ArchStrerror ( int  errorCode)

Return the error string for the specified value of errno.

This function is thread-safe.

ARCH_API int64_t ArchTicksToNanoseconds ( uint64_t  nTicks)

Convert a duration measured in "ticks", as returned by ArchGetTickTime(), to nanoseconds.

An example to test the timing routines would be:

* int64_t t1 = ArchGetTickTime();
* sleep(10);
* int64_t t2 = ArchGetTickTime();
*
* // duration should be approximately 10/// 1e9 = 1e10 nanoseconds.
* int64_t duration = ArchTicksToNanoseconds(t2 - t1);
*
ARCH_API double ArchTicksToSeconds ( uint64_t  nTicks)

Convert a duration measured in "ticks", as returned by ArchGetTickTime(), to seconds.