cosmos::PidFD Class Reference

A specialized FileDescriptor for pidfds. More...

#include <PidFD.hxx>

Inheritance diagram for cosmos::PidFD:

Public Member Functions
	PidFD (FileNum fd=FileNum::INVALID)
Public Member Functions inherited from cosmos::FileDescriptor
constexpr	FileDescriptor (FileNum fd)
bool	valid () const
	Returns whether currently a valid file descriptor number is assigned.
bool	invalid () const
void	setFD (const FileNum fd)
	Assigns a new primitive file descriptor to the object.
void	reset ()
	Invalidates the stored file descriptor.
void	close ()
	Explicitly close the contained FD.
void	duplicate (const FileDescriptor new_fd, const CloseOnExec cloexec=CloseOnExec{true}) const
	Get a duplicate file descriptor that will further be known as new_fd.
FileDescriptor	duplicate (const FileNum lowest=FileNum{0}, const CloseOnExec cloexec=CloseOnExec{true}) const
	Get a duplicate file descriptor using the lowest available free file descriptor number.
DescFlags	getFlags () const
	Retrieves the current file descriptor flags.
void	setFlags (const DescFlags flags)
	Changes the current file descriptor flags.
void	setCloseOnExec (bool on_off)
	convenience wrapper around setFlags to change CLOEXEC setting
std::tuple< OpenMode, OpenFlags >	getStatusFlags () const
	Retrieve the file's OpenMode and current OpenFlags.
void	setStatusFlags (const OpenFlags flags)
	Change certain file descriptor status flags.
void	sync ()
	Flush oustanding writes to disk.
void	dataSync ()
	Flush outstanding writes to disk except metadata.
void	addSeals (const SealFlags flags)
	Add a seal for memory file descriptors.
SealFlags	getSeals () const
	Get the currently set SealFlags for the file descriptor.
int	getPipeSize () const
	For pipe file descriptors return the size of the pipe buffer in the kernel.
int	setPipeSize (const int new_size)
	For pipe file descriptors this sets a new size for the pipe buffer in the kernel.
FileNum	raw () const
	Returns the primitive file descriptor contained in the object.
bool	operator== (const FileDescriptor &other) const
bool	operator!= (const FileDescriptor &other) const
bool	getLock (FileLock &lock) const
	Check lock availability for traditional process-wide POSIX locks.
bool	setLock (const FileLock &lock) const
	Release, or attempt to obtain, a traditional process-wide POSIX lock.
void	setLockWait (const FileLock &lock) const
	Blocking version of setLock().
bool	getOFDLock (FileLock &lock) const
	Just like getLock() but using open-file-description locks.
bool	setOFDLock (const FileLock &lock) const
	Just like setLock() but using open-file-description locks.
void	setOFDLockWait (const FileLock &lock) const
	Just like setLockWait() but using open-file-description locks.
void	getOwner (Owner &owner) const
	Returns the current file descriptor owner settings.
void	setOwner (const Owner owner)
	Change the current file descriptor owner settings.
std::optional< Signal >	getSignal () const
	Returns the currently configured signal for asynchronous I/O.
void	setSignal (std::optional< Signal > sig)
	Configure the signal to be used for asynchronous I/O.
LeaseType	getLease () const
	Gets the lease type currently set, or required to resolve a lease break.
void	setLease (const LeaseType lease)
	Sets a new lease type on the file descriptor.

Friends
struct	CloneArgs

Additional Inherited Members
Public Types inherited from cosmos::FileDescriptor
enum class	DescFlag : int { NONE = 0 , CLOEXEC = FD_CLOEXEC }
	Configurable per file-descriptors flags. More...
enum class	SealFlag : unsigned int {   SEAL = F_SEAL_SEAL , SHRINK = F_SEAL_SHRINK , GROW = F_SEAL_GROW , WRITE = F_SEAL_WRITE ,   FUTURE_WRITE = F_SEAL_FUTURE_WRITE }
	Flags used in addSeals(). More...
enum class	LeaseType : int { READ = F_RDLCK , WRITE = F_WRLCK , UNLOCK = F_UNLCK }
	Different request types for managing file leases. More...
using	DescFlags = BitMask<DescFlag>
	Collection of OpenFlag used for opening files.
using	SealFlags = BitMask<SealFlag>
	Collection flags for applying seals in addSeals().
Protected Member Functions inherited from cosmos::FileDescriptor
int	fcntl (int cmd) const
template<typename T >
int	fcntl (int cmd, T val) const
Protected Attributes inherited from cosmos::FileDescriptor
FileNum	m_fd = FileNum::INVALID

Detailed Description

A specialized FileDescriptor for pidfds.

A file descriptor representing a process in the system. These can be used to refer to or interact with other processes in the system in a race-free fashion (compared to accessing /proc or specifying ProcessIDs, for example).

This is just a thin wrapper around the file descriptor that does not offer specific operations or lifetime management. Use cosmos::ProcessFile for this.

A PidFD can be obtained via cosmos::ProcessFile or from proc::clone(). The uses of a PidFD are the following:

• send a signal to the represented process
• monitor process termination using (e)poll or select, used e.g. in cosmos::SubProc. There is a limitation: the file descriptor will appear as readable when the process can be waited on in the poll API, but it won't actually return any data when reading from it.
• it can be waited on using proc::wait(), but only if the process is a child of the calling process.
• it can be used to obtain a file descriptor from the represented process, see proc::getFD().
• it can be used to enter any namespaces of the target process using setns().
• it can be used with process_madvise() to inform the kernel about memory usage patterns of the target process.

Definition at line 35 of file PidFD.hxx.

Constructor & Destructor Documentation

PidFD()

cosmos::PidFD::PidFD ( FileNum fd = FileNum::INVALID )

inlineexplicit

Definition at line 41 of file PidFD.hxx.

                                                    :
                        FileDescriptor{fd}
        {}

Friends And Related Symbol Documentation

CloneArgs

friend struct CloneArgs

friend

Definition at line 38 of file PidFD.hxx.

---

The documentation for this class was generated from the following file:

• include/proc/PidFD.hxx