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 #if defined(OS_POSIX)
  49 // Attempts to kill the process group identified by |process_group_id|. Returns
  50 // true on success.
  51 BASE_EXPORT bool KillProcessGroup(ProcessHandle process_group_id);
  52 #endif  // defined(OS_POSIX)
  53
  54 // Get the termination status of the process by interpreting the
  55 // circumstances of the child process' death. |exit_code| is set to
  56 // the status returned by waitpid() on POSIX, and from
  57 // GetExitCodeProcess() on Windows.  |exit_code| may be NULL if the
  58 // caller is not interested in it.  Note that on Linux, this function
  59 // will only return a useful result the first time it is called after
  60 // the child exits (because it will reap the child and the information
  61 // will no longer be available).
  62 BASE_EXPORT TerminationStatus GetTerminationStatus(ProcessHandle handle,
  63                                                    int* exit_code);
  64
  65 #if defined(OS_POSIX)
  66 // Send a kill signal to the process and then wait for the process to exit
  67 // and get the termination status.
  68 //
  69 // This is used in situations where it is believed that the process is dead
  70 // or dying (because communication with the child process has been cut).
  71 // In order to avoid erroneously returning that the process is still running
  72 // because the kernel is still cleaning it up, this will wait for the process
  73 // to terminate. In order to avoid the risk of hanging while waiting for the
  74 // process to terminate, send a SIGKILL to the process before waiting for the
  75 // termination status.
  76 //
  77 // Note that it is not an option to call WaitForExitCode and then
  78 // GetTerminationStatus as the child will be reaped when WaitForExitCode
  79 // returns, and this information will be lost.
  80 //
  81 BASE_EXPORT TerminationStatus GetKnownDeadTerminationStatus(
  82     ProcessHandle handle, int* exit_code);
  83 #endif  // defined(OS_POSIX)
  84
  85 // Wait for all the processes based on the named executable to exit.  If filter
  86 // is non-null, then only processes selected by the filter are waited on.
  87 // Returns after all processes have exited or wait_milliseconds have expired.
  88 // Returns true if all the processes exited, false otherwise.
  89 BASE_EXPORT bool WaitForProcessesToExit(
  90     const FilePath::StringType& executable_name,
  91     base::TimeDelta wait,
  92     const ProcessFilter* filter);
  93
  94 // Waits a certain amount of time (can be 0) for all the processes with a given
  95 // executable name to exit, then kills off any of them that are still around.
  96 // If filter is non-null, then only processes selected by the filter are waited
  97 // on.  Killed processes are ended with the given exit code.  Returns false if
  98 // any processes needed to be killed, true if they all exited cleanly within
  99 // the wait_milliseconds delay.
 100 BASE_EXPORT bool CleanupProcesses(const FilePath::StringType& executable_name,
 101                                   base::TimeDelta wait,
 102                                   int exit_code,
 103                                   const ProcessFilter* filter);
 104
 105 // This method ensures that the specified process eventually terminates, and
 106 // then it closes the given process handle.
 107 //
 108 // It assumes that the process has already been signalled to exit, and it
 109 // begins by waiting a small amount of time for it to exit.  If the process
 110 // does not appear to have exited, then this function starts to become
 111 // aggressive about ensuring that the process terminates.
 112 //
 113 // On Linux this method does not block the calling thread.
 114 // On OS X this method may block for up to 2 seconds.
 115 //
 116 // NOTE: The process must have been opened with the PROCESS_TERMINATE and
 117 // SYNCHRONIZE permissions.
 118 //
 119 BASE_EXPORT void EnsureProcessTerminated(Process process);
 120
 121 #if defined(OS_POSIX) && !defined(OS_MACOSX)
 122 // The nicer version of EnsureProcessTerminated() that is patient and will
 123 // wait for |pid| to finish and then reap it.
 124 BASE_EXPORT void EnsureProcessGetsReaped(ProcessId pid);
 125 #endif
 126
 127 }  // namespace base
 128
 129 #endif  // BASE_PROCESS_KILL_H_