VCV Rack API v2
Loading...
Searching...
No Matches
Functions
rack::system Namespace Reference

Cross-platform functions for OS, file path, and filesystem routines. More...

Functions

std::string join (const std::string &path1, const std::string &path2="")
 Joins two paths with a directory separator.
 
template<typename... Paths>
std::string join (const std::string &path1, const std::string &path2, Paths... paths)
 Join an arbitrary number of paths, from left to right.
 
std::vector< std::string > getEntries (const std::string &dirPath, int depth=0)
 Returns all entries (directories, files, symbolic links, etc) in a directory.
 
bool exists (const std::string &path)
 
bool isFile (const std::string &path)
 Returns whether the given path is a file.
 
bool isDirectory (const std::string &path)
 Returns whether the given path is a directory.
 
uint64_t getFileSize (const std::string &path)
 
bool rename (const std::string &srcPath, const std::string &destPath)
 Moves a file or directory.
 
bool copy (const std::string &srcPath, const std::string &destPath)
 Copies a file or directory recursively.
 
bool createDirectory (const std::string &path)
 Creates a directory.
 
bool createDirectories (const std::string &path)
 Creates all directories up to the path.
 
bool createSymbolicLink (const std::string &target, const std::string &link)
 
bool remove (const std::string &path)
 Deletes a file or empty directory.
 
int removeRecursively (const std::string &path)
 Deletes a file or directory recursively.
 
std::string getWorkingDirectory ()
 
void setWorkingDirectory (const std::string &path)
 
std::string getTempDirectory ()
 
std::string getAbsolute (const std::string &path)
 Returns the absolute path beginning with "/".
 
std::string getCanonical (const std::string &path)
 Returns the canonical (unique) path, following symlinks and "." and ".." fake directories.
 
std::string getDirectory (const std::string &path)
 Extracts the parent directory of the path.
 
std::string getFilename (const std::string &path)
 Extracts the filename of the path.
 
std::string getStem (const std::string &path)
 Extracts the portion of a filename without the extension.
 
std::string getExtension (const std::string &path)
 Extracts the extension of a filename, including the dot.
 
std::vector< uint8_t > readFile (const std::string &path)
 Reads an entire file into a memory buffer.
 
uint8_t * readFile (const std::string &path, size_t *size)
 
void writeFile (const std::string &path, const std::vector< uint8_t > &data)
 Writes a memory buffer to a file, overwriting if already exists.
 
void archiveDirectory (const std::string &archivePath, const std::string &dirPath, int compressionLevel=1)
 Compresses the contents of a directory (recursively) to an archive.
 
std::vector< uint8_t > archiveDirectory (const std::string &dirPath, int compressionLevel=1)
 
void unarchiveToDirectory (const std::string &archivePath, const std::string &dirPath)
 Extracts an archive into a directory.
 
void unarchiveToDirectory (const std::vector< uint8_t > &archiveData, const std::string &dirPath)
 
