Process provides an encapsulation of a spawned process, allowing the parent process to perform I/O with the spawned process, send it signals and wait for it to finish. More...

#include <Process.h>

Public Member Functions
	Process (pid_t pid)
	Construct a Process.

	Process ()
	Default constructor.

	Process (const Process &x)
	Copy constructor.

Process &	operator= (const Process &x)
	Assignment operator.

	~Process ()
	Destructor, which does very little.

void	kill (int signal)
	Send a signal to the process.

int	wait (bool hang, int *status)
	Do a system wait on a process.

int	getInFd () const
	Get the file descriptor of the pipe that is connected to the standard in of the Process.

std::ostream &	inStream ()
	Get the ostream of the pipe that is connected to the standard in of the Process.

void	closeIn ()
	Close the file descriptor and ostream of the pipe connected to the standard in of the Process.

int	getOutFd () const
	Get the file descriptor of the pipe that is connected to the standard out of the Process.

std::istream &	outStream ()
	Get the istream of the pipe that is connected to the standard out of the Process.

void	closeOut ()
	Close the file descriptor and istream of the pipe connected to the standard out of the Process.

int	getErrFd () const
	Get the file descriptor of the pipe that is connected to the standard error of the Process.

std::istream &	errStream ()
	Get the istream of the pipe that is connected to the standard error of the Process.

void	closeErr ()
	Close the file descriptor and istream of the pipe connected to the standard error of the Process.

pid_t	getPid () const
	The process id of the Process.

Static Public Member Functions
static Process	spawn (const std::string &cmd, const std::vector< std::string > &args, const std::map< std::string, std::string > &env, int niceval=0)
	Fork and execute a command and associated arguments and environment.

static Process	spawn (const std::string &cmd, const std::vector< std::string > &args, int niceval=0)
	Fork and execute a command and associated arguments.

static Process	spawn (const std::string &cmd)
	Execute a command by forking and executing command from the shell command line using "sh -c cmd".

static pid_t	checkPidFile (const std::string &pidFile)
	Check if another process is running, using the named process id file.

static void	removePidFile ()
	Remove the pid file.

static void	addEffectiveCapability (int cap)
	Add an effective capability to this process.

static void	clearEffectiveCapability (int cap)

static bool	getEffectiveCapability (int cap)
	Check if this process has an effective capability.

static std::string	expandEnvVars (std::string input)

static bool	getEnvVar (const std::string &name, std::string &value)
	Get an environment variable given a variable name like "HOST", without the '$', or any brackets, '{' or '}'.

static void	setEnvVar (const std::string &name, const std::string &value)

static void	clearEnv ()
	Remove any environment settings made by setEnvVar and release any memory allocated to put those settings in the environment.

static unsigned long	getVMemSize ()
	Return the virtual memory size in bytes of the current process, as read from the /proc/pid/stat file.

static unsigned long	getMaxRSS ()
	Return the maximum resident set size of the current process, in bytes.

Private Member Functions
void	setInFd (int val)

void	setOutFd (int val)

void	setErrFd (int val)

Private Attributes
pid_t	_pid

int	_infd
	File descriptor that is connected via a pipe to the standard in file descriptor of a spawned process.

auto_ptr< __gnu_cxx::stdio_filebuf< char > >	_inbuf_ap
	GNU extension filebuf which is needed to create a ostream from a file descriptor.

auto_ptr< std::ostream >	_instream_ap

int	_outfd
	File descriptor that is connected via a pipe to the standard out file descriptor of a spawned process.

auto_ptr< __gnu_cxx::stdio_filebuf< char > >	_outbuf_ap

auto_ptr< std::istream >	_outstream_ap

int	_errfd
	File descriptor that is connected via a pipe to the standard error file descriptor of a spawned process.

auto_ptr< __gnu_cxx::stdio_filebuf< char > >	_errbuf_ap

auto_ptr< std::istream >	_errstream_ap

Static Private Attributes
static std::string	_pidFile

static std::map< std::string, char * >	_environment

static Mutex	_envLock

Detailed Description

Process provides an encapsulation of a spawned process, allowing the parent process to perform I/O with the spawned process, send it signals and wait for it to finish.

Static methods are provided for spawning (forking and executing) a process. A static method also exists to atomically check and create a process id file.

Constructor & Destructor Documentation

◆ Process() [1/3]

Process::Process ( pid_t pid )

Construct a Process.

@ param pid: pid should be > 0 and be a valid process id. Unix system calls support doing kills and waits on a pid less than or equal to 0, but those capabilities are not supported in this class. I/O via the getXXFd() or xxStream() methods is not possible with a process created with this constructor. kill() and wait() are supported. In order to use the Process methods to perform I/O with a process, it must be started with one of the spawn methods.

