mac: Add a mode to crashpad_handler to run from launchd

handler/crashpad_handler.ad

 // 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,
@@ skipping 15 matching lines @@
 *crashpad_handler* ['OPTION…']
 
 == Description
 
 This program is Crashpad’s main exception-handling server. It is responsible for
 catching exceptions, writing crash reports, and uploading them to a crash report
 collection server. Uploads are disabled by default, and can only be enabled by a
 Crashpad client using the Crashpad client library, typically in response to a
 user requesting this behavior.
 
-On OS X, this server is normally started by its initial client, and it performs
-a handshake with this client via a pipe established by the client that is
-inherited by the server, referenced by the *--handshake-fd* argument. During the
-handshake, the server furnishes the client with a send right that the client may
-use as an exception port. The server retains the corresponding receive right,
-which it monitors for exception messages. When the receive right loses all
-senders, the server exits after allowing any upload in progress to complete.
+On OS X, this server may be started by its initial client, in which case it
+performs a handshake with this client via a pipe established by the client that
+is inherited by the server, referenced by the *--handshake-fd* argument. During
+the handshake, the server furnishes the client with a send right that the client
+may use as an exception port. The server retains the corresponding receive
+right, which it monitors for exception messages. When the receive right loses
+all senders, the server exits after allowing any upload in progress to complete.
+
+Alternatively, on OS X, this server may be started from launchd(8), where it
+receives the Mach service name in a *--mach-service* argument. It checks in with
+the bootstrap server under this service name, and clients may look it up with
+the bootstrap server under this service name. It monitors this service for
+exception messages. Upon receipt of +SIGTERM+, the server exits after allowing
+any upload in progress to complete. +SIGTERM+ is normally sent by launchd(8)
+when it determines that the server should exit.
 
 On Windows, clients register with this server by communicating with it via the
 named pipe identified by the *--pipe-name* argument. During registration, a
 client provides the server with an OS event object that it will signal should it
 crash. The server obtains the client’s process handle and waits on the crash
 event object for a crash, as well as the client’s process handle for the client
 to exit cleanly without crashing. When the server loses all clients and
 *--persistent* is not specified, it exits after allowing any upload in progress
 to complete.
 
 It is not normally appropriate to invoke this program directly. Usually, it will
-be invoked by a Crashpad client using the Crashpad client library. Arbitrary
-programs may be run with a Crashpad handler by using
-man_link:run_with_crashpad[1] to establish the Crashpad client environment
-before running a program.
+be invoked by a Crashpad client using the Crashpad client library, or started by
+another system service. On OS X, arbitrary programs may be run with a Crashpad
+handler by using man_link:run_with_crashpad[1] to establish the Crashpad client
+environment before running a program.
 
 == Options
 *--annotation*='KEY=VALUE'::
 Sets a process-level annotation mapping 'KEY' to 'VALUE' in each crash report
 that is written. This option may appear zero, one, or multiple times.
 +
 Most annotations should be provided by the Crashpad client as module-level
 annotations instead of process-level annotations. Module-level annotations are
 more flexible in that they can be modified and cleared during the client
 program’s lifetime. Module-level annotations can be set via the Crashpad client
 library. Process-level annotations are useful for annotations that the
 collection server requires be present, that have fixed values, and for cases
 where a program that does not use the Crashpad client library is being
 monitored.
 +
 Breakpad-type collection servers only require the +"prod"+ and +"ver"+
 annotations, which should be set to the product name or identifier and product
 version, respectively. It is unusual to specify other annotations as
 process-level annotations via this argument.
 
 *--database*='PATH'::
 Use 'PATH' as the path to the Crashpad crash report database. This option is
 required. Crash reports are written to this database, and if uploads are
 enabled, uploaded from this database to a crash report collection server. If the
 database does not exist, it will be created, provided that the parent directory
 of 'PATH' exists.
 
 *--handshake-fd*='FD'::
 Perform the handshake with the initial client on the file descriptor at 'FD'.
-This option is required. This option is only valid on Mac OS X.
+Either this option or *--mach-service*, but not both, is required. This option
+is only valid on OS X.
+
+*--mach-service*='SERVICE'::
+Check in with the bootstrap server under the name 'SERVICE'. Either this option
+or *--handshake-fd*, but not both, is required. This option is only valid on OS
+X.
++
+'SERVICE' may already be reserved with the bootstrap server in cases where this
+tool is started by launchd(8) as a result of a message being sent to a service
+declared in a job’s +MachServices+ dictionary (see launchd.plist(5)). The
+service name may also be completely unknown to the system.
 
 *--persistent*::
 Continue running after the last client exits. If this option is not specified,
 this server will exit as soon as it has no clients, although on startup, it
 always waits for at least one client to connect. This option is only valid on
 Windows.
 
 *--pipe-name*='PIPE'::
 Listen on the given pipe name for connections from clients. 'PIPE' must be of
 the form +\\.\pipe\<somename>+. This option is required. This option is only
@@ skipping 28 matching lines @@
 Failure, with a message printed to the standard error stream.
 
 == See Also
 
 man_link:catch_exception_tool[1],
 man_link:crashpad_database_util[1],
 man_link:generate_dump[1],
 man_link:run_with_crashpad[1]
 
 include::../doc/support/man_footer.ad[]