Classes
struct	Arch_PerLibInit

struct	Arch_Unmapper

struct	ArchBuildMode

struct	ArchIntervalTimer
	A simple timer class for measuring an interval of time using the ArchTickTimer facilities. More...

class	ArchMallocHook
	Override default malloc() functionality. More...

class	ArchRegex

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.

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

typedef unsigned char	uchar

typedef std::function< std::string(uintptr_t address)>	ArchStackTraceCallback
	A callback to get a symbolic representation of an address.

typedef void(*	ArchCrashHandlerSystemCB) (void *userData)
	Callback for handling crashes.

Enumerations
enum	ArchMemAdvice { ArchMemAdviceNormal , ArchMemAdviceWillNeed , ArchMemAdviceDontNeed , ArchMemAdviceRandomAccess }

enum	ArchFileAdvice { ArchFileAdviceNormal , ArchFileAdviceWillNeed , ArchFileAdviceDontNeed , ArchFileAdviceRandomAccess }

enum	ArchMemoryProtection { ArchProtectNoAccess , ArchProtectReadOnly , ArchProtectReadWrite , ArchProtectReadWriteCopy }
	Memory protection options, see ArchSetMemoryProtection(). More...

Functions
size_t	ArchAlignMemorySize (size_t nBytes)
	Return suitably aligned memory size.

void *	ArchAlignMemory (void *base)
	Align memory to the next "best" alignment value.

ARCH_API void *	ArchAlignedAlloc (size_t alignment, size_t size)
	Aligned memory allocation.

ARCH_API void	ArchAlignedFree (void *ptr)
	Free memory allocated by ArchAlignedAlloc.

ARCH_API int	ArchCloseAllFiles (int nExcept, const int *exceptFds)
	Close all file descriptors (with possible exceptions)

ARCH_API void	ArchDebuggerTrap () ARCH_NOINLINE
	Stop in a debugger.

ARCH_API void	ArchDebuggerWait (bool wait)
	Cause debug traps to wait for the debugger or not.

ARCH_API bool	ArchDebuggerAttach () ARCH_NOINLINE
	Attach a debugger.

ARCH_API bool	ArchDebuggerIsAttached () ARCH_NOINLINE
	Test if a debugger is attached.

ARCH_API void	ArchAbort (bool logging=true)
	Abort.

ARCH_API bool	ArchDemangle (std::string *typeName)
	Demangle RTTI-generated type name.

ARCH_API std::string	ArchGetDemangled (const std::string &typeName)
	Return demangled RTTI-generated type name.

ARCH_API std::string	ArchGetDemangled (const char *typeName)
	Return demangled RTTI-generated type name.

std::string	ArchGetDemangled (const std::type_info &typeInfo)
	Return demangled RTTI-generated type name.

std::string	ArchGetDemangled (const std::type_index &typeIndex)
	Return demangled RTTI-generated type name.

template<typename T >
std::string	ArchGetDemangled ()
	Return demangled RTTI generated-type name.

ARCH_API bool	ArchHasEnv (const std::string &name)
	Architecture dependent access to environment variables.

ARCH_API std::string	ArchGetEnv (const std::string &name)
	Gets a value from the current environment identified by `name`.

ARCH_API bool	ArchSetEnv (const std::string &name, const std::string &value, bool overwrite)
	Creates or modifies an environment variable.

ARCH_API bool	ArchRemoveEnv (const std::string &name)
	Removes an environment variable.

ARCH_API std::string	ArchExpandEnvironmentVariables (const std::string &str)
	Expands environment variables in `str`.

ARCH_API char **	ArchEnviron ()
	Return an array of the environment variables.

ARCH_API std::string	ArchStrerror ()
	Return the error string for the current value of errno.

ARCH_API std::string	ArchStrerror (int errorCode)
	Return the error string for the specified value of errno.

ARCH_API FILE *	ArchOpenFile (char const fileName, char const mode)
	Opens a file.

ARCH_API int	ArchChmod (const char *path, int mode)

ARCH_API int	ArchCloseFile (int fd)

ARCH_API int	ArchUnlinkFile (const char *path)

ARCH_API int	ArchFileAccess (const char *path, int mode)

ARCH_API FILE *	ArchFdOpen (int fd, const char *mode)

ARCH_API int	ArchFileNo (FILE *file)

ARCH_API int	ArchFileIsaTTY (int fd)

ARCH_API int	ArchRmDir (const char *path)

ARCH_API int64_t	ArchGetFileLength (const char *fileName)
	Return the length of a file in bytes.

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.

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.

ARCH_API bool	ArchGetModificationTime (const char pathname, double time)
	Returns the modification time (mtime) in seconds for a file.

ARCH_API double	ArchGetModificationTime (const ArchStatType &st)
	Returns the modification time (mtime) in seconds from the stat struct.

ARCH_API std::string	ArchNormPath (const std::string &path, bool stripDriveSpecifier=false)
	Normalizes the specified path, eliminating double slashes, etc.

ARCH_API std::string	ArchAbsPath (const std::string &path)
	Returns the canonical absolute path of the specified filename.

ARCH_API bool	ArchGetStatMode (const char pathname, int mode)
	Returns the permissions mode (mode_t) for the given pathname.

ARCH_API const char *	ArchGetTmpDir ()
	Return the path to a temporary directory for this platform.

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.

ARCH_API int	ArchMakeTmpFile (const std::string &prefix, std::string *pathname=0)
	Create a temporary file, in a system-determined temporary directory.

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.

ARCH_API std::string	ArchMakeTmpSubdir (const std::string &tmpdir, const std::string &prefix)
	Create a temporary sub-direcrory, in a given temporary directory.

size_t	ArchGetFileMappingLength (ArchConstFileMapping const &m)
	Return the length of an ArchConstFileMapping.

size_t	ArchGetFileMappingLength (ArchMutableFileMapping const &m)
	Return the length of an ArchMutableFileMapping.

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.

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.

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.

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.

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

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

ARCH_API std::string	ArchReadLink (const char *path)
	Returns the value of the symbolic link at `path`.

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.

ARCH_API std::string	ArchGetPrettierFunctionName (const std::string &function, const std::string &prettyFunction)
	Return well formatted function name.

ARCH_API uint32_t	ArchHash (const char *data, size_t len)
	Hash len bytes of data.

ARCH_API uint32_t	ArchHash (const char *data, size_t len, uint32_t seed)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ARCH_API uint64_t	ArchHash64 (const char *data, size_t len)
	Hash len bytes of data.

ARCH_API uint64_t	ArchHash64 (const char *data, size_t len, uint64_t seed)
	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 *	ArchLibraryOpen (const std::string &filename, int flag)
	library.h Architecture dependent loading and unloading of dynamic libraries.