References _pid, and kill().

◆ Process() [2/3]

Process::Process ( )

Default constructor.

Does not point to any process.

◆ Process() [3/3]

Process::Process ( const Process & x )

Copy constructor.

The new process will inherit the file descriptors and iostreams from x. The file descriptors and iostreams of the copied Process, x, are no longer valid after this copy.

◆ ~Process()

Process::~Process ( )

Destructor, which does very little.

It does not do a kill or wait on the process, or close any file descriptors that are connected to the process.

Member Function Documentation

◆ addEffectiveCapability()

void Process::addEffectiveCapability ( int cap )

static

Add an effective capability to this process.

See man 7 capabilities. If a process has been started with an effective uid of 0(root), one should call prctl(PR_SET_KEEPCAPS,1,0,0,0) prior to doing setuid to a uid > 0. Then use this method to add a capability.

Exceptions

Exception

◆ checkPidFile()

pid_t Process::checkPidFile ( const std::string & pidFile )

static

Check if another process is running, using the named process id file.

A process id file typically has a name like /var/run/xxxx.pid, or /tmp/xxxx.pid. This function is useful when there should only be one instance of a process running on a system - for example a daemon which listens on a socket port. The process name, "xxxx" should not be used by any other process on the system.

Returns: 0: means that no other process which uses file pidFile appears to be running. The pidFile was then created, containing the process id of the current process. >0: pid of a process that either holds a lock on pidFile, or pidFile contains a pid of a process that is still running.

If the return is 0, it means that the pidFile either didn't exist, was empty, didn't contain a number, or a current process with the given number doesn't exist. In this case, the file is created if necessary, and will contain the process id of the current process. checkPidFile also calls atexit() to schedule the removePidFile() function to be run when the current process exits. One typically does not have to call removePidFile explicitly.

Exceptions

IOException

References _pidFile, fd, kill(), and removePidFile().

◆ clearEffectiveCapability()

void Process::clearEffectiveCapability ( int cap )

static

Exceptions

Exception

◆ clearEnv()

void Process::clearEnv ( )

static

Remove any environment settings made by setEnvVar and release any memory allocated to put those settings in the environment.

References _environment, and _envLock.

◆ closeErr()

void Process::closeErr ( )

Close the file descriptor and istream of the pipe connected to the standard error of the Process.

References _errbuf_ap, _errfd, and _errstream_ap.

Referenced by wait().

◆ closeIn()

void Process::closeIn ( )

Close the file descriptor and ostream of the pipe connected to the standard in of the Process.

The Process will then receive an EOF on a subsequent read from the other end of the pipe.

References _inbuf_ap, _infd, and _instream_ap.

Referenced by wait().

◆ closeOut()

void Process::closeOut ( )

Close the file descriptor and istream of the pipe connected to the standard out of the Process.

References _outbuf_ap, _outfd, and _outstream_ap.

Referenced by wait().

◆ errStream()

std::istream & nidas::util::Process::errStream ( )

inline

Get the istream of the pipe that is connected to the standard error of the Process.

This istream is only valid after a spawn() of a Process. The error output of the Process can be read from this istream.

References _errstream_ap.

◆ expandEnvVars()

string Process::expandEnvVars ( std::string input )

static

References getEnvVar().

◆ getEffectiveCapability()

bool Process::getEffectiveCapability ( int cap )

static

Check if this process has an effective capability.

See man 7 capabilities.

Exceptions

Exception

◆ getEnvVar()

bool Process::getEnvVar	(	const std::string &	name,
		std::string &	value )

static

Get an environment variable given a variable name like "HOST", without the '$', or any brackets, '{' or '}'.

Returns: : true if variable found

References _envLock.

Referenced by expandEnvVars(), nidas::util::UTime::getTZ(), and nidas::util::UTime::setTZ().

◆ getErrFd()

int nidas::util::Process::getErrFd ( ) const

inline

Get the file descriptor of the pipe that is connected to the standard error of the Process.

This file descriptor is only valid after a spawn() of a Process. The error output of the Process can be read from this file descriptor.

References _errfd.

◆ getInFd()

int nidas::util::Process::getInFd ( ) const

inline

Get the file descriptor of the pipe that is connected to the standard in of the Process.

This file descriptor is only valid after a spawn() of a Process. Bytes writen to this file descriptor can be then read by the Process.

References _infd.

◆ getMaxRSS()

unsigned long Process::getMaxRSS ( )

static

Return the maximum resident set size of the current process, in bytes.

