#include <sys/wait.h>
#include <iosfwd>
#include <optional>
#include <cosmos/BitMask.hxx>
#include <cosmos/fs/DirFD.hxx>
#include <cosmos/proc/PidFD.hxx>
#include <cosmos/proc/types.hxx>
#include <cosmos/proc/SigInfo.hxx>
#include <cosmos/string.hxx>
#include <cosmos/SysString.hxx>
#include <cosmos/types.hxx>

Classes
struct	cosmos::proc::PidInfo
	Helper type for caching PID an PPID information. More...

Typedefs
using	cosmos::WaitFlags = BitMask<WaitFlag>

using	cosmos::ChildData = SigInfo::ChildData

using	cosmos::proc::OverwriteEnv = NamedBool<struct overwrite_env_t, true>
	Helper type to specify overwrite behaviour in set_env_var().

Enumerations
enum class	cosmos::WaitFlag : int { WAIT_FOR_EXITED = WEXITED , WAIT_FOR_STOPPED = WSTOPPED , WAIT_FOR_CONTINUED = WCONTINUED , NO_HANG = WNOHANG , LEAVE_INFO = WNOWAIT }
	Different child process wait options used in the proc::wait() family of calls. More...

Functions
ProcessID	cosmos::proc::get_own_pid ()
	Returns the process ID of the current process.

ProcessID	cosmos::proc::get_parent_pid ()
	Returns the process ID of the parent of the current process.

UserID	cosmos::proc::get_real_user_id ()
	Returns the real user ID the current process is running as.

UserID	cosmos::proc::get_effective_user_id ()
	Returns the effective user ID the current process is running as.

GroupID	cosmos::proc::get_real_group_id ()
	Returns the real group ID the current process is running as.

GroupID	cosmos::proc::get_effective_group_id ()
	Returns the effective group ID the current process is running as.

ProcessGroupID	cosmos::proc::get_own_process_group ()
	Returns the process group ID of the caller.

ProcessID	cosmos::proc::create_new_session ()
	Creates a new session with the current process as leader.

std::optional< ProcessID >	cosmos::proc::fork ()
	Fork the current process to create a child process.

