base/process_util.h

   1 // Copyright (c) 2012 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 // This file/namespace contains utility functions for enumerating, ending and
   6 // computing statistics of processes.
   7
   8 #ifndef BASE_PROCESS_UTIL_H_
   9 #define BASE_PROCESS_UTIL_H_
  10
  11 #include "base/basictypes.h"
  12 #include "base/time/time.h"
  13
  14 #if defined(OS_WIN)
  15 #include <windows.h>
  16 #include <tlhelp32.h>
  17 #elif defined(OS_MACOSX) || defined(OS_BSD)
  18 // malloc_zone_t is defined in <malloc/malloc.h>, but this forward declaration
  19 // is sufficient for GetPurgeableZone() below.
  20 typedef struct _malloc_zone_t malloc_zone_t;
  21 #if !defined(OS_BSD)
  22 #include <mach/mach.h>
  23 #endif
  24 #elif defined(OS_POSIX)
  25 #include <dirent.h>
  26 #include <limits.h>
  27 #include <sys/types.h>
  28 #endif
  29
  30 #include <list>
  31 #include <set>
  32 #include <string>
  33 #include <utility>
  34 #include <vector>
  35
  36 #include "base/base_export.h"
  37 #include "base/files/file_path.h"
  38 #include "base/process.h"
  39 #include "base/process/memory.h"
  40 #include "base/process/kill.h"
  41 #include "base/process/process_handle.h"
  42 #include "base/process/process_iterator.h"
  43 #include "base/process/process_metrics.h"
  44
  45 #if defined(OS_POSIX)
  46 #include "base/posix/file_descriptor_shuffle.h"
  47 #endif
  48
  49 class CommandLine;
  50
  51 namespace base {
  52
  53 #if defined(OS_WIN)
  54 // Output multi-process printf, cout, cerr, etc to the cmd.exe console that ran
  55 // chrome. This is not thread-safe: only call from main thread.
  56 BASE_EXPORT void RouteStdioToConsole();
  57 #endif
  58
  59 #if defined(OS_POSIX)
  60 // Close all file descriptors, except those which are a destination in the
  61 // given multimap. Only call this function in a child process where you know
  62 // that there aren't any other threads.
  63 BASE_EXPORT void CloseSuperfluousFds(const InjectiveMultimap& saved_map);
  64 #endif  // defined(OS_POSIX)
  65
  66 typedef std::vector<std::pair<std::string, std::string> > EnvironmentVector;
  67 typedef std::vector<std::pair<int, int> > FileHandleMappingVector;
  68
  69 // Options for launching a subprocess that are passed to LaunchProcess().
  70 // The default constructor constructs the object with default options.
  71 struct LaunchOptions {
  72   LaunchOptions()
  73       : wait(false),
  74 #if defined(OS_WIN)
  75         start_hidden(false),
  76         inherit_handles(false),
  77         as_user(NULL),
  78         empty_desktop_name(false),
  79         job_handle(NULL),
  80         stdin_handle(NULL),
  81         stdout_handle(NULL),
  82         stderr_handle(NULL),
  83         force_breakaway_from_job_(false)
  84 #else
  85         environ(NULL),
  86         fds_to_remap(NULL),
  87         maximize_rlimits(NULL),
  88         new_process_group(false)
  89 #if defined(OS_LINUX)
  90         , clone_flags(0)
  91 #endif  // OS_LINUX
  92 #if defined(OS_CHROMEOS)
  93         , ctrl_terminal_fd(-1)
  94 #endif  // OS_CHROMEOS
  95 #endif  // !defined(OS_WIN)
  96         {}
  97
  98   // If true, wait for the process to complete.
  99   bool wait;
 100
 101 #if defined(OS_WIN)
 102   bool start_hidden;
 103
 104   // If true, the new process inherits handles from the parent. In production
 105   // code this flag should be used only when running short-lived, trusted
 106   // binaries, because open handles from other libraries and subsystems will
 107   // leak to the child process, causing errors such as open socket hangs.
 108   bool inherit_handles;
 109
 110   // If non-NULL, runs as if the user represented by the token had launched it.
 111   // Whether the application is visible on the interactive desktop depends on
 112   // the token belonging to an interactive logon session.
 113   //
 114   // To avoid hard to diagnose problems, when specified this loads the
 115   // environment variables associated with the user and if this operation fails
 116   // the entire call fails as well.
 117   UserTokenHandle as_user;
 118
 119   // If true, use an empty string for the desktop name.
 120   bool empty_desktop_name;
 121
 122   // If non-NULL, launches the application in that job object. The process will
 123   // be terminated immediately and LaunchProcess() will fail if assignment to
 124   // the job object fails.
 125   HANDLE job_handle;
 126
 127   // Handles for the redirection of stdin, stdout and stderr. The handles must
 128   // be inheritable. Caller should either set all three of them or none (i.e.
 129   // there is no way to redirect stderr without redirecting stdin). The
 130   // |inherit_handles| flag must be set to true when redirecting stdio stream.
 131   HANDLE stdin_handle;
 132   HANDLE stdout_handle;
 133   HANDLE stderr_handle;
 134
 135   // If set to true, ensures that the child process is launched with the
 136   // CREATE_BREAKAWAY_FROM_JOB flag which allows it to breakout of the parent
 137   // job if any.
 138   bool force_breakaway_from_job_;
 139 #else
 140   // If non-NULL, set/unset environment variables.
 141   // See documentation of AlterEnvironment().
 142   // This pointer is owned by the caller and must live through the
 143   // call to LaunchProcess().
 144   const EnvironmentVector* environ;
 145
 146   // If non-NULL, remap file descriptors according to the mapping of
 147   // src fd->dest fd to propagate FDs into the child process.
 148   // This pointer is owned by the caller and must live through the
 149   // call to LaunchProcess().
 150   const FileHandleMappingVector* fds_to_remap;
 151
 152   // Each element is an RLIMIT_* constant that should be raised to its
 153   // rlim_max.  This pointer is owned by the caller and must live through
 154   // the call to LaunchProcess().
 155   const std::set<int>* maximize_rlimits;
 156
 157   // If true, start the process in a new process group, instead of
 158   // inheriting the parent's process group.  The pgid of the child process
 159   // will be the same as its pid.
 160   bool new_process_group;
 161
 162 #if defined(OS_LINUX)
 163   // If non-zero, start the process using clone(), using flags as provided.
 164   int clone_flags;
 165 #endif  // defined(OS_LINUX)
 166
 167 #if defined(OS_CHROMEOS)
 168   // If non-negative, the specified file descriptor will be set as the launched
 169   // process' controlling terminal.
 170   int ctrl_terminal_fd;
 171 #endif  // defined(OS_CHROMEOS)
 172
 173 #endif  // !defined(OS_WIN)
 174 };
 175
 176 // Launch a process via the command line |cmdline|.
 177 // See the documentation of LaunchOptions for details on |options|.
 178 //
 179 // Returns true upon success.
 180 //
 181 // Upon success, if |process_handle| is non-NULL, it will be filled in with the
 182 // handle of the launched process.  NOTE: In this case, the caller is
 183 // responsible for closing the handle so that it doesn't leak!
 184 // Otherwise, the process handle will be implicitly closed.
 185 //
 186 // Unix-specific notes:
 187 // - All file descriptors open in the parent process will be closed in the
 188 //   child process except for any preserved by options::fds_to_remap, and
 189 //   stdin, stdout, and stderr. If not remapped by options::fds_to_remap,
 190 //   stdin is reopened as /dev/null, and the child is allowed to inherit its
 191 //   parent's stdout and stderr.
 192 // - If the first argument on the command line does not contain a slash,
 193 //   PATH will be searched.  (See man execvp.)
 194 BASE_EXPORT bool LaunchProcess(const CommandLine& cmdline,
 195                                const LaunchOptions& options,
 196                                ProcessHandle* process_handle);
 197
 198 #if defined(OS_WIN)
 199 // Windows-specific LaunchProcess that takes the command line as a
 200 // string.  Useful for situations where you need to control the
 201 // command line arguments directly, but prefer the CommandLine version
 202 // if launching Chrome itself.
 203 //
 204 // The first command line argument should be the path to the process,
 205 // and don't forget to quote it.
 206 //
 207 // Example (including literal quotes)
 208 //  cmdline = "c:\windows\explorer.exe" -foo "c:\bar\"
 209 BASE_EXPORT bool LaunchProcess(const string16& cmdline,
 210                                const LaunchOptions& options,
 211                                ProcessHandle* process_handle);
 212
 213 #elif defined(OS_POSIX)
 214 // A POSIX-specific version of LaunchProcess that takes an argv array
 215 // instead of a CommandLine.  Useful for situations where you need to
 216 // control the command line arguments directly, but prefer the
 217 // CommandLine version if launching Chrome itself.
 218 BASE_EXPORT bool LaunchProcess(const std::vector<std::string>& argv,
 219                                const LaunchOptions& options,
 220                                ProcessHandle* process_handle);
 221
 222 // AlterEnvironment returns a modified environment vector, constructed from the
 223 // given environment and the list of changes given in |changes|. Each key in
 224 // the environment is matched against the first element of the pairs. In the
 225 // event of a match, the value is replaced by the second of the pair, unless
 226 // the second is empty, in which case the key-value is removed.
 227 //
 228 // The returned array is allocated using new[] and must be freed by the caller.
 229 BASE_EXPORT char** AlterEnvironment(const EnvironmentVector& changes,
 230                                     const char* const* const env);
 231 #endif  // defined(OS_POSIX)
 232
 233 #if defined(OS_WIN)
 234 // Set JOBOBJECT_EXTENDED_LIMIT_INFORMATION to JobObject |job_object|.
 235 // As its limit_info.BasicLimitInformation.LimitFlags has
 236 // JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE.
 237 // When the provide JobObject |job_object| is closed, the binded process will
 238 // be terminated.
 239 BASE_EXPORT bool SetJobObjectAsKillOnJobClose(HANDLE job_object);
 240 #endif  // defined(OS_WIN)
 241
 242 // 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
 244 // on success (application launched and exited cleanly, with exit code
 245 // indicating success).
 246 BASE_EXPORT bool GetAppOutput(const CommandLine& cl, std::string* output);
 247
 248 #if defined(OS_POSIX)
 249 // A POSIX-specific version of GetAppOutput that takes an argv array
 250 // instead of a CommandLine.  Useful for situations where you need to
 251 // control the command line arguments directly.
 252 BASE_EXPORT bool GetAppOutput(const std::vector<std::string>& argv,
 253                               std::string* output);
 254
 255 // A restricted version of |GetAppOutput()| which (a) clears the environment,
 256 // and (b) stores at most |max_output| bytes; also, it doesn't search the path
 257 // for the command.
 258 BASE_EXPORT bool GetAppOutputRestricted(const CommandLine& cl,
 259                                         std::string* output, size_t max_output);
 260
 261 // A version of |GetAppOutput()| which also returns the exit code of the
 262 // executed command. Returns true if the application runs and exits cleanly. If
 263 // this is the case the exit code of the application is available in
 264 // |*exit_code|.
 265 BASE_EXPORT bool GetAppOutputWithExitCode(const CommandLine& cl,
 266                                           std::string* output, int* exit_code);
 267 #endif  // defined(OS_POSIX)
 268
 269 // If supported on the platform, and the user has sufficent rights, increase
 270 // the current process's scheduling priority to a high priority.
 271 BASE_EXPORT void RaiseProcessToHighPriority();
 272
 273 #if defined(OS_MACOSX)
 274 // Restore the default exception handler, setting it to Apple Crash Reporter
 275 // (ReportCrash).  When forking and execing a new process, the child will
 276 // inherit the parent's exception ports, which may be set to the Breakpad
 277 // instance running inside the parent.  The parent's Breakpad instance should
 278 // not handle the child's exceptions.  Calling RestoreDefaultExceptionHandler
 279 // in the child after forking will restore the standard exception handler.
 280 // See http://crbug.com/20371/ for more details.
 281 void RestoreDefaultExceptionHandler();
 282 #endif  // defined(OS_MACOSX)
 283
 284 }  // namespace base
 285
 286 #endif  // BASE_PROCESS_UTIL_H_