llfio_v2_xxx::path_discovery Namespace Reference

Contains functions used to discover suitable paths for things. More...

Classes
struct	discovered_path
	A discovered path. More...

Functions
std::ostream &	operator<< (std::ostream &s, const discovered_path::source_type &v)
span< discovered_path >	all_temporary_directories (bool refresh=false, span< path_view > fallbacks={}, span< path_view > overrides={}) noexcept
	Returns a list of potential directories which might be usuable for temporary files. More...
span< discovered_path >	verified_temporary_directories (const char *_storage_backed_regex=storage_backed_regex, const char *_memory_backed_regex=memory_backed_regex) noexcept
	Returns a subset of all_temporary_directories() each of which has been tested to be writable by the current process. No testing is done of available writable space. More...
const path_handle &	storage_backed_temporary_files_directory () noexcept
	Returns a reference to an open handle to a verified temporary directory where files created are stored in a filesystem directory, usually under the current user's quota. More...
bool	storage_backed_temporary_files_directory_is_networked () noexcept
	True if the storage backed temporary files directory is on a networked file system.
const path_handle &	memory_backed_temporary_files_directory () noexcept
	Returns a reference to an open handle to a verified temporary directory where files created are stored in memory/paging file, and thus access may be a lot quicker, but stronger limits on capacity may apply. More...
bool	memory_backed_temporary_files_directory_is_networked () noexcept
	True if the memory backed temporary files directory is on a networked file system.
const path_handle &	temporary_named_pipes_directory () noexcept
	Returns a reference to an open handle to a verified temporary directory where named pipes may be created and found. More...
result< path_handle >	current_working_directory () noexcept
	Returns a handle to the current working directory, which can change at any moment during a process' lifetime.
const path_handle &	starting_working_directory () noexcept
	Returns a reference to an open handle to a verified directory which was the working directory during static data init of the process before main() was invoked. More...

Detailed Description

Contains functions used to discover suitable paths for things.

Function Documentation

all_temporary_directories()

span<discovered_path> llfio_v2_xxx::path_discovery::all_temporary_directories ( bool  refresh = false, span< path_view >  fallbacks = {}, span< path_view >  overrides = {}  )

inlinenoexcept

Returns a list of potential directories which might be usuable for temporary files.

Parameters

refresh	Recalculate the list and all dependent lists, which are statically cached after first call.
fallbacks	Additional local paths to place after the discovered_path::source_type::system paths, which therefore would take preference over later discovered_path::source_type::hardcoded paths.
overrides	Additional paths to place at the beginning of the list, which therefore would take preference over all other paths.

This is a fairly lightweight call which builds a master list of all potential temporary file directories given the environment block of this process (unless SUID or SGID or Privilege Elevation are in effect) and the user running this process. It does not verify if any of them exist, or are writable, or anything else about them. An internal mutex is held for the duration of this call.

Potential temporary file directories are sourced as follows:

• POSIX:

  As per Unix guidelines, in order:

  1. If not SUID nor SUIG situation, from these environment variables in this order of preference: "TMPDIR", "TMP", "TEMP", "TEMPDIR", "XDG_RUNTIME_DIR", "XDG_CACHE_HOME" and ${HOME}/.cache.
  2. The .cache directory within the effective user's home directory (created if it doesn't exist).
  3. /tmp.
  4. /var/tmp.
  5. /run/user/<effective user id>.
  6. /run/shm.
  7. /.
• Microsoft Windows:
  1. If not SUID nor SUIG situation, from these environment variables in this order of preference: "TMP", "TEMP", "LOCALAPPDATA", "USERPROFILE".
  2. Whatever the Shell says are the paths for: ${FOLDERID_LocalAppData}\Temp, ${FOLDERID_Profile}\AppData\Local\Temp, ${FOLDERID_Profile}\Local Settings\Temp.
  3. ${GetWindowsDirectoryW()}\Temp.
  4. GetSystemWindowsDirectoryW()\..\Temp.

Memory Allocations\n Allocates the master list of discovered temporary directories exactly once per process,

unless refresh is true in which case the list will be refreshed. The system calls to retrieve paths may allocate additional memory for paths returned.

Errors returnable\n This call never fails, except to return an empty span.

memory_backed_temporary_files_directory()

const path_handle& llfio_v2_xxx::path_discovery::memory_backed_temporary_files_directory ( )

inlinenoexcept

Returns a reference to an open handle to a verified temporary directory where files created are stored in memory/paging file, and thus access may be a lot quicker, but stronger limits on capacity may apply.

This is implemented by verified_temporary_directories() iterating all of the paths returned by and checking what file system is in use, comparing it to memory_backed_regex.

The handle is created during verified_temporary_directories() and is statically cached thereafter.

Note

If you wish to create an anonymous memory-backed inode for mmap and paging tricks like mapping the same extent into multiple addresses e.g. to implement a constant time zero copy realloc(), strongly consider using a non-file-backed section_handle as this is more portable.

starting_working_directory()

const path_handle& llfio_v2_xxx::path_discovery::starting_working_directory ( )

inlinenoexcept

Returns a reference to an open handle to a verified directory which was the working directory during static data init of the process before main() was invoked.

If the directory was not readable at the time of process start, a default initialised path handle is returned. If static data init code changes the current working directory, the directory you get is undefined (depends on static data init order, which itself is undefined).

storage_backed_temporary_files_directory()

const path_handle& llfio_v2_xxx::path_discovery::storage_backed_temporary_files_directory ( )

inlinenoexcept

Returns a reference to an open handle to a verified temporary directory where files created are stored in a filesystem directory, usually under the current user's quota.

This is implemented by verified_temporary_directories() iterating all of the paths returned by and checking what file system is in use, comparing it to storage_backed_regex.

The handle is created during verified_temporary_directories() and is statically cached thereafter.

temporary_named_pipes_directory()

const path_handle& llfio_v2_xxx::path_discovery::temporary_named_pipes_directory ( )

inlinenoexcept

Returns a reference to an open handle to a verified temporary directory where named pipes may be created and found.

On Microsoft Windows, this is \Device\NamedPipe within the NT kernel namespace.

On POSIX, this is storage_backed_temporary_files_directory().

verified_temporary_directories()

span<discovered_path> llfio_v2_xxx::path_discovery::verified_temporary_directories ( const char *  _storage_backed_regex = storage_backed_regex, const char *  _memory_backed_regex = memory_backed_regex  )

inlinenoexcept

Returns a subset of all_temporary_directories() each of which has been tested to be writable by the current process. No testing is done of available writable space.

Parameters

_storage_backed_regex	The regex to use to determine which of the temporary directories are backed by storage not memory. The regex is executed case insensitively.
_memory_backed_regex	The regex to use to determine which of the temporary directories are backed by memory not storage. The regex is executed case insensitively.

After this call returns, the successfully probed entries returned by all_temporary_directories() will have their stat structure set. As the probing involves creating a non-zero sized file in each possible temporary directory to verify its validity, this is not a fast call. It is however cached statically, so the cost occurs exactly once per process, unless someone calls all_temporary_directories(true) to wipe and refresh the master list. An internal mutex is held for the duration of this call.

Memory Allocations\n None.

Errors returnable\n This call never fails, though if it fails to find any writable temporary directory, it will

terminate the process.