ARCH_API std::string	ArchLibraryError ()
	Obtain a description of the most recent error that occurred from `ArchLibraryOpen`.

ARCH_API int	ArchLibraryClose (void *handle)
	Closes an object opened with `ArchLibraryOpen`.

ARCH_API void *	ArchLibraryGetSymbolAddress (void handle, const char name)
	Obtain the address of a symbol defined within an object opened with `ArchLibraryOpen`.

ARCH_API bool	ArchIsPtmallocActive ()
	Return true if ptmalloc is being used as the memory allocator.

ARCH_API bool	ArchIsStlAllocatorOff ()
	Return true if the C++ STL allocator was requested to be turned off.

long	ArchSign (long val)
	Three-valued sign. Return 1 if val > 0, 0 if val == 0, or -1 if val < 0.

uint32_t	ArchFloatToBitPattern (float v)
	Returns The IEEE-754 bit pattern of the specified single precision value as a 32-bit unsigned integer.

float	ArchBitPatternToFloat (uint32_t v)
	Returns The single precision floating point value corresponding to the given IEEE-754 bit pattern.

uint64_t	ArchDoubleToBitPattern (double v)
	Returns The IEEE-754 bit pattern of the specified double precision value as a 64-bit unsigned integer.

double	ArchBitPatternToDouble (uint64_t v)
	Returns The double precision floating point value corresponding to the given IEEE-754 bit pattern.

void	ArchSinCosf (float v, float s, float c)
	Computes the sine and cosine of the specified value as a float.

void	ArchSinCos (double v, double s, double c)
	Computes the sine and cosine of the specified value as a double.

int	ArchCountTrailingZeros (uint64_t x)
	Return the number of consecutive 0-bits in `x` starting from the least significant bit position.

ARCH_API void	ArchLogFatalProcessState (const char reason, const char message=nullptr, const char *extraLogMsg=nullptr)
	Dumps call-stack info to a file, prints a message to the terminal, and invokes crash handling script.

ARCH_API void	ArchLogCurrentProcessState (const char reason, const char message=nullptr, const char *extraLogMsg=nullptr)
	Dumps call-stack info to a file, and prints an informative message.

ARCH_API void	ArchSetProcessStateLogCommand (const char command, const char const argv[], const char *const fatalArgv[])
	Sets command line that gets call-stack info and triggers crash handling script.

ARCH_API bool	ArchIsAppCrashing ()
	Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked.

ARCH_API void	ArchLogSessionInfo (const char *crashStackTrace=NULL)
	Log session info.

ARCH_API void	ArchSetLogSession (const char command, const char const argv[], const char *const crashArgv[])
	Sets the command line to log sessions.

ARCH_API void	ArchEnableSessionLogging ()
	Register the callback to invoke logging at end of a successful session.

ARCH_API void	ArchPrintStackTrace (FILE *fout, const std::string &programName, const std::string &reason)
	Print a stack trace to the given FILE pointer.

ARCH_API void	ArchPrintStackTrace (FILE *fout, const std::string &reason)
	Print a stack trace to the given FILE pointer.

ARCH_API void	ArchPrintStackTrace (std::ostream &out, const std::string &programName, const std::string &reason)
	Print a stack trace to the given ostream.

ARCH_API void	ArchPrintStackTrace (std::ostream &out, const std::string &reason)
	Print a stack trace to the given ostream.

ARCH_API void	ArchSetStackTraceCallback (const ArchStackTraceCallback &cb)
	Sets a callback to get a symbolic representation of an address.

ARCH_API void	ArchGetStackTraceCallback (ArchStackTraceCallback *cb)
	Returns the callback to get a symbolic representation of an address.

ARCH_API time_t	ArchGetAppLaunchTime ()
	Returns the set value for the application's launch time.

ARCH_API void	ArchSetFatalStackLogging (bool flag)
	Enables or disables the automatic logging of crash information.

ARCH_API bool	ArchGetFatalStackLogging ()
	Returns whether automatic logging of fatal crashes is enabled This is set to false by default.

ARCH_API void	ArchSetProgramNameForErrors (const char *progName)
	Sets the program name to be used in diagnostic output.

ARCH_API const char *	ArchGetProgramNameForErrors ()
	Returns the currently set program name for reporting errors.

ARCH_API void	ArchSetProgramInfoForErrors (const std::string &key, const std::string &value)
	Sets additional program info to be reported to the terminal in case of a fatal error.

ARCH_API std::string	ArchGetProgramInfoForErrors (const std::string &key)
	Returns currently set program info.

ARCH_API void	ArchSetExtraLogInfoForErrors (const std::string &key, std::vector< std::string > const *lines)
	Stores (or removes if `lines` is nullptr) a pointer to additional log data that will be output in the stack trace log in case of a fatal error.

ARCH_API void	ArchLogStackTrace (const std::string &progName, const std::string &reason, bool fatal=false, const std::string &sessionLog="")
	Logs a stack trace to a file in /var/tmp.

ARCH_API void	ArchLogStackTrace (const std::string &reason, bool fatal=false, const std::string &sessionLog="")
	Logs a stack trace to a file in /var/tmp.

ARCH_API std::vector< std::string >	ArchGetStackTrace (size_t maxDepth)
	Return stack trace.

ARCH_API void	ArchGetStackFrames (size_t maxDepth, std::vector< uintptr_t > *frames)
	Save frames of current stack.

ARCH_API size_t	ArchGetStackFrames (size_t maxDepth, uintptr_t *frames)
	Store at most `maxDepth` frames of the current stack into `frames`.

ARCH_API void	ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, std::vector< uintptr_t > *frames)
	Save frames of current stack.

ARCH_API size_t	ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, uintptr_t *frames)
	Store at most `maxDepth` frames of the current stack into `frames`, skipping the first `numFramesToSkipAtTop` frames.

ARCH_API void	ArchPrintStackFrames (std::ostream &out, const std::vector< uintptr_t > &frames, bool skipUnknownFrames=false)
	Print stack frames to the given ostream.

ARCH_API int	ArchCrashHandlerSystemv (const char pathname, char const argv[], int timeout, ArchCrashHandlerSystemCB callback, void *userData)
	Replacement for 'system' safe for a crash handler.

ARCH_API bool	ArchGetAddressInfo (void address, std::string objectPath, void *baseAddress, std::string symbolName, void **symbolAddress)
	Returns information about the address `address` in the running program.

ARCH_API std::string	ArchGetCwd ()
	Return current working directory as a string.