int getLogicalCoreCount ()
 Returns the number of logical simultaneous multithreading (SMT) (e.g.
 
void setThreadName (const std::string &name)
 Sets a name of the current thread for debuggers and OS-specific process viewers.
 
std::string getStackTrace ()
 Returns the caller's human-readable stack trace with "\n"-separated lines.
 
double getTime ()
 Returns the number of seconds since application launch.
 
double getUnixTime ()
 Returns time since 1970-01-01 00:00:00 UTC in seconds.
 
double getThreadTime ()
 
void sleep (double time)
 
std::string getOperatingSystemInfo ()
 
void openBrowser (const std::string &url)
 Opens a URL in a browser.
 
void openDirectory (const std::string &path)
 Opens Windows Explorer, Finder, etc at a directory location.
 
void runProcessDetached (const std::string &path)
 Runs an executable without blocking.
 
uint32_t getFpuFlags ()
 Returns the CPU's floating point unit control flags.
 
void setFpuFlags (uint32_t flags)
 
void resetFpuFlags ()
 Sets Rack-recommended FPU flags for the current thread.
 
PRIVATE void init ()
 

Detailed Description

Cross-platform functions for OS, file path, and filesystem routines.

Function Documentation

◆ join() [1/2]

std::string rack::system::join ( const std::string & path1,
const std::string & path2 = "" )

Joins two paths with a directory separator.

If path2 is an empty string, returns path1.

◆ join() [2/2]

template<typename... Paths>
std::string rack::system::join ( const std::string & path1,
const std::string & path2,
Paths... paths )

Join an arbitrary number of paths, from left to right.

◆ getEntries()

std::vector< std::string > rack::system::getEntries ( const std::string & dirPath,
int depth = 0 )

Returns all entries (directories, files, symbolic links, etc) in a directory.

depth is the number of directories to recurse. 0 depth does not recurse. -1 depth recurses infinitely.

◆ exists()

bool rack::system::exists ( const std::string & path)

◆ isFile()

bool rack::system::isFile ( const std::string & path)

Returns whether the given path is a file.

◆ isDirectory()

bool rack::system::isDirectory ( const std::string & path)

Returns whether the given path is a directory.

◆ getFileSize()

uint64_t rack::system::getFileSize ( const std::string & path)

◆ rename()

bool rack::system::rename ( const std::string & srcPath,
const std::string & destPath )

Moves a file or directory.

Does not overwrite the destination. If this behavior is needed, use remove() or removeRecursively() before moving. Returns whether the rename was successful.

◆ copy()

bool rack::system::copy ( const std::string & srcPath,
const std::string & destPath )

Copies a file or directory recursively.

Overwrites destination if already exists. Returns whether the copy was successful.

◆ createDirectory()

bool rack::system::createDirectory ( const std::string & path)

Creates a directory.

The parent directory must exist. Returns whether the creation was successful.

◆ createDirectories()

bool rack::system::createDirectories ( const std::string & path)

Creates all directories up to the path.

Returns whether the creation was successful.

◆ createSymbolicLink()

bool rack::system::createSymbolicLink ( const std::string & target,
const std::string & link )

◆ remove()

bool rack::system::remove ( const std::string & path)

Deletes a file or empty directory.

Returns whether the deletion was successful.

◆ removeRecursively()

int rack::system::removeRecursively ( const std::string & path)

Deletes a file or directory recursively.

Returns the number of files and directories that were deleted.

◆ getWorkingDirectory()

std::string rack::system::getWorkingDirectory ( )

◆ setWorkingDirectory()

void rack::system::setWorkingDirectory ( const std::string & path)

◆ getTempDirectory()

std::string rack::system::getTempDirectory ( )

◆ getAbsolute()

std::string rack::system::getAbsolute ( const std::string & path)

Returns the absolute path beginning with "/".

◆ getCanonical()

std::string rack::system::getCanonical ( const std::string & path)

Returns the canonical (unique) path, following symlinks and "." and ".." fake directories.

The path must exist on the filesystem. Examples: getCanonical("/foo/./bar/.") // "/foo/bar"

◆ getDirectory()

std::string rack::system::getDirectory ( const std::string & path)

Extracts the parent directory of the path.

Examples: getDirectory("/var/tmp/example.txt") // "/var/tmp" getDirectory("/") // "" getDirectory("/var/tmp/.") // "/var/tmp"

◆ getFilename()

std::string rack::system::getFilename ( const std::string & path)

Extracts the filename of the path.

Examples: getFilename("/foo/bar.txt") // "bar.txt" getFilename("/foo/.bar") // ".bar" getFilename("/foo/bar/") // "." getFilename("/foo/.") // "." getFilename("/foo/..") // ".." getFilename(".") // "." getFilename("..") // ".." getFilename("/") // "/"

◆ getStem()

std::string rack::system::getStem ( const std::string & path)

Extracts the portion of a filename without the extension.

Examples: getStem("/foo/bar.txt") // "bar" getStem("/foo/.bar") // "" getStem("/foo/foo.tar.ztd") // "foo.tar"

◆ getExtension()

std::string rack::system::getExtension ( const std::string & path)

Extracts the extension of a filename, including the dot.

Examples: getExtension("/foo/bar.txt") // ".txt" getExtension("/foo/bar.") // "." getExtension("/foo/bar") // "" getExtension("/foo/bar.txt/bar.cc") // ".cc" getExtension("/foo/bar.txt/bar.") // "." getExtension("/foo/bar.txt/bar") // "" getExtension("/foo/.") // "" getExtension("/foo/..") // "" getExtension("/foo/.hidden") // ".hidden"

◆ readFile() [1/2]

std::vector< uint8_t > rack::system::readFile ( const std::string & path)

Reads an entire file into a memory buffer.

Throws on error.

◆ readFile() [2/2]

uint8_t * rack::system::readFile ( const std::string & path,
size_t * size )

◆ writeFile()

void rack::system::writeFile ( const std::string & path,
const std::vector< uint8_t > & data )

Writes a memory buffer to a file, overwriting if already exists.

Throws on error.

◆ archiveDirectory() [1/2]

void rack::system::archiveDirectory ( const std::string & archivePath,
const std::string & dirPath,
int compressionLevel = 1 )

Compresses the contents of a directory (recursively) to an archive.

Uses the Unix Standard TAR + Zstandard format (.tar.zst). An equivalent shell command is 

tar -c -C dirPath . | zstd -1 -o archivePath

or 

ZSTD_CLEVEL=1 tar -cf archivePath --zstd -C dirPath .

Throws on error.

◆ archiveDirectory() [2/2]

std::vector< uint8_t > rack::system::archiveDirectory ( const std::string & dirPath,
int compressionLevel = 1 )

◆ unarchiveToDirectory() [1/2]

void rack::system::unarchiveToDirectory ( const std::string & archivePath,
const std::string & dirPath )

Extracts an archive into a directory.

An equivalent shell command is 

zstd -d < archivePath | tar -x -C dirPath

or 

tar -xf archivePath --zstd -C dirPath

As a special case, zero-byte files in the archive cause the unarchiver to delete existing files instead of overwriting them. This is useful for removing presets in .vcvplugin packages, for example.

Throws on error.

◆ unarchiveToDirectory() [2/2]

void rack::system::unarchiveToDirectory ( const std::vector< uint8_t > & archiveData,
const std::string & dirPath )

◆ getLogicalCoreCount()

int rack::system::getLogicalCoreCount ( )

Returns the number of logical simultaneous multithreading (SMT) (e.g.

Intel Hyperthreaded) threads on the CPU.

◆ setThreadName()

void rack::system::setThreadName ( const std::string & name)

Sets a name of the current thread for debuggers and OS-specific process viewers.

◆ getStackTrace()

std::string rack::system::getStackTrace ( )

Returns the caller's human-readable stack trace with "\n"-separated lines.

◆ getTime()

double rack::system::getTime ( )

Returns the number of seconds since application launch.

Gives the most precise (fine-grained) monotonic (non-decreasing) time differences available on the OS for benchmarking purposes, while being fast to compute.

◆ getUnixTime()

double rack::system::getUnixTime ( )

Returns time since 1970-01-01 00:00:00 UTC in seconds.

◆ getThreadTime()

double rack::system::getThreadTime ( )

◆ sleep()

void rack::system::sleep ( double time)

◆ getOperatingSystemInfo()

std::string rack::system::getOperatingSystemInfo ( )

◆ openBrowser()

void rack::system::openBrowser ( const std::string & url)

Opens a URL in a browser.

Shell injection is possible, so make sure the URL is trusted or hard coded. Does nothing if string is blank. Does not block.

◆ openDirectory()

void rack::system::openDirectory ( const std::string & path)

Opens Windows Explorer, Finder, etc at a directory location.

Does nothing if string is blank. Does not block.

◆ runProcessDetached()

void rack::system::runProcessDetached ( const std::string & path)

Runs an executable without blocking.

The launched process will continue running if the current process is closed.

◆ getFpuFlags()

uint32_t rack::system::getFpuFlags ( )

Returns the CPU's floating point unit control flags.

MXCSR register on x64, and the FPCR register on ARM64.

◆ setFpuFlags()

void rack::system::setFpuFlags ( uint32_t flags)

◆ resetFpuFlags()

void rack::system::resetFpuFlags ( )

Sets Rack-recommended FPU flags for the current thread.

◆ init()

PRIVATE void rack::system::init ( )