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

Files

file  errno.h
 
file  fileSystem.h
 
file  fileSystem.h
 
file  fileSystem.h
 
file  systemInfo.h
 
file  timing.h
 
file  virtualMemory.h
 

Classes

struct  Arch_Unmapper
 
struct  ArchIntervalTimer
 

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)
 

Typedefs

typedef struct stat ArchStatType
 
using ArchConstFileMapping = std::unique_ptr< char const, Arch_Unmapper >
 
using ArchMutableFileMapping = std::unique_ptr< char, Arch_Unmapper >
 

Enumerations

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

Functions

PXR_NAMESPACE_OPEN_SCOPE
ARCH_API bool 
ArchHasEnv (const std::string &name)
 
ARCH_API std::string ArchGetEnv (const std::string &name)
 
ARCH_API bool ArchSetEnv (const std::string &name, const std::string &value, bool overwrite)
 
ARCH_API bool ArchRemoveEnv (const std::string &name)
 
ARCH_API std::string ArchExpandEnvironmentVariables (const std::string &str)
 
ARCH_API char ** ArchEnviron ()
 
ARCH_API std::string ArchStrerror ()
 
ARCH_API std::string ArchStrerror (int errorCode)
 
ARCH_API FILE * ArchOpenFile (char const *fileName, char const *mode)
 
ARCH_API int64_t ArchGetFileLength (const char *fileName)
 
ARCH_API int64_t ArchGetFileLength (FILE *file)
 
ARCH_API std::string ArchGetFileName (FILE *file)
 
ARCH_API bool ArchStatIsWritable (const ArchStatType *st)
 
ARCH_API bool ArchGetModificationTime (const char *pathname, double *time)
 
ARCH_API double ArchGetModificationTime (const ArchStatType &st)
 
ARCH_API std::string ArchNormPath (const std::string &path, bool stripDriveSpecifier=false)
 
ARCH_API std::string ArchAbsPath (const std::string &path)
 
ARCH_API bool ArchGetStatMode (const char *pathname, int *mode)
 
ARCH_API const char * ArchGetTmpDir ()
 
ARCH_API std::string ArchMakeTmpFileName (const std::string &prefix, const std::string &suffix=std::string())
 
ARCH_API int ArchMakeTmpFile (const std::string &prefix, std::string *pathname=0)
 
ARCH_API int ArchMakeTmpFile (const std::string &tmpdir, const std::string &prefix, std::string *pathname=0)
 
ARCH_API std::string ArchMakeTmpSubdir (const std::string &tmpdir, const std::string &prefix)
 
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)
 
ARCH_API ArchConstFileMapping ArchMapFileReadOnly (std::string const &path, std::string *errMsg=nullptr)
 
ARCH_API ArchMutableFileMapping ArchMapFileReadWrite (FILE *file, std::string *errMsg=nullptr)
 
ARCH_API ArchMutableFileMapping ArchMapFileReadWrite (std::string const &path, std::string *errMsg=nullptr)
 
ARCH_API void ArchMemAdvise (void const *addr, size_t len, ArchMemAdvice adv)
 
ARCH_API bool ArchQueryMappedMemoryResidency (void const *addr, size_t len, unsigned char *pageMap)
 
ARCH_API int64_t ArchPRead (FILE *file, void *buffer, size_t count, int64_t offset)
 
ARCH_API int64_t ArchPWrite (FILE *file, void const *bytes, size_t count, int64_t offset)
 
ARCH_API std::string ArchReadLink (const char *path)
 
ARCH_API void ArchFileAdvise (FILE *file, int64_t offset, size_t count, ArchFileAdvice adv)
 
PXR_NAMESPACE_OPEN_SCOPE
ARCH_API void
ArchLibraryOpen (const std::string &filename, int flag)
 
ARCH_API std::string ArchLibraryError ()
 
ARCH_API int ArchLibraryClose (void *handle)
 
ARCH_API voidArchLibraryGetSymbolAddress (void *handle, const char *name)
 
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...
 
PXR_NAMESPACE_OPEN_SCOPE uint64_t ArchGetTickTime ()
 
uint64_t ArchGetStartTickTime ()
 
uint64_t ArchGetStopTickTime ()
 
ARCH_API uint64_t ArchGetTickQuantum ()
 
ARCH_API uint64_t ArchGetIntervalTimerTickOverhead ()
 
ARCH_API int64_t ArchTicksToNanoseconds (uint64_t nTicks)
 
ARCH_API double ArchTicksToSeconds (uint64_t nTicks)
 
ARCH_API uint64_t ArchSecondsToTicks (double seconds)
 
ARCH_API double ArchGetNanosecondsPerTick ()
 
ARCH_API uint64_t Arch_MeasureExecutionTime (uint64_t maxTicks, bool *reachedConsensus, void const *m, uint64_t(*callM)(void const *, int))
 
template<class Fn >
uint64_t ArchMeasureExecutionTime (Fn const &fn, uint64_t maxTicks=1e7, bool *reachedConsensus=nullptr)
 

Detailed Description

Macro Definition Documentation

#define ARCH_GLOB_DEFAULT   (ARCH_GLOB_NOCHECK | ARCH_GLOB_MARK)

Definition at line 89 of file fileSystem.h.

#define ARCH_GLOB_MARK   GLOB_MARK

Definition at line 86 of file fileSystem.h.

#define ARCH_GLOB_NOCHECK   GLOB_NOCHECK

Definition at line 85 of file fileSystem.h.

#define ARCH_GLOB_NOSORT   GLOB_NOSORT

Definition at line 87 of file fileSystem.h.