ARCH_API std::string	ArchGetExecutablePath ()
	Return the path to the program's executable.

ARCH_API int	ArchGetPageSize ()
	Return the system's memory page size. Safe to assume power-of-two.

ARCH_API bool	ArchIsMainThread ()
	Return true if the calling thread is the main thread, false otherwise.

ARCH_API std::thread::id	ArchGetMainThreadId ()
	Return the std::thread_id for the thread arch considers to be the "main" thread.

uint64_t	ArchGetTickTime ()
	Return the current time in system-dependent units.

uint64_t	ArchGetStartTickTime ()
	Get a "start" tick time for measuring an interval of time, followed by a later call to ArchGetStopTickTime().

uint64_t	ArchGetStopTickTime ()
	Get a "stop" tick time for measuring an interval of time.

ARCH_API uint64_t	ArchGetTickQuantum ()
	Return the tick time resolution.

ARCH_API uint64_t	ArchGetIntervalTimerTickOverhead ()
	Return the ticks taken to record an interval of time with ArchIntervalTimer, as measured at startup time.

ARCH_API int64_t	ArchTicksToNanoseconds (uint64_t nTicks)
	Convert a duration measured in "ticks", as returned by `ArchGetTickTime()`, to nanoseconds.

ARCH_API double	ArchTicksToSeconds (uint64_t nTicks)
	Convert a duration measured in "ticks", as returned by `ArchGetTickTime()`, to seconds.

ARCH_API uint64_t	ArchSecondsToTicks (double seconds)
	Convert a duration in seconds to "ticks", as returned by `ArchGetTickTime()`.

ARCH_API double	ArchGetNanosecondsPerTick ()
	Get nanoseconds per tick.

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

ARCH_API void *	ArchReserveVirtualMemory (size_t numBytes)
	Reserve `numBytes` bytes of virtual memory.

ARCH_API bool	ArchCommitVirtualMemoryRange (void *start, size_t numBytes)
	Make the range of `numBytes` bytes starting at `start` available for reading and writing.

ARCH_API bool	ArchFreeVirtualMemory (void *start, size_t numBytes)
	Return memory obtained with ArchReserveVirtualMemory() to the system.

ARCH_API bool	ArchSetMemoryProtection (void const *start, size_t numBytes, ArchMemoryProtection protection)
	Change the memory protection on the pages containing `start` and `start` + `numBytes` to `protection`.

ARCH_API int	ArchVsnprintf (char str, size_t size, const char format, va_list ap)
	Return the number of characters (not including the null character) necessary for a particular sprintf into a string.

ARCH_API std::string	ArchStringPrintf (const char *fmt,...)
	Returns a string formed by a printf()-like specification.

ARCH_API std::string	ArchVStringPrintf (const char *fmt, va_list ap)
	Returns a string formed by a printf()-like specification.

Detailed Description

Scope of the Pixar libraries.

Typedef Documentation

◆ ArchStatType

typedef struct stat pxr::ArchStatType

◆ ArchConstFileMapping

using pxr::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.

◆ ArchMutableFileMapping

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

◆ uchar

typedef unsigned char pxr::uchar

◆ ArchStackTraceCallback

typedef std::function<std::string(uintptr_t address)> pxr::ArchStackTraceCallback

A callback to get a symbolic representation of an address.

◆ ArchCrashHandlerSystemCB

typedef void(* pxr::ArchCrashHandlerSystemCB) (void *userData)

Callback for handling crashes.

See also: ArchCrashHandlerSystemv

Enumeration Type Documentation

◆ ArchMemAdvice

enum pxr::ArchMemAdvice

Enumerator
ArchMemAdviceNormal
ArchMemAdviceWillNeed
ArchMemAdviceDontNeed
ArchMemAdviceRandomAccess

◆ ArchFileAdvice

enum pxr::ArchFileAdvice

Enumerator
ArchFileAdviceNormal
ArchFileAdviceWillNeed
ArchFileAdviceDontNeed
ArchFileAdviceRandomAccess

◆ ArchMemoryProtection

enum pxr::ArchMemoryProtection

Memory protection options, see ArchSetMemoryProtection().

Enumerator
ArchProtectNoAccess
ArchProtectReadOnly
ArchProtectReadWrite
ArchProtectReadWriteCopy

Function Documentation

◆ ArchAlignMemorySize()

size_t pxr::ArchAlignMemorySize ( size_t nBytes )

inline

Return suitably aligned memory size.

Requests to malloc() or ::new for a given size are often rounded upward. Given a request for nBytes bytes of storage, this function returns the amount that would actually be consumed by the system to satisfy it. This is needed for efficient user-defined memory management.

◆ ArchAlignMemory()

void * pxr::ArchAlignMemory ( void * base )

inline

Align memory to the next "best" alignment value.

This will take a pointer and bump it to the next ideal alignment boundary that will work for all data types.

◆ ArchAlignedAlloc()

ARCH_API void * pxr::ArchAlignedAlloc	(	size_t	alignment,
		size_t	size )

Aligned memory allocation.

◆ ArchAlignedFree()

ARCH_API void pxr::ArchAlignedFree ( void * ptr )

Free memory allocated by ArchAlignedAlloc.

◆ ArchCloseAllFiles()

ARCH_API int pxr::ArchCloseAllFiles	(	int	nExcept,
		const int *	exceptFds )

Close all file descriptors (with possible exceptions)

ArchCloseAllFiles will close all file descriptors open in the current process. Occasionally you'd like to close all files except for some small subset (like 0, 1, and 2). The nExcept and exceptFds arguments can be used to provide the list of exceptions. ArchDaemonizeProcess uses this method to close all unwanted file descriptors in the daemon process.

nExcept should be the number of elements in the exceptFds array. Invalid file descriptors in exceptFds are ignored.

Note: Be very careful when using this routine. It is intended to be used after a fork(2) call to close all unwanted file descriptors. However, it does not flush stdio buffers, wait for processes opened with popen, shut down the X11 display connection, or anything. It just slams closed all the file descriptors. This is appropriate following a fork(2) call as all these file descriptors are duplicates of the ones in the parent process and shutting down the X11 display connection would mess up the parent's X11 display. But you shouldn't use ArchCloseAllFiles unless you know what you are doing.

Returns: -1 on error and errno will be set to an appropriate value. Returns 0 on success.

◆ ArchDebuggerTrap()

ARCH_API void pxr::ArchDebuggerTrap ( )

Stop in a debugger.

This function will do one of the following: start a debugger attached to this process stopped on this function; stop in an already attached debugger; stop and wait for a debugger to attach, or nothing.

