ganeti.utils.process

module documentation

Utility functions for processes.

Class	`RunResult`	Holds the result of running external programs.
Function	`CloseFDs`	Close file descriptors.
Function	`Daemonize`	Daemonize the current process.
Function	`DisableFork`	Disables the use of fork(2).
Function	`GetProcCmdline`	Returns the command line of a pid as a list of arguments.
Function	`IsDaemonAlive`	Determines whether a daemon is alive
Function	`IsProcessAlive`	Check if a given pid exists on the system.
Function	`IsProcessHandlingSignal`	Checks whether a process is handling a signal.
Function	`KillProcess`	Kill a process given by its pid.
Function	`RunCmd`	Execute a (shell) command.
Function	`RunInSeparateProcess`	Runs a function in a separate process.
Function	`RunParts`	Run Scripts or programs in a directory
Function	`SetupDaemonEnv`	Setup a daemon's environment.
Function	`SetupDaemonFDs`	Setups up a daemon's file descriptors.
Function	`StartDaemon`	Start a daemon process after forking twice.
Function	`WriteErrorToFD`	Possibly write an error message to a fd.
Function	`_BuildCmdEnvironment`	Builds the environment for an external program.
Function	`_CheckIfAlive`	Raises `utils_retry.RetryAgain` if child is still alive.
Function	`_GetProcStatusField`	Retrieves a field from the contents of a proc status file.
Function	`_GetProcStatusPath`	Returns the path for a PID's proc status file.
Function	`_ParseSigsetT`	Parse a rendered sigset_t value.
Function	`_RunCmdFile`	Run a command and save its output to a file.
Function	`_RunCmdPipe`	Run a command and return its output.
Function	`_StartDaemonChild`	Child process for starting daemon.
Function	`_WaitForProcess`	Waits for the child to terminate or until we reach timeout.
Constant	`_TIMEOUT_KILL`	Undocumented
Constant	`_TIMEOUT_NONE`	Undocumented
Constant	`_TIMEOUT_TERM`	Undocumented
Variable	`_no_fork`	Undocumented

def CloseFDs(noclose_fds=None): ¶

Close file descriptors.

This closes all file descriptors above 2 (i.e. except stdin/out/err).

Parameters
noclose_fds:list or None	if given, it denotes a list of file descriptor that should not be closed

def Daemonize(logfile): ¶

Daemonize the current process.

This detaches the current process from the controlling terminal and runs it in the background as a daemon.

Parameters
logfile:str	the logfile to which we should redirect stdout/stderr
Returns
tuple; (int, callable)	File descriptor of pipe(2) which must be closed to notify parent process and a callable to reopen log files

def DisableFork(): ¶

Disables the use of fork(2).

def GetProcCmdline(pid): ¶

Returns the command line of a pid as a list of arguments.

Parameters
pid:int	Process ID
Returns
list of string	Undocumented
Raises
`EnvironmentError`	If the process does not exist

def IsDaemonAlive(name): ¶

Determines whether a daemon is alive

Parameters
name:string	daemon name
Returns
boolean	True if daemon is running, False otherwise

def IsProcessAlive(pid): ¶

Check if a given pid exists on the system.

Parameters
pid:int	the process ID to check
Returns
boolean	True if the process exists
Note
zombie status is not handled, so zombie processes will be returned as alive

def IsProcessHandlingSignal(pid, signum, status_path=None): ¶

Checks whether a process is handling a signal.

Parameters
pid:int	Process ID
signum:int	Signal number
status_path	Undocumented
Returns
bool	Undocumented

def KillProcess(pid, signal_=signal.SIGTERM, timeout=30, waitpid=False): ¶

Kill a process given by its pid.

Parameters
pid:int	The PID to terminate.
signal_:int	The signal to send, by default SIGTERM
timeout:int	The timeout after which, if the process is still alive, a SIGKILL will be sent. If not positive, no such checking will be done
waitpid:boolean	If true, we should waitpid on this process after sending signals, since it's our own child and otherwise it would remain as zombie

def RunCmd(cmd, env=None, output=None, cwd='/', reset_env=False, interactive=False, timeout=None, noclose_fds=None, input_fd=None, postfork_fn=None): ¶

Execute a (shell) command.

The command should not read from its standard input, as it will be closed.

Parameters
cmd:string or list	Command to run
env:dict	Additional environment variables
output:str	if desired, the output of the command can be saved in a file instead of the RunResult instance; this parameter denotes the file name (if not None)
cwd:string	if specified, will be used as the working directory for the command; the default will be /
reset_env:boolean	whether to reset or keep the default os environment
interactive:boolean	whether we pipe stdin, stdout and stderr (default behaviour) or run the command interactive
timeout:int	If not None, timeout in seconds until child process gets killed
noclose_fds:list	list of additional (fd >=3) file descriptors to leave open for the child process
input_fd:`file`-like object or numeric file descriptor	File descriptor for process' standard input
postfork_fn:Callable receiving PID as parameter	Callback run after fork but before timeout
Returns
`RunResult`	RunResult instance
Raises
`errors.ProgrammerError`	if we call this when forks are disabled

