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
3// found in the LICENSE file.
5// This file contains functions for launching subprocesses.
10#include <string>
11#include <utility>
12#include <vector>
14#include "base/base_export.h"
15#include "base/basictypes.h"
16#include "base/environment.h"
17#include "base/process/process_handle.h"
18#include "base/strings/string_piece.h"
20#if defined(OS_POSIX)
21#include "base/posix/file_descriptor_shuffle.h"
22#elif defined(OS_WIN)
23#include <windows.h>
24#include "base/win/scoped_handle.h"
27namespace base {
29class CommandLine;
31#if defined(OS_WIN)
32typedef std::vector<HANDLE> HandlesToInheritVector;
34// TODO(viettrungluu): Only define this on POSIX?
35typedef std::vector<std::pair<int, int> > FileHandleMappingVector;
37// Options for launching a subprocess that are passed to LaunchProcess().
38// The default constructor constructs the object with default options.
39struct BASE_EXPORT LaunchOptions {
40  LaunchOptions();
41  ~LaunchOptions();
43  // If true, wait for the process to complete.
44  bool wait;
46#if defined(OS_WIN)
47  bool start_hidden;
49  // If non-null, inherit exactly the list of handles in this vector (these
50  // handles must be inheritable). This is only supported on Vista and higher.
51  HandlesToInheritVector* handles_to_inherit;
53  // If true, the new process inherits handles from the parent. In production
54  // code this flag should be used only when running short-lived, trusted
55  // binaries, because open handles from other libraries and subsystems will
56  // leak to the child process, causing errors such as open socket hangs.
57  // Note: If |handles_to_inherit| is non-null, this flag is ignored and only
58  // those handles will be inherited (on Vista and higher).
59  bool inherit_handles;
61  // If non-null, runs as if the user represented by the token had launched it.
62  // Whether the application is visible on the interactive desktop depends on
63  // the token belonging to an interactive logon session.
64  //
65  // To avoid hard to diagnose problems, when specified this loads the
66  // environment variables associated with the user and if this operation fails
67  // the entire call fails as well.
68  UserTokenHandle as_user;
70  // If true, use an empty string for the desktop name.
71  bool empty_desktop_name;
73  // If non-null, launches the application in that job object. The process will
74  // be terminated immediately and LaunchProcess() will fail if assignment to
75  // the job object fails.
76  HANDLE job_handle;
78  // Handles for the redirection of stdin, stdout and stderr. The handles must
79  // be inheritable. Caller should either set all three of them or none (i.e.
80  // there is no way to redirect stderr without redirecting stdin). The
81  // |inherit_handles| flag must be set to true when redirecting stdio stream.
82  HANDLE stdin_handle;
83  HANDLE stdout_handle;
84  HANDLE stderr_handle;
86  // If set to true, ensures that the child process is launched with the
87  // CREATE_BREAKAWAY_FROM_JOB flag which allows it to breakout of the parent
88  // job if any.
89  bool force_breakaway_from_job_;
91  // Set/unset environment variables. These are applied on top of the parent
92  // process environment.  Empty (the default) means to inherit the same
93  // environment. See AlterEnvironment().
94  EnvironmentMap environ;
96  // Clear the environment for the new process before processing changes from
97  // |environ|.
98  bool clear_environ;
100  // If non-null, remap file descriptors according to the mapping of
101  // src fd->dest fd to propagate FDs into the child process.
102  // This pointer is owned by the caller and must live through the
103  // call to LaunchProcess().
104  const FileHandleMappingVector* fds_to_remap;
106  // Each element is an RLIMIT_* constant that should be raised to its
107  // rlim_max.  This pointer is owned by the caller and must live through
108  // the call to LaunchProcess().
109  const std::vector<int>* maximize_rlimits;
111  // If true, start the process in a new process group, instead of
112  // inheriting the parent's process group.  The pgid of the child process
113  // will be the same as its pid.
114  bool new_process_group;
116#if defined(OS_LINUX)
117  // If non-zero, start the process using clone(), using flags as provided.
118  int clone_flags;
120  // By default, child processes will have the PR_SET_NO_NEW_PRIVS bit set. If
121  // true, then this bit will not be set in the new child process.
122  bool allow_new_privs;
123#endif  // defined(OS_LINUX)
125#if defined(OS_CHROMEOS)
126  // If non-negative, the specified file descriptor will be set as the launched
127  // process' controlling terminal.
128  int ctrl_terminal_fd;
129#endif  // defined(OS_CHROMEOS)
131#if defined(OS_MACOSX)
132  // If this name is non-empty, the new child, after fork() but before exec(),
133  // will look up this server name in the bootstrap namespace. The resulting
134  // service port will be replaced as the bootstrap port in the child. Because
135  // the process's IPC space is cleared on exec(), any rights to the old
136  // bootstrap port will not be transferred to the new process.
137  std::string replacement_bootstrap_name;
140#endif  // !defined(OS_WIN)
143// Launch a process via the command line |cmdline|.
144// See the documentation of LaunchOptions for details on |options|.
146// Returns true upon success.
148// Upon success, if |process_handle| is non-null, it will be filled in with the
149// handle of the launched process.  NOTE: In this case, the caller is
150// responsible for closing the handle so that it doesn't leak!
151// Otherwise, the process handle will be implicitly closed.
153// Unix-specific notes:
154// - All file descriptors open in the parent process will be closed in the
155//   child process except for any preserved by options::fds_to_remap, and
156//   stdin, stdout, and stderr. If not remapped by options::fds_to_remap,
157//   stdin is reopened as /dev/null, and the child is allowed to inherit its
158//   parent's stdout and stderr.
159// - If the first argument on the command line does not contain a slash,
160//   PATH will be searched.  (See man execvp.)
161BASE_EXPORT bool LaunchProcess(const CommandLine& cmdline,
162                               const LaunchOptions& options,
163                               ProcessHandle* process_handle);
165#if defined(OS_WIN)
166// Windows-specific LaunchProcess that takes the command line as a
167// string.  Useful for situations where you need to control the
168// command line arguments directly, but prefer the CommandLine version
169// if launching Chrome itself.
171// The first command line argument should be the path to the process,
172// and don't forget to quote it.
174// Example (including literal quotes)
175//  cmdline = "c:\windows\explorer.exe" -foo "c:\bar\"
176BASE_EXPORT bool LaunchProcess(const string16& cmdline,
177                               const LaunchOptions& options,
178                               win::ScopedHandle* process_handle);
180// Launches a process with elevated privileges.  This does not behave exactly
181// like LaunchProcess as it uses ShellExecuteEx instead of CreateProcess to
182// create the process.  This means the process will have elevated privileges
183// and thus some common operations like OpenProcess will fail. The process will
184// be available through the |process_handle| argument.  Currently the only
185// supported LaunchOptions are |start_hidden| and |wait|.
186BASE_EXPORT bool LaunchElevatedProcess(const CommandLine& cmdline,
187                                       const LaunchOptions& options,
188                                       ProcessHandle* process_handle);
190#elif defined(OS_POSIX)
191// A POSIX-specific version of LaunchProcess that takes an argv array
192// instead of a CommandLine.  Useful for situations where you need to
193// control the command line arguments directly, but prefer the
194// CommandLine version if launching Chrome itself.
195BASE_EXPORT bool LaunchProcess(const std::vector<std::string>& argv,
196                               const LaunchOptions& options,
197                               ProcessHandle* process_handle);
199// Close all file descriptors, except those which are a destination in the
200// given multimap. Only call this function in a child process where you know
201// that there aren't any other threads.
202BASE_EXPORT void CloseSuperfluousFds(const InjectiveMultimap& saved_map);
203#endif  // defined(OS_POSIX)
205#if defined(OS_WIN)
207// BasicLimitInformation.LimitFlags to |limit_flags|.
208BASE_EXPORT bool SetJobObjectLimitFlags(HANDLE job_object, DWORD limit_flags);
210// Output multi-process printf, cout, cerr, etc to the cmd.exe console that ran
211// chrome. This is not thread-safe: only call from main thread.
212BASE_EXPORT void RouteStdioToConsole();
213#endif  // defined(OS_WIN)
215// Executes the application specified by |cl| and wait for it to exit. Stores
216// the output (stdout) in |output|. Redirects stderr to /dev/null. Returns true
217// on success (application launched and exited cleanly, with exit code
218// indicating success).
219BASE_EXPORT bool GetAppOutput(const CommandLine& cl, std::string* output);
221#if defined(OS_WIN)
222// A Windows-specific version of GetAppOutput that takes a command line string
223// instead of a CommandLine object. Useful for situations where you need to
224// control the command line arguments directly.
225BASE_EXPORT bool GetAppOutput(const StringPiece16& cl, std::string* output);
228#if defined(OS_POSIX)
229// A POSIX-specific version of GetAppOutput that takes an argv array
230// instead of a CommandLine.  Useful for situations where you need to
231// control the command line arguments directly.
232BASE_EXPORT bool GetAppOutput(const std::vector<std::string>& argv,
233                              std::string* output);
235// A restricted version of |GetAppOutput()| which (a) clears the environment,
236// and (b) stores at most |max_output| bytes; also, it doesn't search the path
237// for the command.
238BASE_EXPORT bool GetAppOutputRestricted(const CommandLine& cl,
239                                        std::string* output, size_t max_output);
241// A version of |GetAppOutput()| which also returns the exit code of the
242// executed command. Returns true if the application runs and exits cleanly. If
243// this is the case the exit code of the application is available in
244// |*exit_code|.
245BASE_EXPORT bool GetAppOutputWithExitCode(const CommandLine& cl,
246                                          std::string* output, int* exit_code);
247#endif  // defined(OS_POSIX)
249// If supported on the platform, and the user has sufficent rights, increase
250// the current process's scheduling priority to a high priority.
251BASE_EXPORT void RaiseProcessToHighPriority();
253#if defined(OS_MACOSX)
254// Restore the default exception handler, setting it to Apple Crash Reporter
255// (ReportCrash).  When forking and execing a new process, the child will
256// inherit the parent's exception ports, which may be set to the Breakpad
257// instance running inside the parent.  The parent's Breakpad instance should
258// not handle the child's exceptions.  Calling RestoreDefaultExceptionHandler
259// in the child after forking will restore the standard exception handler.
260// See http://crbug.com/20371/ for more details.
261void RestoreDefaultExceptionHandler();
263// Look up the bootstrap server named |replacement_bootstrap_name| via the
264// current |bootstrap_port|. Then replace the task's bootstrap port with the
265// received right.
266void ReplaceBootstrapPort(const std::string& replacement_bootstrap_name);
267#endif  // defined(OS_MACOSX)
269// Creates a LaunchOptions object suitable for launching processes in a test
270// binary. This should not be called in production/released code.
271BASE_EXPORT LaunchOptions LaunchOptionsForTest();
273}  // namespace base
275#endif  // BASE_PROCESS_LAUNCH_H_