On Linux this will start a debugger using ArchDebuggerAttach() if no debugger is attached. If a debugger is (or was) attached it will stop on this function due to SIGTRAP. Alternatively, users can configure the debugger to not stop on SIGTRAP and instead break on ArchDebuggerTrap().

If a debugger is not attached, ArchDebuggerAttach() does not attach one, and ArchDebuggerWait() has been most recently called with true then this will wait for a debugger to attach, otherwise it does nothing and the process does not stop. The user can continue the process from the debugger simply by issuing the continue command. The user can also continue the process from an attached terminal by putting the process into the foreground or background.

◆ ArchDebuggerWait()

ARCH_API void pxr::ArchDebuggerWait ( bool wait )

Cause debug traps to wait for the debugger or not.

When wait is true the next call to ArchDebuggerTrap() will cause the process to wait for a signal. The user can attach a debugger to continue the process. The process will not wait again until another call to this function with wait true.

◆ ArchDebuggerAttach()

ARCH_API bool pxr::ArchDebuggerAttach ( )

Attach a debugger.

Attaches the debugger by running the contents of the enviroment variable ARCH_DEBUGGER using /bin/sh. Any 'p' in the contents of this variable will be replaced with the process id of the process launching the debugger. Any 'e' will be replaced with the path to the executable for the process.

Returns true if ARCH_DEBUGGER is set and the debugger was successfully launched, otherwise returns false.

◆ ArchDebuggerIsAttached()

ARCH_API bool pxr::ArchDebuggerIsAttached ( )

Test if a debugger is attached.

Attempts to detect if a debugger is currently attached to the process.

◆ ArchAbort()

ARCH_API void pxr::ArchAbort ( bool logging = true )

Abort.

This will try to avoid the JIT debugger if any if ARCH_AVOID_JIT is in the environment and the debugger isn't already attached. In that case it will _exit(134). If logging is false then this will attempt to bypass any crash logging.

◆ ArchDemangle()

ARCH_API bool pxr::ArchDemangle ( std::string * typeName )

Demangle RTTI-generated type name.

Given a variable v, the construct typeid(v).name() returns the type-name of v; unfortunately, the returned type-name is sometimes extremely encoded (otherwise known as "mangled"). ArchDemangle parses the passed in type-name typeName into a readable form, and overwrites typeName. If typeName cannot be unmangled, the function returns false without altering typeName. Otherwise true is returned.

◆ ArchGetDemangled() [1/5]

ARCH_API std::string pxr::ArchGetDemangled ( const std::string & typeName )

Return demangled RTTI-generated type name.

If typeName can be demangled, the function returns the demangled string; otherwise, the function returns the empty string.

See also: ArchDemangle()

◆ ArchGetDemangled() [2/5]

ARCH_API std::string pxr::ArchGetDemangled ( const char * typeName )

Return demangled RTTI-generated type name.

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

◆ ArchGetDemangled() [3/5]

std::string pxr::ArchGetDemangled ( const std::type_info & typeInfo )

inline

Return demangled RTTI-generated type name.

Returns the demangled name associated with typeInfo (i.e. typeInfo.name()).

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

◆ ArchGetDemangled() [4/5]

std::string pxr::ArchGetDemangled ( const std::type_index & typeIndex )

inline

Return demangled RTTI-generated type name.

Returns the demangled name associated with typeIndex (i.e. typeIndex.name()).

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

◆ ArchGetDemangled() [5/5]

template<typename T >

std::string pxr::ArchGetDemangled ( )

inline

Return demangled RTTI generated-type name.

Returns the demangled name of type T.

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

◆ ArchHasEnv()

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

Architecture dependent access to environment variables.

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

◆ ArchGetEnv()

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

Gets a value from the current environment identified by name.

◆ ArchSetEnv()

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

Creates or modifies an environment variable.

◆ ArchRemoveEnv()

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

Removes an environment variable.

◆ ArchExpandEnvironmentVariables()

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

Expands environment variables in str.

◆ ArchEnviron()

ARCH_API char ** pxr::ArchEnviron ( )

Return an array of the environment variables.

◆ ArchStrerror() [1/2]

ARCH_API std::string pxr::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.

◆ ArchStrerror() [2/2]

ARCH_API std::string pxr::ArchStrerror ( int errorCode )

Return the error string for the specified value of errno.

This function is thread-safe.

◆ ArchOpenFile()

ARCH_API FILE * pxr::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.

◆ ArchChmod()

ARCH_API int pxr::ArchChmod	(	const char *	path,
		int	mode )

◆ ArchCloseFile()

ARCH_API int pxr::ArchCloseFile ( int fd )

◆ ArchUnlinkFile()

ARCH_API int pxr::ArchUnlinkFile ( const char * path )

◆ ArchFileAccess()

ARCH_API int pxr::ArchFileAccess	(	const char *	path,
		int	mode )

◆ ArchFdOpen()

ARCH_API FILE * pxr::ArchFdOpen	(	int	fd,
		const char *	mode )

◆ ArchFileNo()

ARCH_API int pxr::ArchFileNo ( FILE * file )

◆ ArchFileIsaTTY()

ARCH_API int pxr::ArchFileIsaTTY ( int fd )

◆ ArchRmDir()

ARCH_API int pxr::ArchRmDir ( const char * path )

◆ ArchGetFileLength() [1/2]

ARCH_API int64_t pxr::ArchGetFileLength ( const char * fileName )

Return the length of a file in bytes.

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

◆ ArchGetFileLength() [2/2]

ARCH_API int64_t pxr::ArchGetFileLength ( FILE * file )

◆ ArchGetFileName()

ARCH_API std::string pxr::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.

◆ ArchStatIsWritable()

ARCH_API bool pxr::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.

◆ ArchGetModificationTime() [1/2]

ARCH_API bool pxr::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.

◆ ArchGetModificationTime() [2/2]

ARCH_API double pxr::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.

◆ ArchNormPath()

ARCH_API std::string pxr::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.

◆ ArchAbsPath()

ARCH_API std::string pxr::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.

◆ ArchGetStatMode()

ARCH_API bool pxr::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.

◆ ArchGetTmpDir()

ARCH_API const char * pxr::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.

◆ ArchMakeTmpFileName()

ARCH_API std::string pxr::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().

◆ ArchMakeTmpFile() [1/2]

ARCH_API int pxr::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.

◆ ArchMakeTmpFile() [2/2]

ARCH_API int pxr::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.

◆ ArchMakeTmpSubdir()

ARCH_API std::string pxr::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.

◆ ArchGetFileMappingLength() [1/2]

size_t pxr::ArchGetFileMappingLength ( ArchConstFileMapping const & m )

inline