std::optional< ChildData >	cosmos::proc::wait (const ProcessID pid, const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Wait on the child process identified by `pid`.

std::optional< ChildData >	cosmos::proc::wait (const ProcessGroupID pgid, const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Wait for any process from the given process group.

std::optional< ChildData >	cosmos::proc::wait (const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Wait for any child process of the calling process.

std::optional< ChildData >	cosmos::proc::wait (const PidFD fd, const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Wait for the process referred to by the given pidfd.

void	cosmos::proc::exec (const SysString path, const CStringVector args=nullptr, const CStringVector env=nullptr)
	Replace the current process by executing the program found in `path`.

void	cosmos::proc::exec (const SysString path, const StringViewVector &args, const StringViewVector *env=nullptr)
	Variant of exec(const SysString, const CStringVector, const CStringVector) that takes StringViewVector.

void	cosmos::proc::exec_at (const DirFD dir_fd, const SysString path, const CStringVector args=nullptr, const CStringVector env=nullptr, const FollowSymlinks follow_symlinks=FollowSymlinks{false})
	Variant of exec() that looks up a program relative to `dir_fd`.

void	cosmos::proc::fexec (const FileDescriptor fd, const CStringVector args=nullptr, const CStringVector env=nullptr)
	Variant of exec() that executes the program referred to by the given file descriptor.

void	cosmos::proc::exit (ExitStatus status)
	Immediately terminate the calling process.

std::optional< SysString >	cosmos::proc::get_env_var (const SysString name)
	Returns the value for the environment variable named `name`.

bool	cosmos::proc::exists_env_var (const SysString name)
	Returns whether the given environment variable exists, ignoring its content.

void	cosmos::proc::set_env_var (const SysString name, const SysString val, const OverwriteEnv overwrite)
	Insert or replace an environment variable.

void	cosmos::proc::clear_env_var (const SysString name)
	Remove the given environment variable.

COSMOS_API std::ostream &	operator<< (std::ostream &o, const cosmos::ChildData &data)
	Outputs a human readable summary of ChildData.

Detailed Description

Various process related functionality

Definition in file process.hxx.

Typedef Documentation

◆ ChildData

using cosmos::ChildData = SigInfo::ChildData

Definition at line 57 of file process.hxx.

◆ OverwriteEnv

using cosmos::proc::OverwriteEnv = NamedBool<struct overwrite_env_t, true>

Helper type to specify overwrite behaviour in set_env_var().

Definition at line 258 of file process.hxx.

◆ WaitFlags

using cosmos::WaitFlags = BitMask<WaitFlag>

Definition at line 51 of file process.hxx.

Enumeration Type Documentation

◆ WaitFlag

enum class cosmos::WaitFlag : int

strong

Different child process wait options used in the proc::wait() family of calls.

Enumerator
WAIT_FOR_EXITED	Wait for child processes that have terminated.
WAIT_FOR_STOPPED	Wait for child processes that have been stopped due to being signaled.
WAIT_FOR_CONTINUED	Wait for (previously stopped) child processes that have been continued via SIGCONT.
NO_HANG	If no matching child processes are available don't block but return nothing.
LEAVE_INFO	Don't remove the info from the kernel, a later wait call can be used to retrieve the same information.

Definition at line 38 of file process.hxx.

                    : int {
        WAIT_FOR_EXITED    = WEXITED,
        WAIT_FOR_STOPPED   = WSTOPPED,
        WAIT_FOR_CONTINUED = WCONTINUED,
        NO_HANG            = WNOHANG,
        LEAVE_INFO         = WNOWAIT
};

Function Documentation

◆ clear_env_var()

COSMOS_API void cosmos::proc::clear_env_var ( const SysString name )

Remove the given environment variable.

This removes the environment variable named name from the calling process's environment. If no such variable exists then nothing happens and the function succeeds.

This call can fail with an exception (e.g. if the name contains invalid characters).

Definition at line 217 of file process.cxx.

                                         {
        const auto res = ::unsetenv(name.raw());
 
        if (res != 0) {
                cosmos_throw (ApiError("unsetenv()"));
        }
}

◆ create_new_session()

COSMOS_API ProcessID cosmos::proc::create_new_session ( )

Creates a new session with the current process as leader.

The session will also receive a new process group of which the current process also is the leader. The new session ID is returned from this function.

This will not work if the current process is already a process group leader, which will cause an exception to the thrown.

The new session will not yet have a controlling terminal.

Definition at line 48 of file process.cxx.

                               {
        auto res = ProcessID{::setsid()};
 
        if (res == ProcessID::INVALID) {
                cosmos_throw (ApiError("setsid()"));
        }
 
        return res;
}

◆ exec() [1/2]

COSMOS_API void cosmos::proc::exec	(	const SysString	path,
		const CStringVector *	args = nullptr,
		const CStringVector *	env = nullptr )

Replace the current process by executing the program found in path.

The given path specifies the new executable to run. args represents the list of arguments passed to the new program. args[0] by convention should contain the filename associated with the executed program. It can differ from path e.g. to trigger different personalities in programs. If args is not provided then path will be passed as argv[0] implicitly.

If path is a basename and does not contain a slash character then a lookup in the PATH environment variable will be made to find a suitable program.

env can be an array of environment variables to make up the new process's environment variable block. By default the current environment will be passed on.

Both args and env need to have a nullptr terminator element at the end. If is missing then a UsageError is thrown.

As a result of this call the calling process will be completely replaced by the new program. Only file descriptors not marked close-on-exec will be inherited to the new program. The ProcessID of the caller will remain the same.

Definition at line 132 of file process.cxx.

                                                                                     {
 
        exec_wrapper(::execvpe, path, args, env);
 
        cosmos_throw (ApiError("execvpe()"));
}

◆ exec() [2/2]

COSMOS_API void cosmos::proc::exec	(	const SysString	path,
		const StringViewVector &	args,
		const StringViewVector *	env = nullptr )

Variant of exec(const SysString, const CStringVector*, const CStringVector*) that takes StringViewVector.

Variant of exec() that takes StringVector.

This performs a conversion of the given StringViewVector(s) to CStringVectors. Therefore the call requires some dynamic memory allocation and copying of pointer values. args and env do not need to contain a terminating nullptr at the end.

See also: exec(const SysString, const StringViewVector&, const StringViewVector*).

Definition at line 139 of file process.cxx.

                                                                           {
 
        const auto args_vector = to_cstring_vector(args);
 
        if (!env) {
                exec(path, &args_vector);
        } else {
                const auto env_vector = to_cstring_vector(*env);
                exec(path, &args_vector, &env_vector);
        }
}

◆ exec_at()

COSMOS_API void cosmos::proc::exec_at	(	const DirFD	dir_fd,
		const SysString	path,
		const CStringVector *	args = nullptr,
		const CStringVector *	env = nullptr,
		const FollowSymlinks	follow_symlinks = FollowSymlinks{false} )

Variant of exec() that looks up a program relative to dir_fd.

If path is an absolute path then dir_fd is ignored and the call behaves just like exec(), except for the follow_symlinks setting.

Otherwise path is looked up relative to dir_fd, possibly relative to the current working directory if dir_fd is set to cosmos::AT_CWD.

If follow_symlinks is unset and the resulting path is a symbolic link then the execution fails with an ApiError and Errno::LINK_LOOP.

Definition at line 165 of file process.cxx.

                                                      {
 
        auto exec_at_wrapper = [dir_fd, follow_symlinks](
                        const char *pathname, char * const argv[], char * const envp[]) -> int {
                return ::execveat(
                                to_integral(dir_fd.raw()), pathname, argv, envp,
                                follow_symlinks ? 0 : AT_SYMLINK_NOFOLLOW);
        };
 
        exec_wrapper(exec_at_wrapper, path, args, env);
 
        cosmos_throw (ApiError("execveat()"));
}

◆ exists_env_var()

bool cosmos::proc::exists_env_var ( const SysString name )

inline

Returns whether the given environment variable exists, ignoring its content.

Definition at line 253 of file process.hxx.

                                                 {
        return get_env_var(name) != std::nullopt;
}

◆ exit()

COSMOS_API void cosmos::proc::exit ( ExitStatus status )

Immediately terminate the calling process.

This terminates the calling process, using status as the process's exit code. "immediately" refers to the fact that no userspace cleanup actions like running libc atexit() handlers will take place.

If multiple threads are running in the current process then they also will be terminated.

Definition at line 194 of file process.cxx.

                             {
        // Note: the glibc wrapper we use here ends the complete process, the
        // actual Linux system call _exit only ends the calling thread.
        _exit(to_integral(status));
}

◆ fexec()

COSMOS_API void cosmos::proc::fexec	(	const FileDescriptor	fd,
		const CStringVector *	args = nullptr,
		const CStringVector *	env = nullptr )

Variant of exec() that executes the program referred to by the given file descriptor.

This behaves just like exec(), except that a program is not looked up by path but the already open file descriptor fd is used. Also file descriptors opened using OpenFlag::PATH are supported.

There is a caveat, if fd refers to a text file naming a script interpreter via a shebang line. If fd has the close-on-exec flag set, which is the natural thing to do, then the interpreter cannot access the text file, because it is already closed. This will cause an ApiError with Errno::NO_ENTRY. It also means that fixing this by not using the close-on-exec flag will cause the file descriptor leaking into the new process.

Definition at line 181 of file process.cxx.

                                                                                         {
 
        auto exec_at_wrapper = [fd](
                        const char *pathname, char * const argv[], char * const envp[]) -> int {
                (void)pathname;
                return ::execveat(to_integral(fd.raw()), "", argv, envp, AT_EMPTY_PATH);
        };
 
        exec_wrapper(exec_at_wrapper, "", args, env);
 
        cosmos_throw (ApiError("fexecve()"));
}

◆ fork()

COSMOS_API std::optional< ProcessID > cosmos::proc::fork ( )

Fork the current process to create a child process.

This creates a copy of the current process to act as a child process. The call will return std::nullopt in the child process context and the process ID of the new child process in the parent context.

The parent is responsible for waiting on the child process to collect its exit status and free its resources using proc::wait(). An exception to this is if the calling process actively ignores the signal::CHILD signal. In this case wait() can be used to wait for the child processes to terminate but no exit status will be returned, but an Errno::NO_CHILD will be thrown instead.

Definition at line 225 of file process.cxx.

                              {
        ProcessID res{::fork()};
 
        if (res == ProcessID::INVALID) {
                cosmos_throw (ApiError("fork()"));
        } else if (res == ProcessID::CHILD) {
                return {};
        }
 
        return res;
}

◆ get_effective_group_id()

COSMOS_API GroupID cosmos::proc::get_effective_group_id ( )

Returns the effective group ID the current process is running as.

See also: get_effective_user_id()

Definition at line 40 of file process.cxx.

                                 {
        return GroupID{::getegid()};
}

◆ get_effective_user_id()

COSMOS_API UserID cosmos::proc::get_effective_user_id ( )

Returns the effective user ID the current process is running as.

This ID may differ from get_real_user_id() if a privileged process temporarily drops privileges or an unprivileged user calls a privileged program with setuid bit.

Definition at line 32 of file process.cxx.

                               {
        return UserID{::geteuid()};
}

◆ get_env_var()

COSMOS_API std::optional< SysString > cosmos::proc::get_env_var ( const SysString name )

Returns the value for the environment variable named name.

This inspects the calling process's environment variables for a variable named name and returns its value. If no such variable is found then nothing is returned.

Definition at line 200 of file process.cxx.

                                                         {
        if (auto res = std::getenv(name.raw()); res != nullptr) {
                return {res};
        }
 
        return {};
}

◆ get_own_pid()

COSMOS_API ProcessID cosmos::proc::get_own_pid ( )

Returns the process ID of the current process.

Definition at line 20 of file process.cxx.

                        {
        return ProcessID{::getpid()};
}

◆ get_own_process_group()

COSMOS_API ProcessGroupID cosmos::proc::get_own_process_group ( )

Returns the process group ID of the caller.

Definition at line 44 of file process.cxx.

                                       {
        return ProcessGroupID{getpgrp()};
}

◆ get_parent_pid()

COSMOS_API ProcessID cosmos::proc::get_parent_pid ( )

Returns the process ID of the parent of the current process.

Definition at line 24 of file process.cxx.

                           {
        return ProcessID{::getppid()};
}

◆ get_real_group_id()

COSMOS_API GroupID cosmos::proc::get_real_group_id ( )

Returns the real group ID the current process is running as.

Definition at line 36 of file process.cxx.

                            {
        return GroupID{::getgid()};
}

◆ get_real_user_id()

COSMOS_API UserID cosmos::proc::get_real_user_id ( )

Returns the real user ID the current process is running as.

Definition at line 28 of file process.cxx.

                          {
        return UserID{::getuid()};
}

◆ operator<<()

COSMOS_API std::ostream & operator<<	(	std::ostream &	o,
		const cosmos::ChildData &	data )

Outputs a human readable summary of ChildData.

Definition at line 254 of file process.cxx.

                                                                   {
        using Event = cosmos::ChildData::Event;
 
        switch (info.event) {
                case Event::EXITED:    o << "Child exited with " << *info.status; break;
                case Event::KILLED:    o << "Child killed by " << *info.signal; break;
                case Event::DUMPED:    o << "Child killed by " << *info.signal << " (dumped core)"; break;
                case Event::TRAPPED:   o << "Child trapped"; break;
                case Event::STOPPED:   o << "Child stopped by " << *info.signal; break;
                case Event::CONTINUED: o << "Child continued by " << *info.signal; break;
                default: o << "Bad ChildData"; break;
        }
 
        return o;
}

◆ set_env_var()

COSMOS_API void cosmos::proc::set_env_var	(	const SysString	name,
		const SysString	val,
		const OverwriteEnv	overwrite )

Insert or replace an environment variable.

This inserts a new name/value pair into the calling process's environment. If a variable of the given name already exists then the outcome depends on the overwrite setting: If true then an existing value will be replaced, otherwise the existing value remains untouched.

This call can fail with an exception (e.g. if the name contains invalid characters).

Definition at line 208 of file process.cxx.

                                                                                          {
        // NOTE: this is POSIX, not existing in C specs
        const auto res = ::setenv(name.raw(), val.raw(), overwrite ? 1 : 0);
 
        if (res != 0) {
                cosmos_throw (ApiError("setenv()"));
        }
}

◆ wait() [1/4]

COSMOS_API std::optional< ChildData > cosmos::proc::wait	(	const PidFD	fd,
		const WaitFlags	flags = WaitFlags{WaitFlag::WAIT_FOR_EXITED} )

Wait for the process referred to by the given pidfd.

This is just like wait(const ProcessID, const WaitFlags) only that it waits for the process referred to by the given pidfd.

The process represented by fd needs to be a child process of the calling process, otherwise an ApiError with Errno::CHILD is thrown.

Definition at line 128 of file process.cxx.

                                                                   {
        return wait(P_PIDFD, to_integral(fd.raw()), flags);
}

◆ wait() [2/4]

COSMOS_API std::optional< ChildData > cosmos::proc::wait	(	const ProcessGroupID	pgid,
		const WaitFlags	flags = WaitFlags{WaitFlag::WAIT_FOR_EXITED} )

Wait for any process from the given process group.

This is just like wait(const ProcessID, const WaitFlags) only that is waits not for a specific child process but for any of the given process group. If pgid == ProcessGroupID::SELF then this waits for any process for the caller's process group.

Definition at line 120 of file process.cxx.

                                                                              {
        return wait(P_PGID, to_integral(pgid), flags);
}

◆ wait() [3/4]

COSMOS_API std::optional< ChildData > cosmos::proc::wait	(	const ProcessID	pid,
		const WaitFlags	flags = WaitFlags{WaitFlag::WAIT_FOR_EXITED} )

Wait on the child process identified by pid.

A child process previously created via fork() or other means can be waited on using this call.

The given flags influence the state changes of the child process that will be waited for. By default a blocking wait for child process exit is performed.

Definition at line 116 of file process.cxx.

                                                                        {
        return wait(P_PID, to_integral(pid), flags);
}

◆ wait() [4/4]

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

Wait for any child process of the calling process.

This is just like wait(const ProcessID, const WaitFlags) only that it waits for any kind of child process, not any specific child process.

Definition at line 124 of file process.cxx.

                                                   {
        return wait(P_ALL, 0, flags);
}

Classes

Typedefs

Enumerations

Functions