Add the generate_dump tool.

R=rsesek@chromium.org

Review URL: https://codereview.chromium.org/727983002

tools/generate_dump.ad

@@ -0,0 +1,95 @@
+// Copyright 2014 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+:doctype: manpage
+
+= generate_dump(1)
+
+== Name
+
+generate_dump - Generate a minidump file containing a snapshot of a running
+process
+
+== Synopsis
+
+[verse]
+*generate_dump* ['OPTION…'] 'PID'
+
+== Description
+
+Generates a minidump file containing a snapshot of a running process whose
+process identifier is 'PID'. By default, the target process will be suspended
+while the minidump is generated, and the minidump file will be written to
++minidump.PID+. After the minidump file is generated, the target process resumes
+running.
+
+The minidump file will contain information about the process, its threads, its
+modules, and the system. It will not contain any exception information because
+it will be generated from a live running process, not as a result of an
+exception occurring.
+
+This program uses +task_for_pid()+ to access the process’ task port. This
+operation may be restricted to use by the superuser or processes permitted by
+taskgated(8). Consequently, this program must normally be invoked by root. It is
+possible to install this program as a setuid root executable to overcome this
+limitation.
+
+This program is similar to the gcore(1) program available on some operating
+systems.
+
+== Options
+
+*-r*, *--no_suspend*::
+The target process will continue running while the minidump file is generated.
+Normally, the target process is suspended during this operation, which
+guarantees that the minidump file will contain an atomic snapshot of the
+process.
++
+This option may be useful when attempting to generate a minidump from a process
+that dump generation has an interprocess dependency on, such as a system server
+like launchd(8) or opendirectoryd(8). Deadlock could occur if any portion of the
+dump generation operation blocks while waiting for a response from one of these
+servers while they are suspended.
+
+*-o*, *--output*='FILE'::
+The minidump will be written to 'FILE' instead of +minidump.PID+.
+
+*--help*::
+Display help and exit.
+
+*--version*::
+Output version information and exit.
+
+== Examples
+
+Generate a minidump file in +/tmp/minidump+ containing a snapshot of the process
+with PID 1234.
+[subs="quotes"]
+----
+$ *generate_dump --output=/tmp/minidump 1234*
+----
+
+== Exit Status
+
+*0*::
+Success.
+
+*1*::
+Failure, with a message printed to the standard error stream.
+
+== See Also
+
+catch_exception_tool(1)
+
+include::man_footer.ad[]

tools/generate_dump.cc