Return the length of an ArchConstFileMapping.

◆ ArchGetFileMappingLength() [2/2]

size_t pxr::ArchGetFileMappingLength ( ArchMutableFileMapping const & m )

inline

Return the length of an ArchMutableFileMapping.

◆ ArchMapFileReadOnly() [1/2]

ARCH_API ArchConstFileMapping pxr::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.

◆ ArchMapFileReadOnly() [2/2]

ARCH_API ArchConstFileMapping pxr::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.

◆ ArchMapFileReadWrite() [1/2]

ARCH_API ArchMutableFileMapping pxr::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.

◆ ArchMapFileReadWrite() [2/2]

ARCH_API ArchMutableFileMapping pxr::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.

◆ ArchMemAdvise()

ARCH_API void pxr::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.

◆ ArchQueryMappedMemoryResidency()

ARCH_API bool pxr::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.

◆ ArchPRead()

ARCH_API int64_t pxr::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.

◆ ArchPWrite()

ARCH_API int64_t pxr::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.

◆ ArchReadLink()

ARCH_API std::string pxr::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.

◆ ArchFileAdvise()

ARCH_API void pxr::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.

◆ ArchGetPrettierFunctionName()

ARCH_API std::string pxr::ArchGetPrettierFunctionName	(	const std::string &	function,
		const std::string &	prettyFunction )

Return well formatted function name.

This function assumes function is ARCH_FUNCTION and prettyFunction is ARCH_PRETTY_FUNCTION, and attempts to reconstruct a well formatted function name.

◆ ArchHash() [1/2]

ARCH_API uint32_t pxr::ArchHash	(	const char *	data,
		size_t	len )

Hash len bytes of data.

To compute a hash value for data that is not contiguous in memory, iterate over all the contiguous blocks of memory and accumulate the hash value by passing it on as seed. Note that this is not equivalent to hashing the contiguous pieces as a whole. Support for that may be added in future.

◆ ArchHash() [2/2]

ARCH_API uint32_t pxr::ArchHash	(	const char *	data,
		size_t	len,
		uint32_t	seed )

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

◆ ArchHash64() [1/2]

ARCH_API uint64_t pxr::ArchHash64	(	const char *	data,
		size_t	len )

Hash len bytes of data.

To compute a hash value for data that is not contiguous in memory, iterate over all the contiguous blocks of memory and accumulate the hash value by passing it on as seed. Note that this is not equivalent to hashing the contiguous pieces as a whole. Support for that may be added in future.

◆ ArchHash64() [2/2]

ARCH_API uint64_t pxr::ArchHash64	(	const char *	data,
		size_t	len,
		uint64_t	seed )

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

◆ ArchLibraryOpen()

ARCH_API void * pxr::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.

◆ ArchLibraryError()

ARCH_API std::string pxr::ArchLibraryError ( )

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

◆ ArchLibraryClose()

ARCH_API int pxr::ArchLibraryClose ( void * handle )

Closes an object opened with ArchLibraryOpen.

◆ ArchLibraryGetSymbolAddress()

ARCH_API void * pxr::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.

◆ ArchIsPtmallocActive()

ARCH_API bool pxr::ArchIsPtmallocActive ( )

Return true if ptmalloc is being used as the memory allocator.

ptmalloc3 is an external shared library providing implementations of the standard memory allocation functions (e.g. malloc, free). Consumers with special behavior that depends on this library may use this function to determine if it is the active allocator.

◆ ArchIsStlAllocatorOff()

ARCH_API bool pxr::ArchIsStlAllocatorOff ( )

Return true if the C++ STL allocator was requested to be turned off.

Under gcc, this is done by setting the environment variable GLIBCXX_FORCE_NEW, but it might differ (or not even be possible) for other platforms.

◆ ArchSign()

long pxr::ArchSign ( long val )

inline

Three-valued sign. Return 1 if val > 0, 0 if val == 0, or -1 if val < 0.

◆ ArchFloatToBitPattern()

uint32_t pxr::ArchFloatToBitPattern ( float v )

inline

Returns The IEEE-754 bit pattern of the specified single precision value as a 32-bit unsigned integer.

◆ ArchBitPatternToFloat()

float pxr::ArchBitPatternToFloat ( uint32_t v )

inline

Returns The single precision floating point value corresponding to the given IEEE-754 bit pattern.

◆ ArchDoubleToBitPattern()

uint64_t pxr::ArchDoubleToBitPattern ( double v )

inline

Returns The IEEE-754 bit pattern of the specified double precision value as a 64-bit unsigned integer.

◆ ArchBitPatternToDouble()

double pxr::ArchBitPatternToDouble ( uint64_t v )

inline

Returns The double precision floating point value corresponding to the given IEEE-754 bit pattern.

◆ ArchSinCosf()

void pxr::ArchSinCosf	(	float	v,
		float *	s,
		float *	c )

inline

Computes the sine and cosine of the specified value as a float.

◆ ArchSinCos()

void pxr::ArchSinCos	(	double	v,
		double *	s,
		double *	c )

inline

Computes the sine and cosine of the specified value as a double.

◆ ArchCountTrailingZeros()

int pxr::ArchCountTrailingZeros ( uint64_t x )

inline

Return the number of consecutive 0-bits in x starting from the least significant bit position.

If x is 0, the result is undefined.

◆ ArchLogFatalProcessState()

ARCH_API void pxr::ArchLogFatalProcessState	(	const char *	reason,
		const char *	message = nullptr,
		const char *	extraLogMsg = nullptr )

Dumps call-stack info to a file, prints a message to the terminal, and invokes crash handling script.

The reason for the trace should be supplied in reason. An additional message may be provided in message. If reason is NULL then this function only writes message to the banner (if any).

This routine can be slow and is intended to be called for a fatal error, such as a caught coredump signal. While it can theoretically be called at any time, ArchLogCurrentProcessState() should be used for nonfatal cases.

This function is implemented by calling an external program. This is suitable for times where the current process may be corrupted. In other cases, using ArchPrintStackTrace() or other related functions would be much faster.

Note the use of char* as opposed to string: this is intentional, because we are trying to use only async-safe function from here on and malloc() is not async-safe.

◆ ArchLogCurrentProcessState()

ARCH_API void pxr::ArchLogCurrentProcessState	(	const char *	reason,
		const char *	message = nullptr,
		const char *	extraLogMsg = nullptr )

Dumps call-stack info to a file, and prints an informative message.

The reason for the trace should be supplied in reason. An additional message may be provided in message. If reason is NULL then this function only writes message to the banner (if any).