#define ARCH_PATH_LIST_SEP   ":"

Definition at line 113 of file fileSystem.h.

#define ARCH_PATH_MAX   1024

Definition at line 101 of file fileSystem.h.

#define ARCH_PATH_SEP   "/"

Definition at line 112 of file fileSystem.h.

#define ARCH_REL_PATH_IDENT   "./"

Definition at line 114 of file fileSystem.h.

#define ArchChmod (   path,
  mode 
)    chmod(path, mode)

Definition at line 139 of file fileSystem.h.

#define ArchCloseFile (   fd)    close(fd)

Definition at line 145 of file fileSystem.h.

#define ArchFdOpen (   fd,
  mode 
)    fdopen(fd, mode)

Definition at line 163 of file fileSystem.h.

#define ArchFileAccess (   path,
  mode 
)    access(path, mode)

Definition at line 157 of file fileSystem.h.

#define ArchFileIsaTTY (   stream)    isatty(stream)

Definition at line 175 of file fileSystem.h.

#define ArchFileNo (   stream)    fileno(stream)

Definition at line 169 of file fileSystem.h.

#define ArchRmDir (   path)    rmdir(path)

Definition at line 181 of file fileSystem.h.

#define ArchUnlinkFile (   path)    unlink(path)

Definition at line 151 of file fileSystem.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 321 of file fileSystem.h.

using ArchMutableFileMapping = std::unique_ptr<char, Arch_Unmapper>

Definition at line 322 of file fileSystem.h.

typedef struct stat ArchStatType

Definition at line 120 of file fileSystem.h.

Enumeration Type Documentation

Enumerator
ArchFileAdviceNormal 
ArchFileAdviceWillNeed 
ArchFileAdviceDontNeed 
ArchFileAdviceRandomAccess 

Definition at line 414 of file fileSystem.h.

Enumerator
ArchMemAdviceNormal 
ArchMemAdviceWillNeed 
ArchMemAdviceDontNeed 
ArchMemAdviceRandomAccess 

Definition at line 364 of file fileSystem.h.

Function Documentation

ARCH_API uint64_t Arch_MeasureExecutionTime ( uint64_t  maxTicks,
bool *  reachedConsensus,
void const *  m,
uint64_t(*)(void const *, int callM 
)
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.

ARCH_API int64_t ArchGetFileLength ( FILE *  file)
size_t ArchGetFileMappingLength ( ArchConstFileMapping const &  m)
inline

Return the length of an ArchConstFileMapping.

Definition at line 326 of file fileSystem.h.

size_t ArchGetFileMappingLength ( ArchMutableFileMapping const &  m)
inline

Return the length of an ArchMutableFileMapping.

Definition at line 332 of file fileSystem.h.

ARCH_API std::string ArchGetFileName ( FILE *  file)

Return a filename for this file, if one can be obtained. Note that there are many reasons why it may be impossible to obtain a filename, even for an opened FILE *. Whenever possible avoid using this function and instead store the filename for future use.

ARCH_API uint64_t ArchGetIntervalTimerTickOverhead ( )

Return the ticks taken to record an interval of time with ArchIntervalTimer, as measured at startup time.

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.

uint64_t ArchGetStartTickTime ( )
inline

Get a "start" tick time for measuring an interval of time, followed by a later call to ArchGetStopTickTime(). Or see ArchIntervalTimer. This is like ArchGetTickTime but it includes compiler & CPU fencing & reordering constraints in an attempt to get the best measurement possible.

Definition at line 85 of file timing.h.

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 ArchGetStopTickTime ( )
inline

Get a "stop" tick time for measuring an interval of time. See ArchGetStartTickTime() or ArchIntervalTimer. This is like ArchGetTickTime but it includes compiler & CPU fencing & reordering constraints in an attempt to get the best measurement possible.

Definition at line 126 of file timing.h.

ARCH_API uint64_t ArchGetTickQuantum ( )

Return the tick time resolution. Although the number of ticks per second may be very large, on many current systems the tick timers do not update at that rate. Rather, sequential calls to ArchGetTickTime() may report increases of 10s to 100s of ticks, with a minimum increment betwewen calls. This function returns that minimum increment as measured at startup time.

Note that if this value is of sufficient size, then short times measured with tick timers are potentially subject to significant noise. In particular, an interval of measured tick time is liable to be off by +/- one ArchGetTickQuantum().

PXR_NAMESPACE_OPEN_SCOPE 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 10s-to-100s of nanoseconds on GHz class machines.

Definition at line 62 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.

PXR_NAMESPACE_OPEN_SCOPE 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.

PXR_NAMESPACE_OPEN_SCOPE 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.

template<class Fn >
uint64_t ArchMeasureExecutionTime ( Fn const &  fn,
uint64_t  maxTicks = 1e7,
bool *  reachedConsensus = nullptr 
)

Run fn repeatedly attempting to determine a consensus fastest execution time with low noise, for up to maxTicks, then return the consensus fastest execution time. If a consensus is not reached in that time, return a best estimate instead. If reachedConsensus is not null, set it to indicate whether or not a consensus was reached. This function ignores maxTicks greater than 5 billion ticks and runs for up to 5 billion ticks instead. The fn will run for an indeterminate number of times, so it should be side-effect free. Also, it should do essentially the same work on every invocation so that timing its execution makes sense.

Definition at line 331 of file timing.h.

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:

sleep(10);
// duration should be approximately 10/// 1e9 = 1e10 nanoseconds.
int64_t duration = ArchTicksToNanoseconds(iTimer.GetElapsedTicks());
ARCH_API double ArchTicksToSeconds ( uint64_t  nTicks)

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