This is the portion of the process's memory that is held in RAM. This value is determined with the getrusage(RUSAGE_SELF,...) system call.

References ELOG, nidas::util::Exception::errnoToString(), and usage().

◆ getOutFd()

int nidas::util::Process::getOutFd ( ) const

inline

Get the file descriptor of the pipe that is connected to the standard out of the Process.

This file descriptor is only valid after a spawn() of a Process. The output of the Process can be read from this file descriptor.

References _outfd.

◆ getPid()

pid_t nidas::util::Process::getPid ( ) const

inline

The process id of the Process.

Returns: : Will be -1 if this Process is not associated with a valid process.

References _pid.

Referenced by nidas::core::FsMount::cancel().

◆ getVMemSize()

unsigned long Process::getVMemSize ( )

static

Return the virtual memory size in bytes of the current process, as read from the /proc/pid/stat file.

Do man proc for info.

References ELOG, nidas::util::Exception::errnoToString(), fclose(), and fp.

◆ inStream()

std::ostream & nidas::util::Process::inStream ( )

inline

Get the ostream of the pipe that is connected to the standard in of the Process.

This ostream is only valid after a spawn() of a Process.

References _instream_ap.

◆ kill()

void Process::kill ( int signal )

Send a signal to the process.

Exceptions

IOException

References _pid, and kill().

Referenced by nidas::core::FsMount::cancel(), checkPidFile(), kill(), and Process().

◆ operator=()

Process & Process::operator= ( const Process & x )

Assignment operator.

The assigned process (on LHS of =) will inherit the file descriptors and iostreams from x. The file descriptors and iostreams of the RHS Process, x, are no longer valid after this assignment.

References _errbuf_ap, _errfd, _errstream_ap, _inbuf_ap, _infd, _instream_ap, _outbuf_ap, _outfd, _outstream_ap, and _pid.

◆ outStream()

std::istream & nidas::util::Process::outStream ( )

inline

Get the istream of the pipe that is connected to the standard out of the Process.

This istream is only valid after a spawn() of a Process. The output of the Process can be read from this istream.

References _outstream_ap.

Referenced by nidas::core::FsMount::autoMount(), nidas::core::FsMount::mount(), and nidas::core::FsMount::unmount().

◆ removePidFile()

void Process::removePidFile ( )

static

Remove the pid file.

Note that checkPidFile schedules this function to be called when the process exits.

References _pidFile.

Referenced by checkPidFile().

◆ setEnvVar()

void Process::setEnvVar	(	const std::string &	name,
		const std::string &	value )

static

References _environment, and _envLock.

Referenced by nidas::util::UTime::setTZ().

◆ setErrFd()

void Process::setErrFd ( int val )

private

References _errbuf_ap, _errfd, and _errstream_ap.

◆ setInFd()

void Process::setInFd ( int val )

private

References _inbuf_ap, _infd, and _instream_ap.

◆ setOutFd()

void Process::setOutFd ( int val )

private

References _outbuf_ap, _outfd, and _outstream_ap.

◆ spawn() [1/3]

Process Process::spawn ( const std::string & cmd )

static

Execute a command by forking and executing command from the shell command line using "sh -c cmd".

Return the Process.

Exceptions

IOException

◆ spawn() [2/3]

Process Process::spawn	(	const std::string &	cmd,
		const std::vector< std::string > &	args,
		const std::map< std::string, std::string > &	env,
		int	niceval = 0 )

static

Fork and execute a command and associated arguments and environment.

Return the Process object that can be used to communicate with or control the sub-process.

Parameters

cmd	The name of the command. spawn uses the execvp system call, which means that if the command name does not contain a slash (/) character, then a search is done for the command name using the PATH environment variable.
args	Arguments that are passed to the command. The zero'th argument should be the short name of the command, as is required by the exec system calls.
env	Environment variables to be added or changed in the subprocess. The map keys are the names of the environment variables. Note that by default, the current environment is copied to the subprocess, so you only need to specify variables that you wish to be added or changed.
niceval	The desired nice value, typically a positive value so that the spawned process has a higher nice value (lower priority). If niceval is negative and the user does not have sufficient permisions to lower the nice value, the error is silently ignored.

Exceptions

IOException

Referenced by spawn(), and nidas::util::svnStatus().

◆ spawn() [3/3]

Process Process::spawn	(	const std::string &	cmd,
		const std::vector< std::string > &	args,
		int	niceval = 0 )

static

Fork and execute a command and associated arguments.

Return the Process object that can be used to communicate with or control the sub-process. spawn uses the execvp system call, which means that if the command name does not contain a slash (/) character, then a search is done for the command name using the PATH environment variable.

Exceptions

IOException