This function is nearly identical to ArchLogFatalProcessState, including calling an external program. However, it is intended for cases that may simulate or require the output info from a full fatal crash, but are not truly fatal errors. For cases where that is not necessary, using ArchPrintStackTrace() or other related functions would be much faster.

Note the use of char* as opposed to string: this is intentional, because we are trying to use only async-safe function from here on and malloc() is not async-safe.

◆ ArchSetProcessStateLogCommand()

ARCH_API void pxr::ArchSetProcessStateLogCommand	(	const char *	command,
		const char *const	argv[],
		const char *const	fatalArgv[] )

Sets command line that gets call-stack info and triggers crash handling script.

This function sets the command line to execute to gather and log call-stack info. argv must be NULL terminated. If command and/or argv (or fatalArgv in the case of a fatal crash) are NULL, then the command will not be executed. Otherwise argv[0] and fatalArgv[0] must be the full path to the program to execute, typically command or "$cmd" as described below.

command, argv, and fatalArgv are not copied and must remain valid until the next call to ArchSetProcessStateLogCommand.

Simple substitution is supported on argv elements:

$cmd: Substitutes the command pathname, or $ARCH_POSTMORTEM if set
$pid: Substitutes the process id
$log: Substitutes the log pathname
$time: Substitutes the user time (if available, else wall time)
$reason: Substitutes the reason string for the crash

See also: ArchLogFatalProcessState

◆ ArchIsAppCrashing()

ARCH_API bool pxr::ArchIsAppCrashing ( )

Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked.

◆ ArchLogSessionInfo()

ARCH_API void pxr::ArchLogSessionInfo ( const char * crashStackTrace = NULL )

Log session info.

Optionally indicate that this is due to a crash by providing the path to a file containing a stack trace in crashStackTrace.

◆ ArchSetLogSession()

ARCH_API void pxr::ArchSetLogSession	(	const char *	command,
		const char *const	argv[],
		const char *const	crashArgv[] )

Sets the command line to log sessions.

This function sets the command line to execute to log session info. argv is used if no crash stack trace is provided, otherwise crashArgv is used. Both must be NULL terminated. If command or argv is NULL then non-crashes are not logged; if command or crashArgv is NULL then crashes are not logged. If not NULL then argv[0] and crashArgv[0] must be full path to the program to execute, typically command or "$cmd" as described below.

command, argv, and crashArgv are not copied and must remain valid until the next call to ArchSetLogSession.

Simple substitution is supported on argv elements:

$cmd: Substitutes the command pathname, or $ARCH_LOGSESSION if set
$prog Substitutes the program name
$pid: Substitutes the process id
$time: Substitutes the user time (if available, else wall time)
$stack: Substitutes the crash stack string (only in crashArgv)

See also: ArchLogSessionInfo

◆ ArchEnableSessionLogging()

ARCH_API void pxr::ArchEnableSessionLogging ( )

Register the callback to invoke logging at end of a successful session.

This function registers ArchLogSessionInfo() and records the current timestamp, to send up-time to the DB upon exiting.

◆ ArchPrintStackTrace() [1/4]

ARCH_API void pxr::ArchPrintStackTrace	(	FILE *	fout,
		const std::string &	programName,
		const std::string &	reason )

Print a stack trace to the given FILE pointer.

◆ ArchPrintStackTrace() [2/4]

ARCH_API void pxr::ArchPrintStackTrace	(	FILE *	fout,
		const std::string &	reason )

Print a stack trace to the given FILE pointer.

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

◆ ArchPrintStackTrace() [3/4]

ARCH_API void pxr::ArchPrintStackTrace	(	std::ostream &	out,
		const std::string &	programName,
		const std::string &	reason )

Print a stack trace to the given ostream.

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

◆ ArchPrintStackTrace() [4/4]

ARCH_API void pxr::ArchPrintStackTrace	(	std::ostream &	out,
		const std::string &	reason )

Print a stack trace to the given ostream.

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

◆ ArchSetStackTraceCallback()

ARCH_API void pxr::ArchSetStackTraceCallback ( const ArchStackTraceCallback & cb )

Sets a callback to get a symbolic representation of an address.

The callback returns a string for an address in a stack trace, typically including the name of the function containing the address. cb may be NULL to use a default implementation.

◆ ArchGetStackTraceCallback()

ARCH_API void pxr::ArchGetStackTraceCallback ( ArchStackTraceCallback * cb )

Returns the callback to get a symbolic representation of an address.

See also: ArchSetStackTraceCallback

◆ ArchGetAppLaunchTime()

ARCH_API time_t pxr::ArchGetAppLaunchTime ( )

Returns the set value for the application's launch time.

The timestamp for this value is set when the arch library is initialized.

◆ ArchSetFatalStackLogging()

ARCH_API void pxr::ArchSetFatalStackLogging ( bool flag )

Enables or disables the automatic logging of crash information.

This function controls whether the stack trace and build information is automatically caught and stored to an internal database when a fatal crash occurs.

◆ ArchGetFatalStackLogging()

ARCH_API bool pxr::ArchGetFatalStackLogging ( )

Returns whether automatic logging of fatal crashes is enabled This is set to false by default.

See also: ArchSetFatalStackLogging

◆ ArchSetProgramNameForErrors()

ARCH_API void pxr::ArchSetProgramNameForErrors ( const char * progName )

Sets the program name to be used in diagnostic output.

The default value is initialized to ArchGetExecutablePath().

◆ ArchGetProgramNameForErrors()

ARCH_API const char * pxr::ArchGetProgramNameForErrors ( )

Returns the currently set program name for reporting errors.

Defaults to ArchGetExecutablePath().

◆ ArchSetProgramInfoForErrors()

ARCH_API void pxr::ArchSetProgramInfoForErrors	(	const std::string &	key,
		const std::string &	value )

Sets additional program info to be reported to the terminal in case of a fatal error.

◆ ArchGetProgramInfoForErrors()

ARCH_API std::string pxr::ArchGetProgramInfoForErrors ( const std::string & key )

Returns currently set program info.

See also: ArchSetExtraLogInfoForErrors

◆ ArchSetExtraLogInfoForErrors()

ARCH_API void pxr::ArchSetExtraLogInfoForErrors	(	const std::string &	key,
		std::vector< std::string > const *	lines )

Stores (or removes if lines is nullptr) a pointer to additional log data that will be output in the stack trace log in case of a fatal error.

Note that the pointer lines is copied, not the pointed-to data. In addition, Arch might read the data pointed to by lines concurrently at any time. Thus it is the caller's responsibility to ensure that lines is both valid and not mutated until replacing or removing it by invoking this function again with the same key and different lines.

◆ ArchLogStackTrace() [1/2]

