AFIO  v2.00 late alpha
afio_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_pathall_temporary_directories (bool refresh=false) noexcept
 Returns a list of potential directories which might be usuable for temporary files. More...
 
span< discovered_pathverified_temporary_directories () 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_handlestorage_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...
 
const path_handlememory_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...
 

Detailed Description

Contains functions used to discover suitable paths for things.

Function Documentation

◆ all_temporary_directories()

span<discovered_path> afio_v2_xxx::path_discovery::all_temporary_directories ( bool  refresh = false)
inlinenoexcept

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

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.

Memory Allocations
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
This call never fails, except to return an empty span.

◆ memory_backed_temporary_files_directory()

const path_handle& afio_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 iterating all of the paths returned by verified_temporary_directories() and checking what file system is in use. The following regex is used:

tmpfs|ramfs

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.

◆ storage_backed_temporary_files_directory()

const path_handle& afio_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 iterating all of the paths returned by verified_temporary_directories() and checking what file system is in use. The following regex is used:

btrfs|cifs|exfat|ext?|f2fs|hfs|jfs|lxfs|nfs|nilf2|ufs|vfat|xfs|zfs|msdosfs|newnfs|ntfs|smbfs|unionfs|fat|fat32

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

◆ verified_temporary_directories()

span<discovered_path> afio_v2_xxx::path_discovery::verified_temporary_directories ( )
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.

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
None.
Errors returnable
This call never fails, though if it fails to find any writable temporary directory, it will terminate the process.