1// Copyright (c) 2013 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// This file contains routines to kill processes and get the exit code and
6// termination status.
7
8#ifndef BASE_PROCESS_KILL_H_
9#define BASE_PROCESS_KILL_H_
10
11#include "base/files/file_path.h"
12#include "base/process/process.h"
13#include "base/process/process_handle.h"
14#include "base/time/time.h"
15#include "build/build_config.h"
16
17namespace base {
18
19class ProcessFilter;
20
21// Return status values from GetTerminationStatus.  Don't use these as
22// exit code arguments to KillProcess*(), use platform/application
23// specific values instead.
24enum TerminationStatus {
25  TERMINATION_STATUS_NORMAL_TERMINATION,   // zero exit status
26  TERMINATION_STATUS_ABNORMAL_TERMINATION, // non-zero exit status
27  TERMINATION_STATUS_PROCESS_WAS_KILLED,   // e.g. SIGKILL or task manager kill
28  TERMINATION_STATUS_PROCESS_CRASHED,      // e.g. Segmentation fault
29  TERMINATION_STATUS_STILL_RUNNING,        // child hasn't exited yet
30#if defined(OS_CHROMEOS)
31  // Used for the case when oom-killer kills a process on ChromeOS.
32  TERMINATION_STATUS_PROCESS_WAS_KILLED_BY_OOM,
33#endif
34#if defined(OS_ANDROID)
35  // On Android processes are spawned from the system Zygote and we do not get
36  // the termination status.  We can't know if the termination was a crash or an
37  // oom kill for sure, but we can use status of the strong process bindings as
38  // a hint.
39  TERMINATION_STATUS_OOM_PROTECTED,        // child was protected from oom kill
40#endif
41  TERMINATION_STATUS_LAUNCH_FAILED,        // child process never launched
42  TERMINATION_STATUS_MAX_ENUM
43};
44
45// Attempts to kill all the processes on the current machine that were launched
46// from the given executable name, ending them with the given exit code.  If
47// filter is non-null, then only processes selected by the filter are killed.
48// Returns true if all processes were able to be killed off, false if at least
49// one couldn't be killed.
50BASE_EXPORT bool KillProcesses(const FilePath::StringType& executable_name,
51                               int exit_code,
52                               const ProcessFilter* filter);
53
54#if defined(OS_POSIX)
55// Attempts to kill the process group identified by |process_group_id|. Returns
56// true on success.
57BASE_EXPORT bool KillProcessGroup(ProcessHandle process_group_id);
58#endif  // defined(OS_POSIX)
59
60// Get the termination status of the process by interpreting the
61// circumstances of the child process' death. |exit_code| is set to
62// the status returned by waitpid() on POSIX, and from
63// GetExitCodeProcess() on Windows.  |exit_code| may be NULL if the
64// caller is not interested in it.  Note that on Linux, this function
65// will only return a useful result the first time it is called after
66// the child exits (because it will reap the child and the information
67// will no longer be available).
68BASE_EXPORT TerminationStatus GetTerminationStatus(ProcessHandle handle,
69                                                   int* exit_code);
70
71#if defined(OS_POSIX)
72// Send a kill signal to the process and then wait for the process to exit
73// and get the termination status.
74//
75// This is used in situations where it is believed that the process is dead
76// or dying (because communication with the child process has been cut).
77// In order to avoid erroneously returning that the process is still running
78// because the kernel is still cleaning it up, this will wait for the process
79// to terminate. In order to avoid the risk of hanging while waiting for the
80// process to terminate, send a SIGKILL to the process before waiting for the
81// termination status.
82//
83// Note that it is not an option to call WaitForExitCode and then
84// GetTerminationStatus as the child will be reaped when WaitForExitCode
85// returns, and this information will be lost.
86//
87BASE_EXPORT TerminationStatus GetKnownDeadTerminationStatus(
88    ProcessHandle handle, int* exit_code);
89#endif  // defined(OS_POSIX)
90
91// Wait for all the processes based on the named executable to exit.  If filter
92// is non-null, then only processes selected by the filter are waited on.
93// Returns after all processes have exited or wait_milliseconds have expired.
94// Returns true if all the processes exited, false otherwise.
95BASE_EXPORT bool WaitForProcessesToExit(
96    const FilePath::StringType& executable_name,
97    base::TimeDelta wait,
98    const ProcessFilter* filter);
99
100// Waits a certain amount of time (can be 0) for all the processes with a given
101// executable name to exit, then kills off any of them that are still around.
102// If filter is non-null, then only processes selected by the filter are waited
103// on.  Killed processes are ended with the given exit code.  Returns false if
104// any processes needed to be killed, true if they all exited cleanly within
105// the wait_milliseconds delay.
106BASE_EXPORT bool CleanupProcesses(const FilePath::StringType& executable_name,
107                                  base::TimeDelta wait,
108                                  int exit_code,
109                                  const ProcessFilter* filter);
110
111// This method ensures that the specified process eventually terminates, and
112// then it closes the given process handle.
113//
114// It assumes that the process has already been signalled to exit, and it
115// begins by waiting a small amount of time for it to exit.  If the process
116// does not appear to have exited, then this function starts to become
117// aggressive about ensuring that the process terminates.
118//
119// On Linux this method does not block the calling thread.
120// On OS X this method may block for up to 2 seconds.
121//
122// NOTE: The process must have been opened with the PROCESS_TERMINATE and
123// SYNCHRONIZE permissions.
124//
125BASE_EXPORT void EnsureProcessTerminated(Process process);
126
127#if defined(OS_POSIX) && !defined(OS_MACOSX)
128// The nicer version of EnsureProcessTerminated() that is patient and will
129// wait for |pid| to finish and then reap it.
130BASE_EXPORT void EnsureProcessGetsReaped(ProcessId pid);
131#endif
132
133}  // namespace base
134
135#endif  // BASE_PROCESS_KILL_H_
136