kill.h revision 58e6fbe4ee35d65e14b626c557d37565bf8ad179 
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
15namespace base {
16
17class 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.
22enum 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.
36BASE_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.
44BASE_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.
49BASE_EXPORT bool KillProcessGroup(ProcessHandle process_group_id);
50#endif  // defined(OS_POSIX)
51
52#if defined(OS_WIN)
53BASE_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).
66BASE_EXPORT TerminationStatus GetTerminationStatus(ProcessHandle handle,
67                                                   int* exit_code);
68
69#if defined(OS_POSIX)
70// Wait for the process to exit and get the termination status. See
71// GetTerminationStatus for more information. On POSIX systems, we can't call
72// WaitForExitCode and then GetTerminationStatus as the child will be reaped
73// when WaitForExitCode return and this information will be lost.
74BASE_EXPORT TerminationStatus WaitForTerminationStatus(ProcessHandle handle,
75                                                       int* exit_code);
76#endif  // defined(OS_POSIX)
77
78// Waits for process to exit. On POSIX systems, if the process hasn't been
79// signaled then puts the exit code in |exit_code|; otherwise it's considered
80// a failure. On Windows |exit_code| is always filled. Returns true on success,
81// and closes |handle| in any case.
82BASE_EXPORT bool WaitForExitCode(ProcessHandle handle, int* exit_code);
83
84// Waits for process to exit. If it did exit within |timeout_milliseconds|,
85// then puts the exit code in |exit_code|, and returns true.
86// In POSIX systems, if the process has been signaled then |exit_code| is set
87// to -1. Returns false on failure (the caller is then responsible for closing
88// |handle|).
89// The caller is always responsible for closing the |handle|.
90BASE_EXPORT bool WaitForExitCodeWithTimeout(ProcessHandle handle,
91                                            int* exit_code,
92                                            base::TimeDelta timeout);
93
94// Wait for all the processes based on the named executable to exit.  If filter
95// is non-null, then only processes selected by the filter are waited on.
96// Returns after all processes have exited or wait_milliseconds have expired.
97// Returns true if all the processes exited, false otherwise.
98BASE_EXPORT bool WaitForProcessesToExit(
99    const FilePath::StringType& executable_name,
100    base::TimeDelta wait,
101    const ProcessFilter* filter);
102
103// Wait for a single process to exit. Return true if it exited cleanly within
104// the given time limit. On Linux |handle| must be a child process, however
105// on Mac and Windows it can be any process.
106BASE_EXPORT bool WaitForSingleProcess(ProcessHandle handle,
107                                      base::TimeDelta wait);
108
109// Waits a certain amount of time (can be 0) for all the processes with a given
110// executable name to exit, then kills off any of them that are still around.
111// If filter is non-null, then only processes selected by the filter are waited
112// on.  Killed processes are ended with the given exit code.  Returns false if
113// any processes needed to be killed, true if they all exited cleanly within
114// the wait_milliseconds delay.
115BASE_EXPORT bool CleanupProcesses(const FilePath::StringType& executable_name,
116                                  base::TimeDelta wait,
117                                  int exit_code,
118                                  const ProcessFilter* filter);
119
120// This method ensures that the specified process eventually terminates, and
121// then it closes the given process handle.
122//
123// It assumes that the process has already been signalled to exit, and it
124// begins by waiting a small amount of time for it to exit.  If the process
125// does not appear to have exited, then this function starts to become
126// aggressive about ensuring that the process terminates.
127//
128// On Linux this method does not block the calling thread.
129// On OS X this method may block for up to 2 seconds.
130//
131// NOTE: The process handle must have been opened with the PROCESS_TERMINATE
132// and SYNCHRONIZE permissions.
133//
134BASE_EXPORT void EnsureProcessTerminated(ProcessHandle process_handle);
135
136#if defined(OS_POSIX) && !defined(OS_MACOSX)
137// The nicer version of EnsureProcessTerminated() that is patient and will
138// wait for |process_handle| to finish and then reap it.
139BASE_EXPORT void EnsureProcessGetsReaped(ProcessHandle process_handle);
140#endif
141
142}  // namespace base
143
144#endif  // BASE_PROCESS_KILL_H_
145