extras#

Fully qualified name: carb::extras

namespace extras#: Common namespace for extra helper functions and classes.

Classes#

Base64: Encoder and decoder helper for Base64 data.
CpuInfo: Helper class for gathering and querying CPU information for x86 and x64 CPUs.
EnvironmentVariable: Defines an environment variable class that allows one to get, set, and restore value on destruction.
EnvironmentVariableParser: Parses environment variables into program options or environment variables.
HandleDatabase: Provides an OS-style mapping of a Handle to a Resource.
Path: Path objects are used for filesystem path manipulations.
SharedMemory: A utility helper class to provide shared memory access to one or more processes.
Utf8Iterator: A simple iterator class for walking a UTF-8 string.
Utf8Parser: Static helper class to allow for the processing of UTF-8 strings.
Uuid: UUIDv4 Unique Identifier (RFC 4122)

Enumerations#

MemoryQueryType: The type of memory to query.
MemoryScaleType: Names for the different types of common memory scales.
SharedState: Bitwise state values returned by carb::extras::HandleDatabase::getSharedState() .

Functions#

void adjustWindowsDllSearchPaths(): (Windows only) Sets the default DLL search directories for the application.
int32_t compareStrings(const char *str1, const char *str2): Compare two strings in a case sensitive manner.
int32_t compareStringsNoCase(const char *str1, const char *str2): Compare two strings in a case insensitive manner.
std::wstring convertCarboniteToWindowsPath(const std::string &path): (Windows only) Converts a UTF-8 file path to Windows system file path.
std::string convertErrnoToMessage(ErrnoType errorCode): Returns a human-readable string for a given errno value.
std::string convertUtf16StringToUtf8(const char16_t *str): Convert a UTF-16 encoded string to UTF-8.
size_t convertUtf16StringToUtf8(const char16_t *str, char *out, size_t outLen): Convert a UTF-16 encoded string to UTF-8.
std::string convertUtf16StringToUtf8(std::u16string str): Convert a UTF-8 encoded string to UTF-32.
size_t convertUtf32StringToUtf8(const char32_t *str, char *out, size_t outLen): Convert a UTF-32 encoded string to UTF-8.
std::string convertUtf32StringToUtf8(std::u32string str): Convert a UTF-8 encoded string to UTF-32.
std::string convertUtf32StringToUtf8(const char32_t *str): Convert a UTF-32 encoded string to UTF-8.
size_t convertUtf8StringToUtf16(const char *str, char16_t *out, size_t outLen) noexcept: Convert a UTF-8 encoded string to UTF-16.
std::u16string convertUtf8StringToUtf16(std::string str): Convert a UTF-8 encoded string to UTF-16.
std::u16string convertUtf8StringToUtf16(const char *str): Convert a UTF-8 encoded string to UTF-16.
std::u32string convertUtf8StringToUtf32(std::string str): Convert a UTF-8 encoded string to UTF-32.
size_t convertUtf8StringToUtf32(const char *str, char32_t *out, size_t outLen) noexcept: Convert a UTF-8 encoded string to UTF-32.
std::u32string convertUtf8StringToUtf32(const char *str): Convert a UTF-8 encoded string to UTF-32.
size_t convertUtf8StringToWide(const char *str, wchar_t *out, size_t outLen) noexcept: Convert a UTF-8 encoded string to wide string.
std::wstring convertUtf8StringToWide(std::string str): Convert a UTF-8 encoded string to UTF-16.
std::wstring convertUtf8StringToWide(const char *str): Convert a UTF-8 encoded string to wide.
std::string convertWideStringToUtf8(std::wstring str): Convert a UTF-8 encoded string to UTF-16.
size_t convertWideStringToUtf8(const wchar_t *str, char *out, size_t outLen) noexcept: Convert a wide encoded string to UTF-8 string.
std::string convertWideStringToUtf8(const wchar_t *str): Convert a UTF-8 encoded string to wide.
std::string convertWinApiErrorCodeToMessage(WinApiErrorType errorCode): (Windows only) Converts a Win32 API error code into a human-readable string.
std::string convertWindowsToCarbonitePath(const std::wstring &pathW): (Windows only) Converts Windows system file path to a UTF-8 file path.
size_t copyStringSafe(char *dstBuf, size_t dstBufSize, const char *srcString): Copy a string with optional truncation.
size_t copyStringSafe(char *dstBuf, size_t dstBufSize, const char *srcString, size_t maxCharacterCount): Copy slice of string with optional truncation.
std::string createLibraryNameForModule(carb::cpp::string_view baseName): Creates a full library name from a module's base name.
size_t debugBacktrace(size_t skipFrames, void **array, size_t count) noexcept: Attempts to capture the callstack for the current thread.
void debugPrint(const char *fmt,…): Prints a formatted string to debug output.
void debuggerBreak(void): Performs a software breakpoint if a debugger is currently attached to this process.
std::wstring fixWindowsPathPrefix(const std::wstring &pathW): (Windows only) Performs fixup on a Windows file path by adding or removing the long path prefix as necessary.
size_t formatString(char *dstBuf, size_t dstBufSize, const char *fmtString,…): A snprintf wrapper that clamps the return value.
size_t formatStringV(char *dstBuf, size_t dstBufSize, const char *fmtString, va_list argsList): A vsnprintf wrapper that clamps the return value.
void getAppPathAndName(const std::map< std::string, std::string > &stringMap, std::string &appPath, std::string &appName): Determines application path and name.
size_t getCurrentProcessMemoryUsage(): Retrieve the physical memory usage by the current process.
constexpr const char * getDefaultLibraryExtension(): Retrieves the default library file extension for the current platform.
constexpr const char * getDefaultLibraryPrefix(): Retrieves the default library file prefix for the current platform.
const char * getDistroName(): Retrieves the platform distro name.
double getFriendlyMemorySize(size_t bytes, const char **suffix, MemoryScaleType scale=MemoryScaleType::eBinaryScale): Retrieves a friendly memory size and scale suffix for a given number of bytes.
ErrnoType getLastErrno() noexcept: Returns the last value of errno.
std::string getLastErrnoMessage(ErrnoType *out=nullptr): Reads the current value of errno and returns a human-readable string for the errno value.
std::string getLastLoadLibraryError(): Retrieves a string explaining the most recent library load failure cause.
WinApiErrorType getLastWinApiErrorCode() noexcept: Platform specific functions ///.
std::string getLastWinApiErrorMessage(): (Windows only) Reads the value of GetLastError() and converts it to a human-readable string.
std::string getLibraryDirectory(void *symbolAddress): Retrieves the parent directory of the library containing a given address or symbol.
std::string getLibraryDirectoryByHandle(LibraryHandle handle): Retrieves the parent directory of a library.
std::string getLibraryFilename(const void *symbolAddress): Retrieves the path for a loaded library from an address or symbol within it.
std::string getLibraryFilenameByHandle(LibraryHandle handle): Retrieves the path for a loaded library from its handle.
LibraryHandle getLibraryHandle(const void *symbolAddress): Retrieves the handle for a loaded library from an address or symbol within it.
LibraryHandle getLibraryHandleByFilename(const char *libraryName, LibraryFlags flags=0): Attempts to retrieve a library's handle by its filename.
T getLibrarySymbol(LibraryHandle libHandle, const char *name): Attempts to retrieve the address of a symbol from a loaded module.
size_t getMemorySizeMultiplier(const char *str): Retrieves the memory size multiplier from a value suffix.
size_t getMemoryValueByName(const char *filename, const char *name, size_t nameLen=0): Retrieves a memory value by its key name in '/proc/meminfo' or other.
Path getPathExtension(std::string path): Helper function to get a Path object representing the extension part of the provided string representation of a path.
Path getPathParent(std::string path): Helper function to get a Path object representing parent directory for the provided string representation of a path.
Path getPathRelative(std::string path, std::string base): Helper function to calculate a relative path from a provided path and a base path.
Path getPathStem(std::string path): Helper function to get a Path object representing the stem part of the provided string representation of a path.
size_t getPeakProcessMemoryUsage(): Retrieves the peak memory usage information for the calling process.
size_t getPhysicalMemory(MemoryQueryType type): Retrieve the physical memory available on the system.
std::string getStringFromMapOrEnvVar(const char *stringMapKey, const std::map< std::string, std::string > &stringMap, const char *envVarName): Helper function that reads string value form the string map or the environment variable, if map doesn't hold such key.
bool getSystemMemoryInfo(SystemMemoryInfo &out): Retrieves the memory usage information for the system.
std::wstring getWindowsCanonicalPath(const std::wstring &pathW): (Windows only) Converts Windows path string into a canonical form.
std::wstring getWindowsFullPath(const std::wstring &pathW): (Windows only) Retrieves the full path and file name of the specified file.
bool isCiEnvironment(): Checks if this process is running under a CI system such as TeamCity or GitLab.
bool isDebuggerAttached(void): Checks if a debugger is attached to the calling process.
bool isMemoryOverlap(const void *ptr1, size_t size1, const void *ptr2, size_t size2): Check if two memory regions overlaps.
bool isRunningOnCentos(): Checks whether the calling process is running on CentOS.
bool isRunningOnUbuntu(): Checks whether the calling process is running on Ubuntu.
bool isStringPrefix(const char *str, const char *prefix): Test if one string is a prefix of the other.
bool isTestEnvironment(): Queries whether the calling process is the Carbonite unit tests.
LibraryHandle loadLibrary(const char *libraryName, LibraryFlags flags=0): Attempts to load a named library into the calling process.
bool operator!=(std::nullptr_t, const HandleRef< Mapped, Handle, Allocator > &ref): Tests inequality between HandleRef and nullptr .
bool operator!=(const HandleRef< Mapped, Handle, Allocator > &ref, std::nullptr_t): Tests inequality between HandleRef and nullptr .
bool operator!=(const std::string &left, const Path &right): Inequality operator.
bool operator!=(const char *left, const Path &right): Inequality operator.
Path operator+(const omni::string &left, const Path &right): Concatenation operator.
Path operator+(const std::string &left, const Path &right): Concatenation operator.
Path operator+(const Path &left, const std::string &right): Concatenation operator.
Path operator+(const char *left, const Path &right): Concatenation operator.
Path operator+(const Path &left, const char *right): Concatenation operator.
Path operator+(const Path &left, const Path &right): Concatenation operator.
Path operator+(const Path &left, const omni::string &right): Concatenation operator.
Path operator/(const Path &left, const Path &right): Join operator.
bool operator==(const std::string &left, const Path &right): Equality operator.
bool operator==(const HandleRef< Mapped, Handle, Allocator > &ref, std::nullptr_t): Tests equality between HandleRef and nullptr .
bool operator==(const char *left, const Path &right): Equality operator.
bool operator==(std::nullptr_t, const HandleRef< Mapped, Handle, Allocator > &ref): Tests equality between HandleRef and nullptr .
void registerPathAlias(const char *alias, const char *value): Registers a new path string alias for replacement with resolvePathAliases() .
std::string resolvePathAliases(const char *srcBuf): Replaces path alias markers in a path with the full names.
void unloadLibrary(LibraryHandle libraryHandle): Unloads a loaded library.
void unregisterPathAlias(const char *alias): Unregisters a path string alias.
void withFormatNV(const char *fmt, va_list ap, Callable &&c) noexcept: Formats as with vsnprintf() and calls a Callable with the result and the size.
void withFormatV(const char *fmt, va_list ap, Callable &&c): Formats as with vsnprintf() and calls a Callable with the result.

