A process's credentials (PID, UID, GID as of this writing). More...

#include <process_credentials.hpp>

Inheritance diagram for ipc::util::Process_credentials:

Public Member Functions
	Process_credentials ()
	Default ctor: each value is initialized to zero or equivalent.

	Process_credentials (process_id_t process_id_init, user_id_t user_id_init, group_id_t group_id_init)
	Ctor that sets the values explicitly. More...

	Process_credentials (const Process_credentials &src)
	Boring copy ctor. More...

Process_credentials &	operator= (const Process_credentials &src)
	Methods. More...

process_id_t	process_id () const
	The process ID (PID). More...

user_id_t	user_id () const
	The user ID (UID). More...

group_id_t	group_id () const
	The group user ID (GID). More...

std::string	process_invoked_as (Error_code *err_code=0) const
	Obtains, from the OS, information as to the binary name via which process process_id() was started, per its command line, namely `argv[0]`. More...

Static Public Member Functions
static process_id_t	own_process_id ()
	Obtains the calling process's process_id(). More...

static user_id_t	own_user_id ()
	Obtains the calling process's effective user_id(). More...

static group_id_t	own_group_id ()
	Obtains the calling process's effective group_id(). More...

static Process_credentials	own_process_credentials ()
	Constructs and returns Process_credentials containing values pertaining to the calling process at this time. More...

Related Functions
(Note that these are not member functions.)
bool	operator== (const Process_credentials &val1, const Process_credentials &val2)
	Checks for by-value equality between two Process_credentials objects. More...

bool	operator!= (const Process_credentials &val1, const Process_credentials &val2)
	Checks for by-value inequality between two Process_credentials objects. More...

std::ostream &	operator<< (std::ostream &os, const Process_credentials &val)
	Prints string representation of the given util::Process_credentials to the given `ostream`. More...

Detailed Description

A process's credentials (PID, UID, GID as of this writing).

See also: Opt_peer_process_credentials, a sub-class.

Constructor & Destructor Documentation

◆ Process_credentials() [1/2]

ipc::util::Process_credentials::Process_credentials	(	process_id_t	process_id_init,
		user_id_t	user_id_init,
		group_id_t	group_id_init
	)

explicit

Ctor that sets the values explicitly.

Parameters

process_id_init	See process_id().
user_id_init	See user_id().
group_id_init	See group_id().

◆ Process_credentials() [2/2]

ipc::util::Process_credentials::Process_credentials ( const Process_credentials & src )

default

Boring copy ctor.

Parameters

src	Source object.

Member Function Documentation

◆ group_id()

group_id_t ipc::util::Process_credentials::group_id ( ) const

The group user ID (GID).

Returns: See above.

◆ operator=()

Process_credentials & ipc::util::Process_credentials::operator= ( const Process_credentials & src )

default

Methods.

Boring copy assignment.

Parameters

src	Source object.

Returns: *this.

◆ own_group_id()

group_id_t ipc::util::Process_credentials::own_group_id ( )

static

Obtains the calling process's effective group_id().

This value can be changed via OS calls.

Returns: See above.

◆ own_process_credentials()

Process_credentials ipc::util::Process_credentials::own_process_credentials ( )

static

Constructs and returns Process_credentials containing values pertaining to the calling process at this time.

Note that certain values therein may become incorrect over time (see own_user_id(), own_group_id()).

Returns: Process_credentials(own_process_id(), own_user_id(), own_group_id()).

◆ own_process_id()

process_id_t ipc::util::Process_credentials::own_process_id ( )

static

Obtains the calling process's process_id().

This value will never change.

Returns: See above.

◆ own_user_id()

user_id_t ipc::util::Process_credentials::own_user_id ( )

static

Obtains the calling process's effective user_id().

This value can be changed via OS calls.

Returns: See above.

◆ process_id()

process_id_t ipc::util::Process_credentials::process_id ( ) const

The process ID (PID).

Returns: See above.

◆ process_invoked_as()

std::string ipc::util::Process_credentials::process_invoked_as ( Error_code * err_code = 0 ) const

Obtains, from the OS, information as to the binary name via which process process_id() was started, per its command line, namely argv[0].

In simplified terms this is the executable of *this process; however there are important properties to consider about this information:

The process must be currently executing. If it is not, a no-such-file error is emitted.
The executable name is as-it-appeared on the command line; e.g., it might be a relative and/or un-normalized and/or a symlink. It is only the normalized, absolute path if that is how it was invoked.
It is possible (not common but not non-existent either) for a process to change its own command line upon execution; in this case there's almost no limit to what string might result. Note! Even an empty returned string is possible; and this is not emitted as an error.

Because of these facts we feel it is, informally, best to use this information for one of these use cases:

logging;
verification against an expected value, especially when safety-checking against an expected policy (e.g., against session::App::m_exec_path) – namely that, say, the given process was (1) an instance of a specific application and (2) was invoked via its normalized, absolute path.

For these cases it should be reasonable to use.

Implementation/rationale for it

(Normally we omit impl details in public doc headers, but in this case the utility is low-level, and it may benefit you to know it.)

This builds in Linux only; it reads /proc/(pid)/cmdline (if it exists) and obtains the first NUL-terminated entry there. This is argv[0]. argv space may be overwritten by the process, so it could be something other than the original invocation. Ignoring that, it'll be whatever the command line included; could be absolute or not, normalized or not, the symlink or not... and so on. The tool ps uses the same technique.

One technique was considered: read Linux's /proc/(pid)/exe symlink which points to the absolute, normalized executable path actually invoked. That would have been perfect; however it appears to require admin privileges on our part, and we do not want to require this. On balance, since the original use case prompting this feature (session::App::m_exec_path verification) is acceptably served by the less-demanding /proc/.../cmdline method, we chose that.

Parameters

err_code See flow::Error_code docs for error reporting semantics. Error_code generated: some system error code; but most likely no-such-file error of some kind, indicating the process is not executing (any longer?).

Returns: The first entry – the executable – according to the process's command line (see above), if no Error_code is emitted. If one is emitted, without an exception (err_code not null), empty string. Caution: If error is not emitted, returned value might still be empty, if the process overrode its own command line (see above).

◆ user_id()

user_id_t ipc::util::Process_credentials::user_id ( ) const

The user ID (UID).

Returns: See above.

Friends And Related Function Documentation

◆ operator!=()

bool operator!=	(	const Process_credentials &	val1,
		const Process_credentials &	val2
	)

process_invoked_as() does not participate in this and is not invoked.

Parameters

val1	Value to compare.
val2	Value to compare.

Returns: Whether at least one accessor compares unequal.

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	os,
		const Process_credentials &	val
	)

process_invoked_as() does not participate in this and is not invoked; you may query that information if desired manually; just remember val.process_id() must be live at the time for it to work.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator==()

bool operator==	(	const Process_credentials &	val1,
		const Process_credentials &	val2
	)

process_invoked_as() does not participate in this and is not invoked.

Parameters

val1	Value to compare.
val2	Value to compare.

Returns: Whether the accessors all compare equal.

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

Public Member Functions

Static Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ Process_credentials() [1/2]

◆ Process_credentials() [2/2]

Member Function Documentation

◆ group_id()

◆ operator=()

◆ own_group_id()

◆ own_process_credentials()

◆ own_process_id()

◆ own_user_id()

◆ process_id()

◆ process_invoked_as()

Implementation/rationale for it

◆ user_id()

Friends And Related Function Documentation

◆ operator!=()

◆ operator<<()

◆ operator==()