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