ARCH_API void pxr::ArchLogStackTrace	(	const std::string &	progName,
		const std::string &	reason,
		bool	fatal = false,
		const std::string &	sessionLog = "" )

Logs a stack trace to a file in /var/tmp.

This function is similar to ArchLogPostMortem(), but will not fork an external process and only reports a stack trace. A file in /var/tmp is created with the name st_APPNAME.XXXXXX, where mktemp is used to make a unique extension for the file. If sessionLog is specified, then it will be appended to this file. A message is printed to stderr reporting that a stack trace has been taken and what file it has been written to. And if fatal is true, then the stack trace will be added to the stack_trace database table.

◆ ArchLogStackTrace() [2/2]

ARCH_API void pxr::ArchLogStackTrace	(	const std::string &	reason,
		bool	fatal = false,
		const std::string &	sessionLog = "" )

Logs a stack trace to a file in /var/tmp.

This function is similar to ArchLogPostMortem(), but will not fork an external process and only reports a stack trace. A file in /var/tmp is created with the name st_APPNAME.XXXXXX, where mktemp is used to make a unique extension for the file. If sessionLog is specified, then it will be appended to this file. A message is printed to stderr reporting that a stack trace has been taken and what file it has been written to. And if fatal is true, then the stack trace will be added to the stack_trace database table.

◆ ArchGetStackTrace()

ARCH_API std::vector< std::string > pxr::ArchGetStackTrace ( size_t maxDepth )

Return stack trace.

This function will return a vector of strings containing the current stack. The vector will be of maximum size maxDepth.

◆ ArchGetStackFrames() [1/4]

ARCH_API void pxr::ArchGetStackFrames	(	size_t	maxDepth,
		std::vector< uintptr_t > *	frames )

Save frames of current stack.

This function saves at maximum maxDepth frames of the current stack into the vector frames.

◆ ArchGetStackFrames() [2/4]

ARCH_API size_t pxr::ArchGetStackFrames	(	size_t	maxDepth,
		uintptr_t *	frames )

Store at most maxDepth frames of the current stack into frames.

Return the number of stack frames written to frames.

◆ ArchGetStackFrames() [3/4]

ARCH_API void pxr::ArchGetStackFrames	(	size_t	maxDepth,
		size_t	numFramesToSkipAtTop,
		std::vector< uintptr_t > *	frames )

Save frames of current stack.

This function saves at maximum maxDepth frames of the current stack into the vector frames, skipping the first numFramesToSkipAtTop frames. The first frame will be at depth numFramesToSkipAtTop and the last at depth numFramesToSkipAtTop + maxDepth - 1.

◆ ArchGetStackFrames() [4/4]

ARCH_API size_t pxr::ArchGetStackFrames	(	size_t	maxDepth,
		size_t	numFramesToSkipAtTop,
		uintptr_t *	frames )

Store at most maxDepth frames of the current stack into frames, skipping the first numFramesToSkipAtTop frames.

Return the number of stack frames written to frames.

◆ ArchPrintStackFrames()

ARCH_API void pxr::ArchPrintStackFrames	(	std::ostream &	out,
		const std::vector< uintptr_t > &	frames,
		bool	skipUnknownFrames = false )

Print stack frames to the given ostream.

◆ ArchCrashHandlerSystemv()

ARCH_API int pxr::ArchCrashHandlerSystemv	(	const char *	pathname,
		char *const	argv[],
		int	timeout,
		ArchCrashHandlerSystemCB	callback,
		void *	userData )

Replacement for 'system' safe for a crash handler.

This function is a substitute for system() which does not allocate or free any data, and times out after timeout seconds if the operation in argv is not complete. Unlike system, it takes the full pathname of the program to run, and won't search the path. Also unlike system, argv[] are the separated arguments, starting with the program's name, as for execv. callback is called every second. userData is passed to callback. callback can be used, for example, to print a '.' repeatedly to show progress. The alarm used in this function could interfere with setitimer or other calls to alarm, and this function uses non-locking fork and exec if available so should not generally be used except following a catastrophe.

◆ ArchGetAddressInfo()

ARCH_API bool pxr::ArchGetAddressInfo	(	void *	address,
		std::string *	objectPath,
		void **	baseAddress,
		std::string *	symbolName,
		void **	symbolAddress )

Returns information about the address address in the running program.

Returns false if no information can be found, otherwise returns true and modifies the other arguments: objectPath is set to the absolute path to the executable or library the address is found in, baseAddress is the address where that object is loaded, symbolName is the symbolic name of the thing containing the address, and symbolAddress is the starting address of that thing. If no thing is found to contain the address then symbolName is cleared and symbolAddress is set to NULL. Any of the arguments except address can be NULL if the result isn't needed. This will return false if NULL is passed to address.

◆ ArchGetCwd()

ARCH_API std::string pxr::ArchGetCwd ( )

Return current working directory as a string.

◆ ArchGetExecutablePath()

ARCH_API std::string pxr::ArchGetExecutablePath ( )

Return the path to the program's executable.

◆ ArchGetPageSize()

ARCH_API int pxr::ArchGetPageSize ( )

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

◆ ArchIsMainThread()

ARCH_API bool pxr::ArchIsMainThread ( )

Return true if the calling thread is the main thread, false otherwise.

◆ ArchGetMainThreadId()

ARCH_API std::thread::id pxr::ArchGetMainThreadId ( )

Return the std::thread_id for the thread arch considers to be the "main" thread.

◆ ArchGetTickTime()

uint64_t pxr::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.

◆ ArchGetStartTickTime()

uint64_t pxr::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.

◆ ArchGetStopTickTime()

uint64_t pxr::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.

◆ ArchGetTickQuantum()

ARCH_API uint64_t pxr::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().

◆ ArchGetIntervalTimerTickOverhead()

ARCH_API uint64_t pxr::ArchGetIntervalTimerTickOverhead ( )

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

◆ ArchTicksToNanoseconds()

ARCH_API int64_t pxr::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:

ArchIntervalTimer iTimer;
sleep(10);
 
// duration should be approximately 10/// 1e9 = 1e10 nanoseconds.
int64_t duration = ArchTicksToNanoseconds(iTimer.GetElapsedTicks());

◆ ArchTicksToSeconds()

ARCH_API double pxr::ArchTicksToSeconds ( uint64_t nTicks )

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

◆ ArchSecondsToTicks()

ARCH_API uint64_t pxr::ArchSecondsToTicks ( double seconds )

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

◆ ArchGetNanosecondsPerTick()

ARCH_API double pxr::ArchGetNanosecondsPerTick ( )

Get nanoseconds per tick.