References spawn().

◆ wait()

int Process::wait	(	bool	hang,
		int *	status )

Do a system wait on a process.

Returns: Process id of waited on process, or 0 if hang=false and process has not finished, or -1 if process does not exist.

Parameters

hang	If true, wait for process state to change. If hang=false, don't wait, return 0 if process state has not changed.
status	status of process. See man 2 waitpid. After a successfull wait, any file descriptors connected to the process will be closed.

Exceptions

IOException

References _pid, closeErr(), closeIn(), and closeOut().

Referenced by nidas::core::FsMount::autoMount(), nidas::core::FsMount::cancel(), nidas::core::FsMount::mount(), and nidas::core::FsMount::unmount().

Member Data Documentation

◆ _environment

map< string, char * > Process::_environment

staticprivate

Referenced by clearEnv(), and setEnvVar().

◆ _envLock

Mutex Process::_envLock

staticprivate

Referenced by clearEnv(), getEnvVar(), and setEnvVar().

◆ _errbuf_ap

auto_ptr<__gnu_cxx::stdio_filebuf<char> > nidas::util::Process::_errbuf_ap

mutableprivate

Referenced by closeErr(), operator=(), and setErrFd().

◆ _errfd

int nidas::util::Process::_errfd

mutableprivate

File descriptor that is connected via a pipe to the standard error file descriptor of a spawned process.

Referenced by closeErr(), getErrFd(), operator=(), and setErrFd().

◆ _errstream_ap

auto_ptr<std::istream> nidas::util::Process::_errstream_ap

mutableprivate

Referenced by closeErr(), errStream(), operator=(), and setErrFd().

◆ _inbuf_ap

auto_ptr<__gnu_cxx::stdio_filebuf<char> > nidas::util::Process::_inbuf_ap

mutableprivate

GNU extension filebuf which is needed to create a ostream from a file descriptor.

Referenced by closeIn(), operator=(), and setInFd().

◆ _infd

int nidas::util::Process::_infd

mutableprivate

File descriptor that is connected via a pipe to the standard in file descriptor of a spawned process.

It is declared mutable to allow invalidating x._infd in the copy constructor and assignment operators that take a reference to a const Process argument.

Referenced by closeIn(), getInFd(), operator=(), and setInFd().

◆ _instream_ap

auto_ptr<std::ostream> nidas::util::Process::_instream_ap

mutableprivate

Referenced by closeIn(), inStream(), operator=(), and setInFd().

◆ _outbuf_ap

auto_ptr<__gnu_cxx::stdio_filebuf<char> > nidas::util::Process::_outbuf_ap

mutableprivate

Referenced by closeOut(), operator=(), and setOutFd().

◆ _outfd

int nidas::util::Process::_outfd

mutableprivate

File descriptor that is connected via a pipe to the standard out file descriptor of a spawned process.

Referenced by closeOut(), getOutFd(), operator=(), and setOutFd().

◆ _outstream_ap

auto_ptr<std::istream> nidas::util::Process::_outstream_ap

mutableprivate

Referenced by closeOut(), operator=(), outStream(), and setOutFd().

◆ _pid

pid_t nidas::util::Process::_pid

private

Referenced by getPid(), kill(), operator=(), Process(), and wait().

◆ _pidFile

string Process::_pidFile

staticprivate

Referenced by checkPidFile(), and removePidFile().

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

nidas/util/Process.h
nidas/util/Process.cc

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Process() [1/3]

◆ Process() [2/3]

◆ Process() [3/3]

◆ ~Process()

Member Function Documentation

◆ addEffectiveCapability()

◆ checkPidFile()

◆ clearEffectiveCapability()

◆ clearEnv()

◆ closeErr()

◆ closeIn()

◆ closeOut()

◆ errStream()

◆ expandEnvVars()

◆ getEffectiveCapability()

◆ getEnvVar()

◆ getErrFd()

◆ getInFd()

◆ getMaxRSS()

◆ getOutFd()

◆ getPid()

◆ getVMemSize()

◆ inStream()

◆ kill()

◆ operator=()

◆ outStream()

◆ removePidFile()

◆ setEnvVar()

◆ setErrFd()

◆ setInFd()

◆ setOutFd()

◆ spawn() [1/3]

◆ spawn() [2/3]

◆ spawn() [3/3]

◆ wait()

Member Data Documentation

◆ _environment

◆ _envLock

◆ _errbuf_ap

◆ _errfd

◆ _errstream_ap

◆ _inbuf_ap

◆ _infd

◆ _instream_ap

◆ _outbuf_ap

◆ _outfd

◆ _outstream_ap

◆ _pid

◆ _pidFile