@@ -0,0 +1,178 @@
+// Copyright 2014 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <fcntl.h>
+#include <getopt.h>
+#include <libgen.h>
+#include <mach/mach.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#include <string>
+
+#include "base/logging.h"
+#include "base/mac/scoped_mach_port.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/strings/stringprintf.h"
+#include "minidump/minidump_file_writer.h"
+#include "snapshot/mac/process_snapshot_mac.h"
+#include "tools/tool_support.h"
+#include "util/file/file_writer.h"
+#include "util/mach/scoped_task_suspend.h"
+#include "util/mach/task_for_pid.h"
+#include "util/posix/drop_privileges.h"
+#include "util/stdlib/string_number_conversion.h"
+
+namespace crashpad {
+namespace {
+
+struct Options {
+  std::string dump_path;
+  pid_t pid;
+  bool suspend;
+};
+
+void Usage(const std::string& me) {
+  fprintf(stderr,
+"Usage: %s [OPTION]... PID\n"
+"Generate a minidump file containing a snapshot of a running process.\n"
+"\n"
+"  -r, --no_suspend   don't suspend the target process during dump generation\n"
+"  -o, --output=FILE  write the minidump to FILE instead of minidump.PID\n"
+"      --help         display this help and exit\n"
+"      --version      output version information and exit\n",
+          me.c_str());
+  ToolSupport::UsageTail(me);
+}
+
+int GenerateDumpMain(int argc, char* argv[]) {
+  const std::string me(basename(argv[0]));
+
+  enum OptionFlags {
+    // “Short” (single-character) options.
+    kOptionOutput = 'o',
+    kOptionNoSuspend = 'r',
+
+    // Long options without short equivalents.
+    kOptionLastChar = 255,
+
+    // Standard options.
+    kOptionHelp = -2,
+    kOptionVersion = -3,
+  };
+
+  Options options = {};
+  options.suspend = true;
+
+  const struct option long_options[] = {
+      {"no_suspend", no_argument, nullptr, kOptionNoSuspend},
+      {"output", required_argument, nullptr, kOptionOutput},
+      {"help", no_argument, nullptr, kOptionHelp},
+      {"version", no_argument, nullptr, kOptionVersion},
+      {nullptr, 0, nullptr, 0},
+  };
+
+  int opt;
+  while ((opt = getopt_long(argc, argv, "o:r", long_options, nullptr)) != -1) {
+    switch (opt) {
+      case kOptionOutput:
+        options.dump_path = optarg;
+        break;
+      case kOptionNoSuspend:
+        options.suspend = false;
+        break;
+      case kOptionHelp:
+        Usage(me);
+        return EXIT_SUCCESS;
+      case kOptionVersion:
+        ToolSupport::Version(me);
+        return EXIT_SUCCESS;
+      default:
+        ToolSupport::UsageHint(me, nullptr);
+        return EXIT_FAILURE;
+    }
+  }
+  argc -= optind;
+  argv += optind;
+
+  if (argc != 1) {
+    ToolSupport::UsageHint(me, "PID is required");
+    return EXIT_FAILURE;
+  }
+
+  if (!StringToNumber(argv[0], &options.pid) || options.pid <= 0) {
+    fprintf(stderr, "%s: invalid PID: %s\n", me.c_str(), argv[0]);
+    return EXIT_FAILURE;
+  }
+
+  task_t task = TaskForPID(options.pid);
+  if (task == TASK_NULL) {
+    return EXIT_FAILURE;
+  }
+  base::mac::ScopedMachSendRight task_owner(task);
+
+  // This tool may have been installed as a setuid binary so that TaskForPID()
+  // could succeed. Drop any privileges now that they’re no longer necessary.
+  DropPrivileges();
+
+  if (options.pid == getpid()) {
+    if (options.suspend) {
+      LOG(ERROR) << "cannot suspend myself";
+      return EXIT_FAILURE;
+    }
+    LOG(WARNING) << "operating on myself";
+  }
+
+  if (options.dump_path.empty()) {
+    options.dump_path = base::StringPrintf("minidump.%d", options.pid);
+  }
+
+  {
+    scoped_ptr<ScopedTaskSuspend> suspend;
+    if (options.suspend) {
+      suspend.reset(new ScopedTaskSuspend(task));
+    }
+
+    ProcessSnapshotMac process_snapshot;
+    if (!process_snapshot.Initialize(task)) {
+      return EXIT_FAILURE;
+    }
+
+    FileWriter file_writer;
+    if (!file_writer.Open(base::FilePath(options.dump_path),
+                          O_WRONLY | O_CREAT | O_TRUNC,
+                          0644)) {
+      return EXIT_FAILURE;
+    }
+
+    MinidumpFileWriter minidump;
+    minidump.InitializeFromSnapshot(&process_snapshot);
+    if (!minidump.WriteEverything(&file_writer)) {
+      if (unlink(options.dump_path.c_str()) != 0) {
+        PLOG(ERROR) << "unlink";
+      }
+      return EXIT_FAILURE;
+    }
+  }
+
+  return EXIT_SUCCESS;
+}
+
+}  // namespace
+}  // namespace crashpad
+
+int main(int argc, char* argv[]) {
+  return crashpad::GenerateDumpMain(argc, argv);
+}

tools/tools.gyp

@@ -62,6 +62,24 @@
             'exception_port_tool.cc',
           ],
         },
+        {
+          'target_name': 'generate_dump',
+          'type': 'executable',
+          'dependencies': [
+            'tool_support',
+            '../compat/compat.gyp:compat',
+            '../minidump/minidump.gyp:minidump',
+            '../snapshot/snapshot.gyp:snapshot',
+            '../third_party/mini_chromium/mini_chromium/base/base.gyp:base',
+            '../util/util.gyp:util',
+          ],
+          'include_dirs': [
+            '..',
+          ],
+          'sources': [
+            'generate_dump.cc',
+          ],
+        },
         {
           'target_name': 'on_demand_service_tool',
           'type': 'executable',