xref: /aosp_15_r20/external/cronet/base/process/launch.h (revision 6777b5387eb2ff775bb5750e3f5d96f37fb7352b)
1 // Copyright 2013 The Chromium Authors
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 functions for launching subprocesses.
6 
7 #ifndef BASE_PROCESS_LAUNCH_H_
8 #define BASE_PROCESS_LAUNCH_H_
9 
10 #include <stddef.h>
11 
12 #include <string>
13 #include <string_view>
14 #include <utility>
15 #include <vector>
16 
17 #include "base/base_export.h"
18 #include "base/command_line.h"
19 #include "base/environment.h"
20 #include "base/files/file_path.h"
21 #include "base/memory/raw_ptr.h"
22 #include "base/process/process.h"
23 #include "base/process/process_handle.h"
24 #include "base/threading/thread_restrictions.h"
25 #include "build/blink_buildflags.h"
26 #include "build/build_config.h"
27 
28 #if BUILDFLAG(IS_WIN)
29 #include "base/win/windows_types.h"
30 #elif BUILDFLAG(IS_FUCHSIA)
31 #include <lib/fdio/spawn.h>
32 #include <zircon/types.h>
33 #endif
34 
35 #if BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
36 #include "base/posix/file_descriptor_shuffle.h"
37 #endif
38 
39 namespace base {
40 
41 #if BUILDFLAG(IS_APPLE)
42 class MachRendezvousPort;
43 using MachPortsForRendezvous = std::map<uint32_t, MachRendezvousPort>;
44 #endif
45 
46 #if BUILDFLAG(IS_WIN)
47 typedef std::vector<HANDLE> HandlesToInheritVector;
48 #elif BUILDFLAG(IS_FUCHSIA)
49 struct PathToTransfer {
50   base::FilePath path;
51   zx_handle_t handle;
52 };
53 struct HandleToTransfer {
54   uint32_t id;
55   zx_handle_t handle;
56 };
57 typedef std::vector<HandleToTransfer> HandlesToTransferVector;
58 typedef std::vector<std::pair<int, int>> FileHandleMappingVector;
59 #elif BUILDFLAG(IS_POSIX)
60 typedef std::vector<std::pair<int, int>> FileHandleMappingVector;
61 #endif  // BUILDFLAG(IS_WIN)
62 
63 // Options for launching a subprocess that are passed to LaunchProcess().
64 // The default constructor constructs the object with default options.
65 struct BASE_EXPORT LaunchOptions {
66 #if (BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)) && !BUILDFLAG(IS_APPLE)
67   // Delegate to be run in between fork and exec in the subprocess (see
68   // pre_exec_delegate below)
69   class BASE_EXPORT PreExecDelegate {
70    public:
71     PreExecDelegate() = default;
72 
73     PreExecDelegate(const PreExecDelegate&) = delete;
74     PreExecDelegate& operator=(const PreExecDelegate&) = delete;
75 
76     virtual ~PreExecDelegate() = default;
77 
78     // Since this is to be run between fork and exec, and fork may have happened
79     // while multiple threads were running, this function needs to be async
80     // safe.
81     virtual void RunAsyncSafe() = 0;
82   };
83 #endif  // BUILDFLAG(IS_POSIX)
84 
85   LaunchOptions();
86   LaunchOptions(const LaunchOptions&);
87   ~LaunchOptions();
88 
89   // If true, wait for the process to complete.
90   bool wait = false;
91 
92   // If not empty, change to this directory before executing the new process.
93   base::FilePath current_directory;
94 
95 #if BUILDFLAG(IS_WIN)
96   bool start_hidden = false;
97 
98   // Process will be started using ShellExecuteEx instead of CreateProcess so
99   // that it is elevated. LaunchProcess with this flag will have different
100   // behaviour due to ShellExecuteEx. Some common operations like OpenProcess
101   // will fail. Currently the only other supported LaunchOptions are
102   // |start_hidden| and |wait|.
103   bool elevated = false;
104 
105   // Sets STARTF_FORCEOFFFEEDBACK so that the feedback cursor is forced off
106   // while the process is starting.
107   bool feedback_cursor_off = false;
108 
109   // Windows can inherit handles when it launches child processes.
110   // See https://blogs.msdn.microsoft.com/oldnewthing/20111216-00/?p=8873
111   // for a good overview of Windows handle inheritance.
112   //
113   // Implementation note: it might be nice to implement in terms of
114   // std::optional<>, but then the natural default state (vector not present)
115   // would be "all inheritable handles" while we want "no inheritance."
116   enum class Inherit {
117     // Only those handles in |handles_to_inherit| vector are inherited. If the
118     // vector is empty, no handles are inherited. The handles in the vector must
119     // all be inheritable.
120     kSpecific,
121 
122     // All handles in the current process which are inheritable are inherited.
123     // In production code this flag should be used only when running
124     // short-lived, trusted binaries, because open handles from other libraries
125     // and subsystems will leak to the child process, causing errors such as
126     // open socket hangs. There are also race conditions that can cause handle
127     // over-sharing.
128     //
129     // |handles_to_inherit| must be null.
130     //
131     // DEPRECATED. THIS SHOULD NOT BE USED. Explicitly map all handles that
132     // need to be shared in new code.
133     // TODO(brettw) bug 748258: remove this.
134     kAll
135   };
136   Inherit inherit_mode = Inherit::kSpecific;
137   HandlesToInheritVector handles_to_inherit;
138 
139   // If non-null, runs as if the user represented by the token had launched it.
140   // Whether the application is visible on the interactive desktop depends on
141   // the token belonging to an interactive logon session.
142   //
143   // To avoid hard to diagnose problems, when specified this loads the
144   // environment variables associated with the user and if this operation fails
145   // the entire call fails as well.
146   UserTokenHandle as_user = nullptr;
147 
148   // If true, use an empty string for the desktop name.
149   bool empty_desktop_name = false;
150 
151   // If non-null, launches the application in that job object. The process will
152   // be terminated immediately and LaunchProcess() will fail if assignment to
153   // the job object fails.
154   HANDLE job_handle = nullptr;
155 
156   // Handles for the redirection of stdin, stdout and stderr. The caller should
157   // either set all three of them or none (i.e. there is no way to redirect
158   // stderr without redirecting stdin).
159   //
160   // The handles must be inheritable. Pseudo handles are used when stdout and
161   // stderr redirect to the console. In that case, GetFileType() will return
162   // FILE_TYPE_CHAR and they're automatically inherited by child processes. See
163   // https://msdn.microsoft.com/en-us/library/windows/desktop/ms682075.aspx
164   // Otherwise, the caller must ensure that the |inherit_mode| and/or
165   // |handles_to_inherit| set so that the handles are inherited.
166   HANDLE stdin_handle = nullptr;
167   HANDLE stdout_handle = nullptr;
168   HANDLE stderr_handle = nullptr;
169 
170   // If set to true, ensures that the child process is launched with the
171   // CREATE_BREAKAWAY_FROM_JOB flag which allows it to breakout of the parent
172   // job if any.
173   bool force_breakaway_from_job_ = false;
174 
175   // If set to true, permission to bring windows to the foreground is passed to
176   // the launched process if the current process has such permission.
177   bool grant_foreground_privilege = false;
178 
179   // If set to true, sets a process mitigation flag to disable Hardware-enforced
180   // Stack Protection for the process.
181   // This overrides /cetcompat if set on the executable. See:
182   // https://docs.microsoft.com/en-us/cpp/build/reference/cetcompat?view=msvc-160
183   // If not supported by Windows, has no effect. This flag weakens security by
184   // turning off ROP protection.
185   bool disable_cetcompat = false;
186 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
187   // Remap file descriptors according to the mapping of src_fd->dest_fd to
188   // propagate FDs into the child process.
189   FileHandleMappingVector fds_to_remap;
190 #endif  // BUILDFLAG(IS_WIN)
191 
192 #if BUILDFLAG(IS_WIN) || BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
193   // Set/unset environment variables. These are applied on top of the parent
194   // process environment.  Empty (the default) means to inherit the same
195   // environment. See internal::AlterEnvironment().
196   EnvironmentMap environment;
197 
198   // Clear the environment for the new process before processing changes from
199   // |environment|.
200   bool clear_environment = false;
201 #endif  // BUILDFLAG(IS_WIN) || BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
202 
203 #if BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)
204   // If non-zero, start the process using clone(), using flags as provided.
205   // Unlike in clone, clone_flags may not contain a custom termination signal
206   // that is sent to the parent when the child dies. The termination signal will
207   // always be set to SIGCHLD.
208   int clone_flags = 0;
209 
210   // By default, child processes will have the PR_SET_NO_NEW_PRIVS bit set. If
211   // true, then this bit will not be set in the new child process.
212   bool allow_new_privs = false;
213 
214   // Sets parent process death signal to SIGKILL.
215   bool kill_on_parent_death = false;
216 
217   // File descriptors of the parent process with FD_CLOEXEC flag to be removed
218   // before calling exec*().
219   std::vector<int> fds_to_remove_cloexec;
220 #endif  // BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)
221 
222 #if BUILDFLAG(IS_MAC) || (BUILDFLAG(IS_IOS) && BUILDFLAG(USE_BLINK))
223   // Mach ports that will be accessible to the child process. These are not
224   // directly inherited across process creation, but they are stored by a Mach
225   // IPC server that a child process can communicate with to retrieve them.
226   //
227   // After calling LaunchProcess(), any rights that were transferred with MOVE
228   // dispositions will be consumed, even on failure.
229   //
230   // See base/mac/mach_port_rendezvous.h for details.
231   MachPortsForRendezvous mach_ports_for_rendezvous;
232 
233   // Apply a process scheduler policy to enable mitigations against CPU side-
234   // channel attacks.
235   bool enable_cpu_security_mitigations = false;
236 #endif  // BUILDFLAG(IS_MAC) || (BUILDFLAG(IS_IOS) && BUILDFLAG(USE_BLINK))
237 
238 #if BUILDFLAG(IS_MAC)
239   // When a child process is launched, the system tracks the parent process
240   // with a concept of "responsibility". The responsible process will be
241   // associated with any requests for private data stored on the system via
242   // the TCC subsystem. When launching processes that run foreign/third-party
243   // code, the responsibility for the child process should be disclaimed so
244   // that any TCC requests are not associated with the parent.
245   bool disclaim_responsibility = false;
246 #endif  // BUILDFLAG(IS_MAC) || (BUILDFLAG(IS_IOS) && BUILDFLAG(USE_BLINK))
247 
248 #if BUILDFLAG(IS_FUCHSIA)
249   // If valid, launches the application in that job object.
250   zx_handle_t job_handle = ZX_HANDLE_INVALID;
251 
252   // Specifies additional handles to transfer (not duplicate) to the child
253   // process. Each entry is an <id,handle> pair, with an |id| created using the
254   // PA_HND() macro. The child retrieves the handle
255   // |zx_take_startup_handle(id)|. The supplied handles are consumed by
256   // LaunchProcess() even on failure.
257   // Note that PA_USER1 ids are reserved for use by AddHandleToTransfer(), below
258   // and by convention PA_USER0 is reserved for use by the embedding
259   // application.
260   HandlesToTransferVector handles_to_transfer;
261 
262   // Allocates a unique id for |handle| in |handles_to_transfer|, inserts it,
263   // and returns the generated id.
264   static uint32_t AddHandleToTransfer(
265       HandlesToTransferVector* handles_to_transfer,
266       zx_handle_t handle);
267 
268   // Specifies which basic capabilities to grant to the child process.
269   // By default the child process will receive the caller's complete namespace,
270   // access to the current base::GetDefaultJob(), handles for stdio and access
271   // to the dynamic library loader.
272   // Note that the child is always provided access to the loader service.
273   uint32_t spawn_flags = FDIO_SPAWN_CLONE_NAMESPACE | FDIO_SPAWN_CLONE_STDIO |
274                          FDIO_SPAWN_CLONE_JOB;
275 
276   // Specifies paths to clone from the calling process' namespace into that of
277   // the child process. If |paths_to_clone| is empty then the process will
278   // receive either a full copy of the parent's namespace, or an empty one,
279   // depending on whether FDIO_SPAWN_CLONE_NAMESPACE is set.
280   // Process launch will fail if `paths_to_clone` and `paths_to_transfer`
281   // together contain conflicting paths (e.g. overlaps or duplicates).
282   std::vector<FilePath> paths_to_clone;
283 
284   // Specifies handles which will be installed as files or directories in the
285   // child process' namespace.
286   // Process launch will fail if `paths_to_clone` and `paths_to_transfer`
287   // together contain conflicting paths (e.g. overlaps or duplicates).
288   std::vector<PathToTransfer> paths_to_transfer;
289 
290   // Suffix that will be added to the process name. When specified process name
291   // will be set to "<binary_name><process_suffix>".
292   std::string process_name_suffix;
293 #endif  // BUILDFLAG(IS_FUCHSIA)
294 
295 #if BUILDFLAG(IS_POSIX)
296   // If not empty, launch the specified executable instead of
297   // cmdline.GetProgram(). This is useful when it is necessary to pass a custom
298   // argv[0].
299   base::FilePath real_path;
300 
301 #if !BUILDFLAG(IS_APPLE)
302   // If non-null, a delegate to be run immediately prior to executing the new
303   // program in the child process.
304   //
305   // WARNING: If LaunchProcess is called in the presence of multiple threads,
306   // code running in this delegate essentially needs to be async-signal safe
307   // (see man 7 signal for a list of allowed functions).
308   raw_ptr<PreExecDelegate> pre_exec_delegate = nullptr;
309 #endif  // !BUILDFLAG(IS_APPLE)
310 
311   // Each element is an RLIMIT_* constant that should be raised to its
312   // rlim_max.  This pointer is owned by the caller and must live through
313   // the call to LaunchProcess().
314   raw_ptr<const std::vector<int>> maximize_rlimits = nullptr;
315 
316   // If true, start the process in a new process group, instead of
317   // inheriting the parent's process group.  The pgid of the child process
318   // will be the same as its pid.
319   bool new_process_group = false;
320 #endif  // BUILDFLAG(IS_POSIX)
321 
322 #if BUILDFLAG(IS_CHROMEOS)
323   // If non-negative, the specified file descriptor will be set as the launched
324   // process' controlling terminal.
325   int ctrl_terminal_fd = -1;
326 #endif  // BUILDFLAG(IS_CHROMEOS)
327 };
328 
329 // Launch a process via the command line |cmdline|.
330 // See the documentation of LaunchOptions for details on |options|.
331 //
332 // Returns a valid Process upon success.
333 //
334 // Unix-specific notes:
335 // - All file descriptors open in the parent process will be closed in the
336 //   child process except for any preserved by options::fds_to_remap, and
337 //   stdin, stdout, and stderr. If not remapped by options::fds_to_remap,
338 //   stdin is reopened as /dev/null, and the child is allowed to inherit its
339 //   parent's stdout and stderr.
340 // - If the first argument on the command line does not contain a slash,
341 //   PATH will be searched.  (See man execvp.)
342 BASE_EXPORT Process LaunchProcess(const CommandLine& cmdline,
343                                   const LaunchOptions& options);
344 
345 #if BUILDFLAG(IS_WIN)
346 // Windows-specific LaunchProcess that takes the command line as a
347 // string.  Useful for situations where you need to control the
348 // command line arguments directly, but prefer the CommandLine version
349 // if launching Chrome itself. Also prefer the CommandLine version if
350 // `options.elevated` is set because `cmdline` needs to be parsed for
351 // ShellExecuteEx.
352 //
353 // The first command line argument should be the path to the process,
354 // and don't forget to quote it.
355 //
356 // Example (including literal quotes)
357 //  cmdline = "c:\windows\explorer.exe" -foo "c:\bar\"
358 BASE_EXPORT Process LaunchProcess(const CommandLine::StringType& cmdline,
359                                   const LaunchOptions& options);
360 
361 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
362 // A POSIX-specific version of LaunchProcess that takes an argv array
363 // instead of a CommandLine.  Useful for situations where you need to
364 // control the command line arguments directly, but prefer the
365 // CommandLine version if launching Chrome itself.
366 BASE_EXPORT Process LaunchProcess(const std::vector<std::string>& argv,
367                                   const LaunchOptions& options);
368 
369 #if !BUILDFLAG(IS_APPLE)
370 // Close all file descriptors, except those which are a destination in the
371 // given multimap. Only call this function in a child process where you know
372 // that there aren't any other threads.
373 BASE_EXPORT void CloseSuperfluousFds(const InjectiveMultimap& saved_map);
374 #endif  // BUILDFLAG(IS_APPLE)
375 #endif  // BUILDFLAG(IS_WIN)
376 
377 #if BUILDFLAG(IS_WIN)
378 // Set |job_object|'s JOBOBJECT_EXTENDED_LIMIT_INFORMATION
379 // BasicLimitInformation.LimitFlags to |limit_flags|.
380 BASE_EXPORT bool SetJobObjectLimitFlags(HANDLE job_object, DWORD limit_flags);
381 
382 // Output multi-process printf, cout, cerr, etc to the cmd.exe console that ran
383 // chrome. This is not thread-safe: only call from main thread.
384 BASE_EXPORT void RouteStdioToConsole(bool create_console_if_not_found);
385 #endif  // BUILDFLAG(IS_WIN)
386 
387 // Executes the application specified by |cl| and wait for it to exit. Stores
388 // the output (stdout) in |output|. Redirects stderr to /dev/null. Returns true
389 // on success (application launched and exited cleanly, with exit code
390 // indicating success).
391 BASE_EXPORT bool GetAppOutput(const CommandLine& cl, std::string* output);
392 
393 // Like GetAppOutput, but also includes stderr.
394 BASE_EXPORT bool GetAppOutputAndError(const CommandLine& cl,
395                                       std::string* output);
396 
397 // A version of |GetAppOutput()| which also returns the exit code of the
398 // executed command. Returns true if the application runs and exits cleanly. If
399 // this is the case the exit code of the application is available in
400 // |*exit_code|.
401 BASE_EXPORT bool GetAppOutputWithExitCode(const CommandLine& cl,
402                                           std::string* output, int* exit_code);
403 
404 #if BUILDFLAG(IS_WIN)
405 // A Windows-specific version of GetAppOutput that takes a command line string
406 // instead of a CommandLine object. Useful for situations where you need to
407 // control the command line arguments directly.
408 BASE_EXPORT bool GetAppOutput(CommandLine::StringPieceType cl,
409                               std::string* output);
410 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
411 // A POSIX-specific version of GetAppOutput that takes an argv array
412 // instead of a CommandLine.  Useful for situations where you need to
413 // control the command line arguments directly.
414 BASE_EXPORT bool GetAppOutput(const std::vector<std::string>& argv,
415                               std::string* output);
416 
417 // Like the above POSIX-specific version of GetAppOutput, but also includes
418 // stderr.
419 BASE_EXPORT bool GetAppOutputAndError(const std::vector<std::string>& argv,
420                                       std::string* output);
421 #endif  // BUILDFLAG(IS_WIN)
422 
423 // If supported on the platform, and the user has sufficent rights, increase
424 // the current process's scheduling priority to a high priority.
425 BASE_EXPORT void RaiseProcessToHighPriority();
426 
427 // Creates a LaunchOptions object suitable for launching processes in a test
428 // binary. This should not be called in production/released code.
429 BASE_EXPORT LaunchOptions LaunchOptionsForTest();
430 
431 #if BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)
432 // A wrapper for clone with fork-like behavior, meaning that it returns the
433 // child's pid in the parent and 0 in the child. |flags|, |ptid|, and |ctid| are
434 // as in the clone system call (the CLONE_VM flag is not supported).
435 //
436 // This function uses the libc clone wrapper (which updates libc's pid cache)
437 // internally, so callers may expect things like getpid() to work correctly
438 // after in both the child and parent.
439 //
440 // As with fork(), callers should be extremely careful when calling this while
441 // multiple threads are running, since at the time the fork happened, the
442 // threads could have been in any state (potentially holding locks, etc.).
443 // Callers should most likely call execve() in the child soon after calling
444 // this.
445 //
446 // It is unsafe to use any pthread APIs after ForkWithFlags().
447 // However, performing an exec() will lift this restriction.
448 BASE_EXPORT pid_t ForkWithFlags(int flags, pid_t* ptid, pid_t* ctid);
449 #endif
450 
451 namespace internal {
452 
453 // Friend and derived class of ScopedAllowBaseSyncPrimitives which allows
454 // GetAppOutputInternal() to join a process. GetAppOutputInternal() can't itself
455 // be a friend of ScopedAllowBaseSyncPrimitives because it is in the anonymous
456 // namespace.
457 class [[maybe_unused, nodiscard]] GetAppOutputScopedAllowBaseSyncPrimitives
458     : public base::ScopedAllowBaseSyncPrimitives{};
459 
460 }  // namespace internal
461 
462 }  // namespace base
463 
464 #endif  // BASE_PROCESS_LAUNCH_H_
465