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