cosmos::ProcessFile Class Reference

Wrapper around a PidFD. More...

#include <ProcessFile.hxx>

Public Types
enum class	OpenFlag : unsigned int { NONBLOCK = PIDFD_NONBLOCK }
using	OpenFlags = BitMask<OpenFlag>

Public Member Functions
	ProcessFile (const ProcessID pid, const OpenFlags flags=OpenFlags{})
	Creates a new coupling to the given process ID.
	ProcessFile (const PidFD fd)
	Wraps the given PidFD and takes ownership of it.
	ProcessFile (const ProcessFile &)=delete
ProcessFile &	operator= (const ProcessFile &)=delete
	ProcessFile (ProcessFile &&other) noexcept
ProcessFile &	operator= (ProcessFile &&other) noexcept
bool	open () const
	Returns whether a pidfd is currently open.
void	close ()
PidFD	fd () const
	Returns the raw PidFD file descriptor.
void	sendSignal (const Signal sig) const
	Send a signal to the represented process.
FileDescriptor	dupFD (const FileNum targetfd) const
	Duplicate a file descriptor from the target process into the current process.
std::optional< ChildData >	wait (const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Wait for the child process to exit.

Protected Attributes
PidFD	m_fd

Detailed Description

Wrapper around a PidFD.

This wraps a PidFD just like a File object wraps a FileDescriptor. It adds lifetime handling i.e. closes the PidFD when no longer needed and also offers domain specific operations that can be performed on the PidFD.

Definition at line 22 of file ProcessFile.hxx.

Member Typedef Documentation

OpenFlags

using cosmos::ProcessFile::OpenFlags = BitMask<OpenFlag>

Definition at line 29 of file ProcessFile.hxx.

Member Enumeration Documentation

OpenFlag

enum class cosmos::ProcessFile::OpenFlag : unsigned int

strong

Enumerator
NONBLOCK	open the file descriptor in non-blocking mode - proc::wait() will never block.

Definition at line 25 of file ProcessFile.hxx.

                            : unsigned int {
                NONBLOCK = PIDFD_NONBLOCK 
        };

Constructor & Destructor Documentation

ProcessFile() [1/3]

cosmos::ProcessFile::ProcessFile ( const ProcessID pid, const OpenFlags flags = OpenFlags{} )

explicit

Creates a new coupling to the given process ID.

Note that creating a PidFD this way is often subject to race conditions i.e. the process with the given pid might be replaced by a different one than you expect.

It can be safe if pid is a child process of the calling process and no other thread is calling any of the wait family of functions to cleanup the child process in case it exits.

Definition at line 31 of file ProcessFile.cxx.

                                                                   {
        auto fd = pidfd_open(to_integral(pid), flags.raw());
 
        if (fd == -1) {
                cosmos_throw (ApiError("pidfd_open()"));
        }
 
        m_fd.setFD(FileNum{fd});
}

ProcessFile() [2/3]

cosmos::ProcessFile::ProcessFile ( const PidFD fd )

inlineexplicit

Wraps the given PidFD and takes ownership of it.

The given fd will be owned by the new ProcessFile object. This means that ProcessFile will close() it if it deems this necessary.

The only way currently to obtain fd is via proc::clone().

Definition at line 52 of file ProcessFile.hxx.

                                             :
                        m_fd{fd}
        {}

ProcessFile() [3/3]

cosmos::ProcessFile::ProcessFile ( ProcessFile && other )

inlinenoexcept

Definition at line 61 of file ProcessFile.hxx.

                                                  {
                *this = std::move(other);
        }

~ProcessFile()

cosmos::ProcessFile::~ProcessFile

(

)

Definition at line 41 of file ProcessFile.cxx.

                          {
        const auto orig_fd = m_fd.raw();
 
        try {
                close();
        } catch (const std::exception &e) {
                noncritical_error(sprintf("%s: failed to close fd(%d)", __FUNCTION__, to_integral(orig_fd)), e);
        }
}

Member Function Documentation

close()

void cosmos::ProcessFile::close ( )

inline

Definition at line 78 of file ProcessFile.hxx.

                     {
                m_fd.close();
        }

dupFD()

FileDescriptor cosmos::ProcessFile::dupFD

(

const FileNum

targetfd

)

const

Duplicate a file descriptor from the target process into the current process.

This operation is similar to file descriptor passing over UNIX domain sockets. It doesn't require a socket connection though and also doesn't require the cooperation of the process the file descriptor is obtained from.

The operation requires PTRACE_MODE_ATTACH_REALCREDS credentials though, which roughly means the target process needs to run under the same user as the current process, or the current process needs to be privileged.

targetfd is the file descriptor number in the target process that should be duplicated into the current process.

The returned file descriptor will have the close-on-exec flag set.

The caller is responsible for closing the returned file descriptor at the appropriate time. It is best to wrap the file descriptor in a more specialized, managed type.

Definition at line 51 of file ProcessFile.cxx.

                                                              {
        auto fd = pidfd_getfd(to_integral(m_fd.raw()), to_integral(targetfd), 0);
 
        if (fd == -1) {
                cosmos_throw (ApiError("pidfd_getfd()"));
        }
 
        return FileDescriptor{FileNum{fd}};
}

fd()

PidFD cosmos::ProcessFile::fd ( ) const

inline

Returns the raw PidFD file descriptor.

You can use this for some operations like cosmos::proc::wait(). Make sure not to close the returned object, as ProcessFile is the owner of the file.

Definition at line 88 of file ProcessFile.hxx.

{ return m_fd; }

open()

bool cosmos::ProcessFile::open ( ) const

inline

Returns whether a pidfd is currently open.

Definition at line 74 of file ProcessFile.hxx.

                          {
                return m_fd.valid();
        }

operator=()

ProcessFile & cosmos::ProcessFile::operator= ( ProcessFile && other )

inlinenoexcept

Definition at line 65 of file ProcessFile.hxx.

                                                             {
                m_fd = other.m_fd;
                other.m_fd.reset();
                return *this;
        }

sendSignal()

void cosmos::ProcessFile::sendSignal ( const Signal sig ) const

inline

Send a signal to the represented process.

Definition at line 91 of file ProcessFile.hxx.

                                                {
                signal::send(m_fd, sig);
        }

wait()

std::optional< ChildData > cosmos::ProcessFile::wait ( const WaitFlags flags = WaitFlags{WaitFlag::WAIT_FOR_EXITED} )

inline

Wait for the child process to exit.

See also

proc::wait(const PidFD, const WaitFlags).

Definition at line 122 of file ProcessFile.hxx.

                                                                     {WaitFlag::WAIT_FOR_EXITED}) {
                return proc::wait(m_fd, flags);
        }

Member Data Documentation

m_fd

PidFD cosmos::ProcessFile::m_fd

protected

Definition at line 128 of file ProcessFile.hxx.

---

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

• include/proc/ProcessFile.hxx
• src/proc/ProcessFile.cxx