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