Flow-IPC 1.0.2
Flow-IPC project: Public API.
Public Member Functions | Static Public Member Functions | Related Functions | List of all members
ipc::util::Process_credentials Class Reference

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

#include <process_credentials.hpp>

Inheritance diagram for ipc::util::Process_credentials:
[legend]

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_credentialsoperator= (const Process_credentials &src)
 Boring copy assignment. 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_initSee process_id().
user_id_initSee user_id().
group_id_initSee group_id().

◆ Process_credentials() [2/2]

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

Boring copy ctor.

Parameters
srcSource 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

Boring copy assignment.

Parameters
srcSource 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_codeSee 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 
)
related

Checks for by-value inequality between two Process_credentials objects.

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

Parameters
val1Value to compare.
val2Value to compare.
Returns
Whether at least one accessor compares unequal.

◆ operator<<()

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

Prints string representation of the given util::Process_credentials to the given ostream.

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
osStream to which to write.
valObject to serialize.
Returns
os.

◆ operator==()

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

Checks for by-value equality between two Process_credentials objects.

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

Parameters
val1Value to compare.
val2Value to compare.
Returns
Whether the accessors all compare equal.

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