Useful when converting ticks obtained from ArchTickTime()

◆ Arch_MeasureExecutionTime()

ARCH_API uint64_t pxr::Arch_MeasureExecutionTime	(	uint64_t	maxTicks,
		bool *	reachedConsensus,
		void const *	m,
		uint64_t(*	callM )(void const *, int) )

◆ ArchMeasureExecutionTime()

template<class Fn >

uint64_t pxr::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.

◆ ArchReserveVirtualMemory()

ARCH_API void * pxr::ArchReserveVirtualMemory ( size_t numBytes )

Reserve numBytes bytes of virtual memory.

Call ArchCommitVirtualMemory() on subranges to write to and read from the memory. Return nullptr in case of an error; check errno.

◆ ArchCommitVirtualMemoryRange()

ARCH_API bool pxr::ArchCommitVirtualMemoryRange	(	void *	start,
		size_t	numBytes )

Make the range of numBytes bytes starting at start available for reading and writing.

The range must be within one previously reserved by ArchReserveVirtualMemory(). It is not an error to commit a range that was previously partly or fully committed. Return false in case of an error; check errno.

◆ ArchFreeVirtualMemory()

ARCH_API bool pxr::ArchFreeVirtualMemory	(	void *	start,
		size_t	numBytes )

Return memory obtained with ArchReserveVirtualMemory() to the system.

The start argument must be the value returned from a previous call to ArchReserveVirtualMemory, and numBytes must match the argument from that call. Memory within the range may not be accessed after this call. Return false in case of an error; check errno.

◆ ArchSetMemoryProtection()

ARCH_API bool pxr::ArchSetMemoryProtection	(	void const *	start,
		size_t	numBytes,
		ArchMemoryProtection	protection )

Change the memory protection on the pages containing start and start + numBytes to protection.

Return true if the protection is changed successfully. Return false in case of an error; check errno. This function rounds start to the nearest lower page boundary. On POSIX systems, ArchProtectReadWrite and ArchProtectReadWriteCopy are the same, on Windows they differ but the Windows API documentation does not make it clear what using ReadWrite means for a private file-backed mapping.

◆ ArchVsnprintf()

ARCH_API int pxr::ArchVsnprintf	(	char *	str,
		size_t	size,
		const char *	format,
		va_list	ap )

Return the number of characters (not including the null character) necessary for a particular sprintf into a string.

ArchVsnprintf guarantees the C99 behavior of vsnprintf on all systems: it returns the number of bytes (not including the terminating null character) needed to actually print the requested string. If size indicates that str has enough capacity to hold the result, then the function actually prints into str.

You probably want to use the functionality of this call via TfStringPrintf().

◆ ArchStringPrintf()

ARCH_API std::string pxr::ArchStringPrintf	(	const char *	fmt,
			... )

Returns a string formed by a printf()-like specification.

ArchStringPrintf() is a memory-safe architecture-independent way of forming a string using printf()-like formatting. For example,

string formatMsg(const string& caller, int i, double val[])
{
   return ArchStringPrintf("%s: val[%d] = %g\n", caller.c_str(), i, val[i]);
}

The function is safe only to the extent that the arguments match the formatting string. In particular, be careful to pass strings themselve into ArchStringPrintf() as in the above example (i.e. caller.c_str() as opposed to just passing caller).

◆ ArchVStringPrintf()

ARCH_API std::string pxr::ArchVStringPrintf	(	const char *	fmt,
		va_list	ap )

Returns a string formed by a printf()-like specification.

ArchVStringPrintf() is equivalent to ArchStringPrintf() except that it is called with a va_list instead of a variable number of arguments. ArchVStringPrintf() does not call the va_end macro. Consequently, the value of ap is undefined after the call. A functions that calls ArchVStringPrintf() should call va_end(ap) itself afterwards.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ArchStatType

◆ ArchConstFileMapping

◆ ArchMutableFileMapping

◆ uchar

◆ ArchStackTraceCallback

◆ ArchCrashHandlerSystemCB

Enumeration Type Documentation

◆ ArchMemAdvice

◆ ArchFileAdvice

◆ ArchMemoryProtection

Function Documentation

◆ ArchAlignMemorySize()

◆ ArchAlignMemory()

◆ ArchAlignedAlloc()

◆ ArchAlignedFree()

◆ ArchCloseAllFiles()

◆ ArchDebuggerTrap()

◆ ArchDebuggerWait()

◆ ArchDebuggerAttach()

◆ ArchDebuggerIsAttached()

◆ ArchAbort()

◆ ArchDemangle()

◆ ArchGetDemangled() [1/5]

◆ ArchGetDemangled() [2/5]

◆ ArchGetDemangled() [3/5]

◆ ArchGetDemangled() [4/5]

◆ ArchGetDemangled() [5/5]

◆ ArchHasEnv()

◆ ArchGetEnv()

◆ ArchSetEnv()

◆ ArchRemoveEnv()

◆ ArchExpandEnvironmentVariables()

◆ ArchEnviron()

◆ ArchStrerror() [1/2]

◆ ArchStrerror() [2/2]

◆ ArchOpenFile()

◆ ArchChmod()

◆ ArchCloseFile()

◆ ArchUnlinkFile()

◆ ArchFileAccess()

◆ ArchFdOpen()

◆ ArchFileNo()

◆ ArchFileIsaTTY()

◆ ArchRmDir()

◆ ArchGetFileLength() [1/2]

◆ ArchGetFileLength() [2/2]

◆ ArchGetFileName()

◆ ArchStatIsWritable()

◆ ArchGetModificationTime() [1/2]

◆ ArchGetModificationTime() [2/2]

◆ ArchNormPath()

◆ ArchAbsPath()

◆ ArchGetStatMode()

◆ ArchGetTmpDir()

◆ ArchMakeTmpFileName()

◆ ArchMakeTmpFile() [1/2]

◆ ArchMakeTmpFile() [2/2]

◆ ArchMakeTmpSubdir()

◆ ArchGetFileMappingLength() [1/2]

◆ ArchGetFileMappingLength() [2/2]

◆ ArchMapFileReadOnly() [1/2]

◆ ArchMapFileReadOnly() [2/2]

◆ ArchMapFileReadWrite() [1/2]

◆ ArchMapFileReadWrite() [2/2]

◆ ArchMemAdvise()

◆ ArchQueryMappedMemoryResidency()

◆ ArchPRead()

◆ ArchPWrite()

◆ ArchReadLink()

◆ ArchFileAdvise()

◆ ArchGetPrettierFunctionName()

◆ ArchHash() [1/2]

◆ ArchHash() [2/2]

◆ ArchHash64() [1/2]