kill.h revision 7dbb3d5cf0c15f500944d211057644d6a2f37371
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.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