1 // Copyright 2011 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 #ifndef BASE_PROCESS_PROCESS_H_ 6 #define BASE_PROCESS_PROCESS_H_ 7 8 #include "base/base_export.h" 9 #include "base/macros.h" 10 #include "base/process/process_handle.h" 11 #include "base/time/time.h" 12 #include "build/build_config.h" 13 14 #if defined(OS_WIN) 15 #include "base/win/scoped_handle.h" 16 #endif 17 18 #if defined(OS_FUCHSIA) 19 #include <lib/zx/process.h> 20 #endif 21 22 #if defined(OS_MACOSX) 23 #include "base/feature_list.h" 24 #include "base/process/port_provider_mac.h" 25 #endif 26 27 namespace base { 28 29 #if defined(OS_MACOSX) 30 extern const Feature kMacAllowBackgroundingProcesses; 31 #endif 32 33 // Provides a move-only encapsulation of a process. 34 // 35 // This object is not tied to the lifetime of the underlying process: the 36 // process may be killed and this object may still around, and it will still 37 // claim to be valid. The actual behavior in that case is OS dependent like so: 38 // 39 // Windows: The underlying ProcessHandle will be valid after the process dies 40 // and can be used to gather some information about that process, but most 41 // methods will obviously fail. 42 // 43 // POSIX: The underlying ProcessHandle is not guaranteed to remain valid after 44 // the process dies, and it may be reused by the system, which means that it may 45 // end up pointing to the wrong process. 46 class BASE_EXPORT Process { 47 public: 48 // On Windows, this takes ownership of |handle|. On POSIX, this does not take 49 // ownership of |handle|. 50 explicit Process(ProcessHandle handle = kNullProcessHandle); 51 52 Process(Process&& other); 53 54 // The destructor does not terminate the process. 55 ~Process(); 56 57 Process& operator=(Process&& other); 58 59 // Returns an object for the current process. 60 static Process Current(); 61 62 // Returns a Process for the given |pid|. 63 static Process Open(ProcessId pid); 64 65 // Returns a Process for the given |pid|. On Windows the handle is opened 66 // with more access rights and must only be used by trusted code (can read the 67 // address space and duplicate handles). 68 static Process OpenWithExtraPrivileges(ProcessId pid); 69 70 #if defined(OS_WIN) 71 // Returns a Process for the given |pid|, using some |desired_access|. 72 // See ::OpenProcess documentation for valid |desired_access|. 73 static Process OpenWithAccess(ProcessId pid, DWORD desired_access); 74 #endif 75 76 // Creates an object from a |handle| owned by someone else. 77 // Don't use this for new code. It is only intended to ease the migration to 78 // a strict ownership model. 79 // TODO(rvargas) crbug.com/417532: Remove this code. 80 static Process DeprecatedGetProcessFromHandle(ProcessHandle handle); 81 82 // Returns true if processes can be backgrounded. 83 static bool CanBackgroundProcesses(); 84 85 // Terminates the current process immediately with |exit_code|. 86 [[noreturn]] static void TerminateCurrentProcessImmediately(int exit_code); 87 88 // Returns true if this objects represents a valid process. 89 bool IsValid() const; 90 91 // Returns a handle for this process. There is no guarantee about when that 92 // handle becomes invalid because this object retains ownership. 93 ProcessHandle Handle() const; 94 95 // Returns a second object that represents this process. 96 Process Duplicate() const; 97 98 // Get the PID for this process. 99 ProcessId Pid() const; 100 101 // Returns true if this process is the current process. 102 bool is_current() const; 103 104 // Close the process handle. This will not terminate the process. 105 void Close(); 106 107 // Returns true if this process is still running. This is only safe on Windows 108 // (and maybe Fuchsia?), because the ProcessHandle will keep the zombie 109 // process information available until itself has been released. But on Posix, 110 // the OS may reuse the ProcessId. 111 #if defined(OS_WIN) IsRunning()112 bool IsRunning() const { 113 return !WaitForExitWithTimeout(base::TimeDelta(), nullptr); 114 } 115 #endif 116 117 // Terminates the process with extreme prejudice. The given |exit_code| will 118 // be the exit code of the process. If |wait| is true, this method will wait 119 // for up to one minute for the process to actually terminate. 120 // Returns true if the process terminates within the allowed time. 121 // NOTE: On POSIX |exit_code| is ignored. 122 bool Terminate(int exit_code, bool wait) const; 123 124 // Waits for the process to exit. Returns true on success. 125 // On POSIX, if the process has been signaled then |exit_code| is set to -1. 126 // On Linux this must be a child process, however on Mac and Windows it can be 127 // any process. 128 // NOTE: |exit_code| is optional, nullptr can be passed if the exit code is 129 // not required. 130 bool WaitForExit(int* exit_code) const; 131 132 // Same as WaitForExit() but only waits for up to |timeout|. 133 // NOTE: |exit_code| is optional, nullptr can be passed if the exit code 134 // is not required. 135 bool WaitForExitWithTimeout(TimeDelta timeout, int* exit_code) const; 136 137 // Indicates that the process has exited with the specified |exit_code|. 138 // This should be called if process exit is observed outside of this class. 139 // (i.e. Not because Terminate or WaitForExit, above, was called.) 140 // Note that nothing prevents this being called multiple times for a dead 141 // process though that should be avoided. 142 void Exited(int exit_code) const; 143 144 #if defined(OS_MACOSX) 145 // The Mac needs a Mach port in order to manipulate a process's priority, 146 // and there's no good way to get that from base given the pid. These Mac 147 // variants of the IsProcessBackgrounded and SetProcessBackgrounded API take 148 // a port provider for this reason. See crbug.com/460102 149 // 150 // A process is backgrounded when its task priority is 151 // |TASK_BACKGROUND_APPLICATION|. 152 // 153 // Returns true if the port_provider can locate a task port for the process 154 // and it is backgrounded. If port_provider is null, returns false. 155 bool IsProcessBackgrounded(PortProvider* port_provider) const; 156 157 // Set the process as backgrounded. If value is 158 // true, the priority of the associated task will be set to 159 // TASK_BACKGROUND_APPLICATION. If value is false, the 160 // priority of the process will be set to TASK_FOREGROUND_APPLICATION. 161 // 162 // Returns true if the priority was changed, false otherwise. If 163 // |port_provider| is null, this is a no-op and it returns false. 164 bool SetProcessBackgrounded(PortProvider* port_provider, bool value); 165 #else 166 // A process is backgrounded when it's priority is lower than normal. 167 // Return true if this process is backgrounded, false otherwise. 168 bool IsProcessBackgrounded() const; 169 170 // Set a process as backgrounded. If value is true, the priority of the 171 // process will be lowered. If value is false, the priority of the process 172 // will be made "normal" - equivalent to default process priority. 173 // Returns true if the priority was changed, false otherwise. 174 bool SetProcessBackgrounded(bool value); 175 #endif // defined(OS_MACOSX) 176 // Returns an integer representing the priority of a process. The meaning 177 // of this value is OS dependent. 178 int GetPriority() const; 179 180 #if defined(OS_CHROMEOS) 181 // Get the PID in its PID namespace. 182 // If the process is not in a PID namespace or /proc/<pid>/status does not 183 // report NSpid, kNullProcessId is returned. 184 ProcessId GetPidInNamespace() const; 185 #endif 186 187 private: 188 #if defined(OS_WIN) 189 win::ScopedHandle process_; 190 #elif defined(OS_FUCHSIA) 191 zx::process process_; 192 #else 193 ProcessHandle process_; 194 #endif 195 196 #if defined(OS_WIN) || defined(OS_FUCHSIA) 197 bool is_current_process_; 198 #endif 199 200 DISALLOW_COPY_AND_ASSIGN(Process); 201 }; 202 203 #if defined(OS_CHROMEOS) 204 // Exposed for testing. 205 // Given the contents of the /proc/<pid>/cgroup file, determine whether the 206 // process is backgrounded or not. 207 BASE_EXPORT bool IsProcessBackgroundedCGroup( 208 const StringPiece& cgroup_contents); 209 #endif // defined(OS_CHROMEOS) 210 211 } // namespace base 212 213 #endif // BASE_PROCESS_PROCESS_H_ 214