123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162 |
- // Copyright (c) 2013 The Chromium Authors. All rights reserved.
- // Use of this source code is governed by a BSD-style license that can be
- // found in the LICENSE file.
- // This file contains routines to kill processes and get the exit code and
- // termination status.
- #ifndef BASE_PROCESS_KILL_H_
- #define BASE_PROCESS_KILL_H_
- #include "butil/files/file_path.h"
- #include "butil/process/process_handle.h"
- #include "butil/time/time.h"
- namespace butil {
- class ProcessFilter;
- // Return status values from GetTerminationStatus. Don't use these as
- // exit code arguments to KillProcess*(), use platform/application
- // specific values instead.
- enum TerminationStatus {
- TERMINATION_STATUS_NORMAL_TERMINATION, // zero exit status
- TERMINATION_STATUS_ABNORMAL_TERMINATION, // non-zero exit status
- TERMINATION_STATUS_PROCESS_WAS_KILLED, // e.g. SIGKILL or task manager kill
- TERMINATION_STATUS_PROCESS_CRASHED, // e.g. Segmentation fault
- TERMINATION_STATUS_STILL_RUNNING, // child hasn't exited yet
- #if defined(OS_ANDROID)
- // On Android processes are spawned from the system Zygote and we do not get
- // the termination status. We can't know if the termination was a crash or an
- // oom kill for sure, but we can use status of the strong process bindings as
- // a hint.
- TERMINATION_STATUS_OOM_PROTECTED, // child was protected from oom kill
- #endif
- TERMINATION_STATUS_MAX_ENUM
- };
- // Attempts to kill all the processes on the current machine that were launched
- // from the given executable name, ending them with the given exit code. If
- // filter is non-null, then only processes selected by the filter are killed.
- // Returns true if all processes were able to be killed off, false if at least
- // one couldn't be killed.
- BASE_EXPORT bool KillProcesses(const FilePath::StringType& executable_name,
- int exit_code,
- const ProcessFilter* filter);
- // Attempts to kill the process identified by the given process
- // entry structure, giving it the specified exit code. If |wait| is true, wait
- // for the process to be actually terminated before returning.
- // Returns true if this is successful, false otherwise.
- BASE_EXPORT bool KillProcess(ProcessHandle process, int exit_code, bool wait);
- #if defined(OS_POSIX)
- // Attempts to kill the process group identified by |process_group_id|. Returns
- // true on success.
- BASE_EXPORT bool KillProcessGroup(ProcessHandle process_group_id);
- #endif // defined(OS_POSIX)
- #if defined(OS_WIN)
- BASE_EXPORT bool KillProcessById(ProcessId process_id,
- int exit_code,
- bool wait);
- #endif // defined(OS_WIN)
- // Get the termination status of the process by interpreting the
- // circumstances of the child process' death. |exit_code| is set to
- // the status returned by waitpid() on POSIX, and from
- // GetExitCodeProcess() on Windows. |exit_code| may be NULL if the
- // caller is not interested in it. Note that on Linux, this function
- // will only return a useful result the first time it is called after
- // the child exits (because it will reap the child and the information
- // will no longer be available).
- BASE_EXPORT TerminationStatus GetTerminationStatus(ProcessHandle handle,
- int* exit_code);
- #if defined(OS_POSIX)
- // Send a kill signal to the process and then wait for the process to exit
- // and get the termination status.
- //
- // This is used in situations where it is believed that the process is dead
- // or dying (because communication with the child process has been cut).
- // In order to avoid erroneously returning that the process is still running
- // because the kernel is still cleaning it up, this will wait for the process
- // to terminate. In order to avoid the risk of hanging while waiting for the
- // process to terminate, send a SIGKILL to the process before waiting for the
- // termination status.
- //
- // Note that it is not an option to call WaitForExitCode and then
- // GetTerminationStatus as the child will be reaped when WaitForExitCode
- // returns, and this information will be lost.
- //
- BASE_EXPORT TerminationStatus GetKnownDeadTerminationStatus(
- ProcessHandle handle, int* exit_code);
- #endif // defined(OS_POSIX)
- // Waits for process to exit. On POSIX systems, if the process hasn't been
- // signaled then puts the exit code in |exit_code|; otherwise it's considered
- // a failure. On Windows |exit_code| is always filled. Returns true on success,
- // and closes |handle| in any case.
- BASE_EXPORT bool WaitForExitCode(ProcessHandle handle, int* exit_code);
- // Waits for process to exit. If it did exit within |timeout_milliseconds|,
- // then puts the exit code in |exit_code|, and returns true.
- // In POSIX systems, if the process has been signaled then |exit_code| is set
- // to -1. Returns false on failure (the caller is then responsible for closing
- // |handle|).
- // The caller is always responsible for closing the |handle|.
- BASE_EXPORT bool WaitForExitCodeWithTimeout(ProcessHandle handle,
- int* exit_code,
- butil::TimeDelta timeout);
- // Wait for all the processes based on the named executable to exit. If filter
- // is non-null, then only processes selected by the filter are waited on.
- // Returns after all processes have exited or wait_milliseconds have expired.
- // Returns true if all the processes exited, false otherwise.
- BASE_EXPORT bool WaitForProcessesToExit(
- const FilePath::StringType& executable_name,
- butil::TimeDelta wait,
- const ProcessFilter* filter);
- // Wait for a single process to exit. Return true if it exited cleanly within
- // the given time limit. On Linux |handle| must be a child process, however
- // on Mac and Windows it can be any process.
- BASE_EXPORT bool WaitForSingleProcess(ProcessHandle handle,
- butil::TimeDelta wait);
- // Waits a certain amount of time (can be 0) for all the processes with a given
- // executable name to exit, then kills off any of them that are still around.
- // If filter is non-null, then only processes selected by the filter are waited
- // on. Killed processes are ended with the given exit code. Returns false if
- // any processes needed to be killed, true if they all exited cleanly within
- // the wait_milliseconds delay.
- BASE_EXPORT bool CleanupProcesses(const FilePath::StringType& executable_name,
- butil::TimeDelta wait,
- int exit_code,
- const ProcessFilter* filter);
- // This method ensures that the specified process eventually terminates, and
- // then it closes the given process handle.
- //
- // It assumes that the process has already been signalled to exit, and it
- // begins by waiting a small amount of time for it to exit. If the process
- // does not appear to have exited, then this function starts to become
- // aggressive about ensuring that the process terminates.
- //
- // On Linux this method does not block the calling thread.
- // On OS X this method may block for up to 2 seconds.
- //
- // NOTE: The process handle must have been opened with the PROCESS_TERMINATE
- // and SYNCHRONIZE permissions.
- //
- BASE_EXPORT void EnsureProcessTerminated(ProcessHandle process_handle);
- #if defined(OS_POSIX) && !defined(OS_MACOSX)
- // The nicer version of EnsureProcessTerminated() that is patient and will
- // wait for |process_handle| to finish and then reap it.
- BASE_EXPORT void EnsureProcessGetsReaped(ProcessHandle process_handle);
- #endif
- } // namespace butil
- #endif // BASE_PROCESS_KILL_H_
|