Structs#

ConstHandleRef: A smart-reference class for a Handle associated with a HandleDatabase .
HandleRef: A smart-reference class for a Handle associated with a HandleDatabase .
SystemMemoryInfo: Stores information about memory in the system.

Typedefs#

ErrnoType: The decayed type of errno
LibraryFlags: Base type for the flags to control how libraries are loaded.
LibraryHandle: Handle to a loaded library.
ScopedHandleRef: Deprecated: Use HandleRef instead.
WinApiErrorType: (Windows only) The type of value returned from GetLastError()

Variables#

constexpr LibraryFlags fLibFlagDeepBind: Flag to indicate that the symbols in the library being loaded should be linked to first and take precedence over global scope symbols of the same name from other libraries.
constexpr LibraryFlags fLibFlagLoadExisting: Flag to indicate that a valid library handle should only be returned if the requested library was already loaded into the process.
constexpr LibraryFlags fLibFlagMakeFullLibName: Flag to indicate that only the module's base name was given and that the full name should be constructed using createLibraryNameForModule() before attempting to load the library.
constexpr LibraryFlags fLibFlagNow: Flag to indicate that the library should be fully loaded and linked immediately.
constexpr LibraryFlags fLibFlagPin: Flag to indicate that the library should be "pinned"; that is, it should stay loaded until the process is terminated.
constexpr LibraryHandle kInvalidLibraryHandle: A value representing an invalid library handle.