base/process/kill.h

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