def RunInSeparateProcess(fn, *args): ¶

Runs a function in a separate process.

Note: Only boolean return values are supported.

Parameters
fn:callable	Function to be called
*args	Undocumented
Returns
bool	Function's result

def RunParts(dir_name, env=None, reset_env=False): ¶

Run Scripts or programs in a directory

Parameters
dir_name:string	absolute path to a directory
env:dict	The environment to use
reset_env:boolean	whether to reset or keep the default os environment
Returns
list of tuples	list of (name, (one of RUNDIR_STATUS), RunResult)

def SetupDaemonEnv(cwd='/', umask=63): ¶

Setup a daemon's environment.

This should be called between the first and second fork, due to setsid usage.

Parameters
cwd	the directory to which to chdir
umask	the umask to setup

def SetupDaemonFDs(output_file, output_fd): ¶

Setups up a daemon's file descriptors.

Parameters
output_file	if not None, the file to which to redirect stdout/stderr
output_fd	if not None, the file descriptor for stdout/stderr

def StartDaemon(cmd, env=None, cwd='/', output=None, output_fd=None, pidfile=None): ¶

Start a daemon process after forking twice.

Parameters
cmd:string or list	Command to run
env:dict	Additional environment variables
cwd:string	Working directory for the program
output:string	Path to file in which to save the output
output_fd:int	File descriptor for output
pidfile:string	Process ID file
Returns
int	Daemon process ID
Raises
`errors.ProgrammerError`	if we call this when forks are disabled

def WriteErrorToFD(fd, err): ¶

Possibly write an error message to a fd.

Parameters
fd:None or int (file descriptor)	if not None, the error will be written to this fd
err	string, the error message

def _BuildCmdEnvironment(env, reset): ¶

Builds the environment for an external program.

def _CheckIfAlive(child): ¶

Raises utils_retry.RetryAgain if child is still alive.

Raises
`utils_retry.RetryAgain`	If child is still alive

def _GetProcStatusField(pstatus, field): ¶

Retrieves a field from the contents of a proc status file.

Parameters
pstatus:string	Contents of /proc/$pid/status
field:string	Name of field whose value should be returned
Returns
string	Undocumented

def _GetProcStatusPath(pid): ¶

Returns the path for a PID's proc status file.

Parameters
pid:int	Process ID
Returns
string	Undocumented

def _ParseSigsetT(sigset): ¶

Parse a rendered sigset_t value.

This is the opposite of the Linux kernel's fs/proc/array.c:render_sigset_t function.

Parameters
sigset:string	Rendered signal set from /proc/$pid/status
Returns
set	Set of all enabled signal numbers

def _RunCmdFile(cmd, env, via_shell, output, cwd, noclose_fds): ¶

Run a command and save its output to a file.

Parameters
cmd:string or list	Command to run
env:dict	The environment to use
via_shell:bool	if we should run via the shell
output:str	the filename in which to save the output
cwd:string	the working directory for the program
noclose_fds:list	list of additional (fd >=3) file descriptors to leave open for the child process
Returns
int	the exit status

def _RunCmdPipe(cmd, env, via_shell, cwd, interactive, timeout, noclose_fds, input_fd, postfork_fn=None, _linger_timeout=constants.CHILD_LINGER_TIMEOUT): ¶

Run a command and return its output.

Parameters
cmd:string or list	Command to run
env:dict	The environment to use
via_shell:bool	if we should run via the shell
cwd:string	the working directory for the program
interactive:boolean	Run command interactive (without piping)
timeout:int	Timeout after the programm gets terminated
noclose_fds:list	list of additional (fd >=3) file descriptors to leave open for the child process
input_fd:`file`-like object or numeric file descriptor	File descriptor for process' standard input
postfork_fn:Callable receiving PID as parameter	Function run after fork but before timeout
_linger_timeout	Undocumented
Returns
tuple	(out, err, status)

def _StartDaemonChild(errpipe_read, errpipe_write, pidpipe_read, pidpipe_write, args, env, cwd, output, fd_output, pidfile): ¶

Child process for starting daemon.

def _WaitForProcess(child, timeout): ¶

Waits for the child to terminate or until we reach timeout.

_TIMEOUT_KILL = ¶

Undocumented

_TIMEOUT_NONE = ¶

Undocumented

_TIMEOUT_TERM = ¶

Undocumented

_no_fork: bool = ¶

Undocumented