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/move.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 namespace base {
19 
20 // Provides a move-only encapsulation of a process.
21 //
22 // This object is not tied to the lifetime of the underlying process: the
23 // process may be killed and this object may still around, and it will still
24 // claim to be valid. The actual behavior in that case is OS dependent like so:
25 //
26 // Windows: The underlying ProcessHandle will be valid after the process dies
27 // and can be used to gather some information about that process, but most
28 // methods will obviously fail.
29 //
30 // POSIX: The underlying PorcessHandle is not guaranteed to remain valid after
31 // the process dies, and it may be reused by the system, which means that it may
32 // end up pointing to the wrong process.
33 class BASE_EXPORT Process {
34   MOVE_ONLY_TYPE_FOR_CPP_03(Process)
35 
36  public:
37   explicit Process(ProcessHandle handle = kNullProcessHandle);
38 
39   Process(Process&& other);
40 
41   // The destructor does not terminate the process.
42   ~Process();
43 
44   Process& operator=(Process&& other);
45 
46   // Returns an object for the current process.
47   static Process Current();
48 
49   // Returns a Process for the given |pid|.
50   static Process Open(ProcessId pid);
51 
52   // Returns a Process for the given |pid|. On Windows the handle is opened
53   // with more access rights and must only be used by trusted code (can read the
54   // address space and duplicate handles).
55   static Process OpenWithExtraPrivileges(ProcessId pid);
56 
57 #if defined(OS_WIN)
58   // Returns a Process for the given |pid|, using some |desired_access|.
59   // See ::OpenProcess documentation for valid |desired_access|.
60   static Process OpenWithAccess(ProcessId pid, DWORD desired_access);
61 #endif
62 
63   // Creates an object from a |handle| owned by someone else.
64   // Don't use this for new code. It is only intended to ease the migration to
65   // a strict ownership model.
66   // TODO(rvargas) crbug.com/417532: Remove this code.
67   static Process DeprecatedGetProcessFromHandle(ProcessHandle handle);
68 
69   // Returns true if processes can be backgrounded.
70   static bool CanBackgroundProcesses();
71 
72   // Returns true if this objects represents a valid process.
73   bool IsValid() const;
74 
75   // Returns a handle for this process. There is no guarantee about when that
76   // handle becomes invalid because this object retains ownership.
77   ProcessHandle Handle() const;
78 
79   // Returns a second object that represents this process.
80   Process Duplicate() const;
81 
82   // Get the PID for this process.
83   ProcessId Pid() const;
84 
85   // Returns true if this process is the current process.
86   bool is_current() const;
87 
88   // Close the process handle. This will not terminate the process.
89   void Close();
90 
91   // Terminates the process with extreme prejudice. The given |exit_code| will
92   // be the exit code of the process. If |wait| is true, this method will wait
93   // for up to one minute for the process to actually terminate.
94   // Returns true if the process terminates within the allowed time.
95   // NOTE: On POSIX |exit_code| is ignored.
96   bool Terminate(int exit_code, bool wait) const;
97 
98   // Waits for the process to exit. Returns true on success.
99   // On POSIX, if the process has been signaled then |exit_code| is set to -1.
100   // On Linux this must be a child process, however on Mac and Windows it can be
101   // any process.
102   // NOTE: |exit_code| is optional, nullptr can be passed if the exit code is
103   // not required.
104   bool WaitForExit(int* exit_code);
105 
106   // Same as WaitForExit() but only waits for up to |timeout|.
107   // NOTE: |exit_code| is optional, nullptr can be passed if the exit code
108   // is not required.
109   bool WaitForExitWithTimeout(TimeDelta timeout, int* exit_code);
110 
111   // A process is backgrounded when it's priority is lower than normal.
112   // Return true if this process is backgrounded, false otherwise.
113   bool IsProcessBackgrounded() const;
114 
115   // Set a process as backgrounded. If value is true, the priority of the
116   // process will be lowered. If value is false, the priority of the process
117   // will be made "normal" - equivalent to default process priority.
118   // Returns true if the priority was changed, false otherwise.
119   bool SetProcessBackgrounded(bool value);
120 
121   // Returns an integer representing the priority of a process. The meaning
122   // of this value is OS dependent.
123   int GetPriority() const;
124 
125 #if defined(OS_CHROMEOS)
126   // Get the PID in its PID namespace.
127   // If the process is not in a PID namespace or /proc/<pid>/status does not
128   // report NSpid, kNullProcessId is returned.
129   ProcessId GetPidInNamespace() const;
130 #endif
131 
132  private:
133 #if defined(OS_WIN)
134   bool is_current_process_;
135   win::ScopedHandle process_;
136 #else
137   ProcessHandle process_;
138 #endif
139 };
140 
141 #if defined(OS_CHROMEOS)
142 // Exposed for testing.
143 // Given the contents of the /proc/<pid>/cgroup file, determine whether the
144 // process is backgrounded or not.
145 BASE_EXPORT bool IsProcessBackgroundedCGroup(
146     const StringPiece& cgroup_contents);
147 #endif  // defined(OS_CHROMEOS)
148 
149 }  // namespace base
150 
151 #endif  // BASE_PROCESS_PROCESS_H_
152