OLD | NEW |
1 // Copyright 2013 The Chromium Authors. All rights reserved. | 1 // Copyright 2013 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // This file contains functions for launching subprocesses. | 5 // This file contains functions for launching subprocesses. |
6 | 6 |
7 #ifndef BASE_PROCESS_LAUNCH_H_ | 7 #ifndef BASE_PROCESS_LAUNCH_H_ |
8 #define BASE_PROCESS_LAUNCH_H_ | 8 #define BASE_PROCESS_LAUNCH_H_ |
9 | 9 |
10 #include <string> | 10 #include <string> |
11 #include <utility> | 11 #include <utility> |
12 #include <vector> | 12 #include <vector> |
13 | 13 |
14 #include "base/base_export.h" | 14 #include "base/base_export.h" |
15 #include "base/basictypes.h" | 15 #include "base/basictypes.h" |
16 #include "base/environment.h" | 16 #include "base/environment.h" |
17 #include "base/process/process.h" | 17 #include "base/process/process.h" |
18 #include "base/process/process_handle.h" | 18 #include "base/process/process_handle.h" |
19 #include "base/strings/string_piece.h" | 19 #include "base/strings/string_piece.h" |
20 | 20 |
21 #if defined(OS_POSIX) | 21 #if defined(OS_POSIX) |
22 #include "base/posix/file_descriptor_shuffle.h" | 22 #include "base/posix/file_descriptor_shuffle.h" |
23 #elif defined(OS_WIN) | |
24 #include <windows.h> | |
25 #endif | 23 #endif |
26 | 24 |
27 namespace base { | 25 namespace base { |
28 | 26 |
29 class CommandLine; | 27 class CommandLine; |
30 | 28 |
31 #if defined(OS_WIN) | |
32 typedef std::vector<HANDLE> HandlesToInheritVector; | |
33 #endif | |
34 // TODO(viettrungluu): Only define this on POSIX? | 29 // TODO(viettrungluu): Only define this on POSIX? |
35 typedef std::vector<std::pair<int, int> > FileHandleMappingVector; | 30 typedef std::vector<std::pair<int, int> > FileHandleMappingVector; |
36 | 31 |
37 // Options for launching a subprocess that are passed to LaunchProcess(). | 32 // Options for launching a subprocess that are passed to LaunchProcess(). |
38 // The default constructor constructs the object with default options. | 33 // The default constructor constructs the object with default options. |
39 struct BASE_EXPORT LaunchOptions { | 34 struct BASE_EXPORT LaunchOptions { |
40 #if defined(OS_POSIX) | 35 #if defined(OS_POSIX) |
41 // Delegate to be run in between fork and exec in the subprocess (see | 36 // Delegate to be run in between fork and exec in the subprocess (see |
42 // pre_exec_delegate below) | 37 // pre_exec_delegate below) |
43 class BASE_EXPORT PreExecDelegate { | 38 class BASE_EXPORT PreExecDelegate { |
(...skipping 10 matching lines...) Expand all Loading... |
54 DISALLOW_COPY_AND_ASSIGN(PreExecDelegate); | 49 DISALLOW_COPY_AND_ASSIGN(PreExecDelegate); |
55 }; | 50 }; |
56 #endif // defined(OS_POSIX) | 51 #endif // defined(OS_POSIX) |
57 | 52 |
58 LaunchOptions(); | 53 LaunchOptions(); |
59 ~LaunchOptions(); | 54 ~LaunchOptions(); |
60 | 55 |
61 // If true, wait for the process to complete. | 56 // If true, wait for the process to complete. |
62 bool wait; | 57 bool wait; |
63 | 58 |
64 #if defined(OS_WIN) | |
65 bool start_hidden; | |
66 | |
67 // If non-null, inherit exactly the list of handles in this vector (these | |
68 // handles must be inheritable). This is only supported on Vista and higher. | |
69 HandlesToInheritVector* handles_to_inherit; | |
70 | |
71 // If true, the new process inherits handles from the parent. In production | |
72 // code this flag should be used only when running short-lived, trusted | |
73 // binaries, because open handles from other libraries and subsystems will | |
74 // leak to the child process, causing errors such as open socket hangs. | |
75 // Note: If |handles_to_inherit| is non-null, this flag is ignored and only | |
76 // those handles will be inherited (on Vista and higher). | |
77 bool inherit_handles; | |
78 | |
79 // If non-null, runs as if the user represented by the token had launched it. | |
80 // Whether the application is visible on the interactive desktop depends on | |
81 // the token belonging to an interactive logon session. | |
82 // | |
83 // To avoid hard to diagnose problems, when specified this loads the | |
84 // environment variables associated with the user and if this operation fails | |
85 // the entire call fails as well. | |
86 UserTokenHandle as_user; | |
87 | |
88 // If true, use an empty string for the desktop name. | |
89 bool empty_desktop_name; | |
90 | |
91 // If non-null, launches the application in that job object. The process will | |
92 // be terminated immediately and LaunchProcess() will fail if assignment to | |
93 // the job object fails. | |
94 HANDLE job_handle; | |
95 | |
96 // Handles for the redirection of stdin, stdout and stderr. The handles must | |
97 // be inheritable. Caller should either set all three of them or none (i.e. | |
98 // there is no way to redirect stderr without redirecting stdin). The | |
99 // |inherit_handles| flag must be set to true when redirecting stdio stream. | |
100 HANDLE stdin_handle; | |
101 HANDLE stdout_handle; | |
102 HANDLE stderr_handle; | |
103 | |
104 // If set to true, ensures that the child process is launched with the | |
105 // CREATE_BREAKAWAY_FROM_JOB flag which allows it to breakout of the parent | |
106 // job if any. | |
107 bool force_breakaway_from_job_; | |
108 #else | |
109 // Set/unset environment variables. These are applied on top of the parent | 59 // Set/unset environment variables. These are applied on top of the parent |
110 // process environment. Empty (the default) means to inherit the same | 60 // process environment. Empty (the default) means to inherit the same |
111 // environment. See AlterEnvironment(). | 61 // environment. See AlterEnvironment(). |
112 EnvironmentMap environ; | 62 EnvironmentMap environ; |
113 | 63 |
114 // Clear the environment for the new process before processing changes from | 64 // Clear the environment for the new process before processing changes from |
115 // |environ|. | 65 // |environ|. |
116 bool clear_environ; | 66 bool clear_environ; |
117 | 67 |
118 // If non-null, remap file descriptors according to the mapping of | 68 // If non-null, remap file descriptors according to the mapping of |
(...skipping 48 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
167 | 117 |
168 #if defined(OS_MACOSX) | 118 #if defined(OS_MACOSX) |
169 // If this name is non-empty, the new child, after fork() but before exec(), | 119 // If this name is non-empty, the new child, after fork() but before exec(), |
170 // will look up this server name in the bootstrap namespace. The resulting | 120 // will look up this server name in the bootstrap namespace. The resulting |
171 // service port will be replaced as the bootstrap port in the child. Because | 121 // service port will be replaced as the bootstrap port in the child. Because |
172 // the process's IPC space is cleared on exec(), any rights to the old | 122 // the process's IPC space is cleared on exec(), any rights to the old |
173 // bootstrap port will not be transferred to the new process. | 123 // bootstrap port will not be transferred to the new process. |
174 std::string replacement_bootstrap_name; | 124 std::string replacement_bootstrap_name; |
175 #endif | 125 #endif |
176 | 126 |
177 #endif // !defined(OS_WIN) | |
178 }; | 127 }; |
179 | 128 |
180 // Launch a process via the command line |cmdline|. | 129 // Launch a process via the command line |cmdline|. |
181 // See the documentation of LaunchOptions for details on |options|. | 130 // See the documentation of LaunchOptions for details on |options|. |
182 // | 131 // |
183 // Returns a valid Process upon success. | 132 // Returns a valid Process upon success. |
184 // | 133 // |
185 // Unix-specific notes: | 134 // Unix-specific notes: |
186 // - All file descriptors open in the parent process will be closed in the | 135 // - All file descriptors open in the parent process will be closed in the |
187 // child process except for any preserved by options::fds_to_remap, and | 136 // child process except for any preserved by options::fds_to_remap, and |
188 // stdin, stdout, and stderr. If not remapped by options::fds_to_remap, | 137 // stdin, stdout, and stderr. If not remapped by options::fds_to_remap, |
189 // stdin is reopened as /dev/null, and the child is allowed to inherit its | 138 // stdin is reopened as /dev/null, and the child is allowed to inherit its |
190 // parent's stdout and stderr. | 139 // parent's stdout and stderr. |
191 // - If the first argument on the command line does not contain a slash, | 140 // - If the first argument on the command line does not contain a slash, |
192 // PATH will be searched. (See man execvp.) | 141 // PATH will be searched. (See man execvp.) |
193 BASE_EXPORT Process LaunchProcess(const CommandLine& cmdline, | 142 BASE_EXPORT Process LaunchProcess(const CommandLine& cmdline, |
194 const LaunchOptions& options); | 143 const LaunchOptions& options); |
195 | 144 |
196 #if defined(OS_WIN) | 145 #if defined(OS_POSIX) |
197 // Windows-specific LaunchProcess that takes the command line as a | |
198 // string. Useful for situations where you need to control the | |
199 // command line arguments directly, but prefer the CommandLine version | |
200 // if launching Chrome itself. | |
201 // | |
202 // The first command line argument should be the path to the process, | |
203 // and don't forget to quote it. | |
204 // | |
205 // Example (including literal quotes) | |
206 // cmdline = "c:\windows\explorer.exe" -foo "c:\bar\" | |
207 BASE_EXPORT Process LaunchProcess(const string16& cmdline, | |
208 const LaunchOptions& options); | |
209 | |
210 // Launches a process with elevated privileges. This does not behave exactly | |
211 // like LaunchProcess as it uses ShellExecuteEx instead of CreateProcess to | |
212 // create the process. This means the process will have elevated privileges | |
213 // and thus some common operations like OpenProcess will fail. Currently the | |
214 // only supported LaunchOptions are |start_hidden| and |wait|. | |
215 BASE_EXPORT Process LaunchElevatedProcess(const CommandLine& cmdline, | |
216 const LaunchOptions& options); | |
217 | |
218 #elif defined(OS_POSIX) | |
219 // A POSIX-specific version of LaunchProcess that takes an argv array | 146 // A POSIX-specific version of LaunchProcess that takes an argv array |
220 // instead of a CommandLine. Useful for situations where you need to | 147 // instead of a CommandLine. Useful for situations where you need to |
221 // control the command line arguments directly, but prefer the | 148 // control the command line arguments directly, but prefer the |
222 // CommandLine version if launching Chrome itself. | 149 // CommandLine version if launching Chrome itself. |
223 BASE_EXPORT Process LaunchProcess(const std::vector<std::string>& argv, | 150 BASE_EXPORT Process LaunchProcess(const std::vector<std::string>& argv, |
224 const LaunchOptions& options); | 151 const LaunchOptions& options); |
225 | 152 |
226 // Close all file descriptors, except those which are a destination in the | 153 // Close all file descriptors, except those which are a destination in the |
227 // given multimap. Only call this function in a child process where you know | 154 // given multimap. Only call this function in a child process where you know |
228 // that there aren't any other threads. | 155 // that there aren't any other threads. |
229 BASE_EXPORT void CloseSuperfluousFds(const InjectiveMultimap& saved_map); | 156 BASE_EXPORT void CloseSuperfluousFds(const InjectiveMultimap& saved_map); |
230 #endif // defined(OS_POSIX) | 157 #endif // defined(OS_POSIX) |
231 | 158 |
232 #if defined(OS_WIN) | |
233 // Set |job_object|'s JOBOBJECT_EXTENDED_LIMIT_INFORMATION | |
234 // BasicLimitInformation.LimitFlags to |limit_flags|. | |
235 BASE_EXPORT bool SetJobObjectLimitFlags(HANDLE job_object, DWORD limit_flags); | |
236 | |
237 // Output multi-process printf, cout, cerr, etc to the cmd.exe console that ran | |
238 // chrome. This is not thread-safe: only call from main thread. | |
239 BASE_EXPORT void RouteStdioToConsole(); | |
240 #endif // defined(OS_WIN) | |
241 | |
242 // Executes the application specified by |cl| and wait for it to exit. Stores | 159 // Executes the application specified by |cl| and wait for it to exit. Stores |
243 // the output (stdout) in |output|. Redirects stderr to /dev/null. Returns true | 160 // the output (stdout) in |output|. Redirects stderr to /dev/null. Returns true |
244 // on success (application launched and exited cleanly, with exit code | 161 // on success (application launched and exited cleanly, with exit code |
245 // indicating success). | 162 // indicating success). |
246 BASE_EXPORT bool GetAppOutput(const CommandLine& cl, std::string* output); | 163 BASE_EXPORT bool GetAppOutput(const CommandLine& cl, std::string* output); |
247 | 164 |
248 #if defined(OS_WIN) | |
249 // A Windows-specific version of GetAppOutput that takes a command line string | |
250 // instead of a CommandLine object. Useful for situations where you need to | |
251 // control the command line arguments directly. | |
252 BASE_EXPORT bool GetAppOutput(const StringPiece16& cl, std::string* output); | |
253 #endif | |
254 | |
255 #if defined(OS_POSIX) | 165 #if defined(OS_POSIX) |
256 // A POSIX-specific version of GetAppOutput that takes an argv array | 166 // A POSIX-specific version of GetAppOutput that takes an argv array |
257 // instead of a CommandLine. Useful for situations where you need to | 167 // instead of a CommandLine. Useful for situations where you need to |
258 // control the command line arguments directly. | 168 // control the command line arguments directly. |
259 BASE_EXPORT bool GetAppOutput(const std::vector<std::string>& argv, | 169 BASE_EXPORT bool GetAppOutput(const std::vector<std::string>& argv, |
260 std::string* output); | 170 std::string* output); |
261 | 171 |
262 // A restricted version of |GetAppOutput()| which (a) clears the environment, | 172 // A restricted version of |GetAppOutput()| which (a) clears the environment, |
263 // and (b) stores at most |max_output| bytes; also, it doesn't search the path | 173 // and (b) stores at most |max_output| bytes; also, it doesn't search the path |
264 // for the command. | 174 // for the command. |
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
312 // multiple threads are running, since at the time the fork happened, the | 222 // multiple threads are running, since at the time the fork happened, the |
313 // threads could have been in any state (potentially holding locks, etc.). | 223 // threads could have been in any state (potentially holding locks, etc.). |
314 // Callers should most likely call execve() in the child soon after calling | 224 // Callers should most likely call execve() in the child soon after calling |
315 // this. | 225 // this. |
316 BASE_EXPORT pid_t ForkWithFlags(unsigned long flags, pid_t* ptid, pid_t* ctid); | 226 BASE_EXPORT pid_t ForkWithFlags(unsigned long flags, pid_t* ptid, pid_t* ctid); |
317 #endif | 227 #endif |
318 | 228 |
319 } // namespace base | 229 } // namespace base |
320 | 230 |
321 #endif // BASE_PROCESS_LAUNCH_H_ | 231 #endif // BASE_PROCESS_LAUNCH_H_ |
OLD | NEW |