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_CHROMEOS)
  30   // Used for the case when oom-killer kills a process on ChromeOS.
  31   TERMINATION_STATUS_PROCESS_WAS_KILLED_BY_OOM,
  32 #endif
  33 #if defined(OS_ANDROID)
  34   // On Android processes are spawned from the system Zygote and we do not get
  35   // the termination status.  We can't know if the termination was a crash or an
  36   // oom kill for sure, but we can use status of the strong process bindings as
  37   // a hint.
  38   TERMINATION_STATUS_OOM_PROTECTED,        // child was protected from oom kill
  39 #endif
  40   TERMINATION_STATUS_LAUNCH_FAILED,        // child process never launched
  41   TERMINATION_STATUS_MAX_ENUM
  42 };
  43
  44 // Attempts to kill all the processes on the current machine that were launched
  45 // from the given executable name, ending them with the given exit code.  If
  46 // filter is non-null, then only processes selected by the filter are killed.
  47 // Returns true if all processes were able to be killed off, false if at least
  48 // one couldn't be killed.
  49 BASE_EXPORT bool KillProcesses(const FilePath::StringType& executable_name,
  50                                int exit_code,
  51                                const ProcessFilter* filter);
  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 // Get the termination status of the process by interpreting the
  60 // circumstances of the child process' death. |exit_code| is set to
  61 // the status returned by waitpid() on POSIX, and from
  62 // GetExitCodeProcess() on Windows.  |exit_code| may be NULL if the
  63 // caller is not interested in it.  Note that on Linux, this function
  64 // will only return a useful result the first time it is called after
  65 // the child exits (because it will reap the child and the information
  66 // will no longer be available).
  67 BASE_EXPORT TerminationStatus GetTerminationStatus(ProcessHandle handle,
  68                                                    int* exit_code);
  69
  70 #if defined(OS_POSIX)
  71 // Send a kill signal to the process and then wait for the process to exit
  72 // and get the termination status.
  73 //
  74 // This is used in situations where it is believed that the process is dead
  75 // or dying (because communication with the child process has been cut).
  76 // In order to avoid erroneously returning that the process is still running
  77 // because the kernel is still cleaning it up, this will wait for the process
  78 // to terminate. In order to avoid the risk of hanging while waiting for the
  79 // process to terminate, send a SIGKILL to the process before waiting for the
  80 // termination status.
  81 //
  82 // Note that it is not an option to call WaitForExitCode and then
  83 // GetTerminationStatus as the child will be reaped when WaitForExitCode
  84 // returns, and this information will be lost.
  85 //
  86 BASE_EXPORT TerminationStatus GetKnownDeadTerminationStatus(
  87     ProcessHandle handle, int* exit_code);
  88 #endif  // defined(OS_POSIX)
  89
  90 // Wait for all the processes based on the named executable to exit.  If filter
  91 // is non-null, then only processes selected by the filter are waited on.
  92 // Returns after all processes have exited or wait_milliseconds have expired.
  93 // Returns true if all the processes exited, false otherwise.
  94 BASE_EXPORT bool WaitForProcessesToExit(
  95     const FilePath::StringType& executable_name,
  96     base::TimeDelta wait,
  97     const ProcessFilter* filter);
  98
  99 // Waits a certain amount of time (can be 0) for all the processes with a given
 100 // executable name to exit, then kills off any of them that are still around.
 101 // If filter is non-null, then only processes selected by the filter are waited
 102 // on.  Killed processes are ended with the given exit code.  Returns false if
 103 // any processes needed to be killed, true if they all exited cleanly within
 104 // the wait_milliseconds delay.
 105 BASE_EXPORT bool CleanupProcesses(const FilePath::StringType& executable_name,
 106                                   base::TimeDelta wait,
 107                                   int exit_code,
 108                                   const ProcessFilter* filter);
 109
 110 // This method ensures that the specified process eventually terminates, and
 111 // then it closes the given process handle.
 112 //
 113 // It assumes that the process has already been signalled to exit, and it
 114 // begins by waiting a small amount of time for it to exit.  If the process
 115 // does not appear to have exited, then this function starts to become
 116 // aggressive about ensuring that the process terminates.
 117 //
 118 // On Linux this method does not block the calling thread.
 119 // On OS X this method may block for up to 2 seconds.
 120 //
 121 // NOTE: The process must have been opened with the PROCESS_TERMINATE and
 122 // SYNCHRONIZE permissions.
 123 //
 124 BASE_EXPORT void EnsureProcessTerminated(Process process);
 125
 126 #if defined(OS_POSIX) && !defined(OS_MACOSX)
 127 // The nicer version of EnsureProcessTerminated() that is patient and will
 128 // wait for |pid| to finish and then reap it.
 129 BASE_EXPORT void EnsureProcessGetsReaped(ProcessId pid);
 130 #endif
 131
 132 }  // namespace base
 133
 134 #endif  // BASE_PROCESS_KILL_H_