handler/crashpad_handler.ad - crashpad/crashpad - Git at Google

 // 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

 = crashpad_handler(8)

 == Name

 crashpad_handler - Crashpad’s exception handler server

 == Synopsis

 [verse]
 *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 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. Alternatively, the server
 can inherit an already-created pipe from a parent process by using the
 *--initial-client-data* mechanism. That argument also takes all of the arguments
 that would normally be passed in a registration message, and so constitutes
 registration of the first client. Subsequent clients may then register by
 communicating with the server via the pipe. 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 a server started via the
 *--initial-client-data* mechanism loses all of its clients, it exits after
 allowing any upload in progress to complete.

 On Windows, this executable is built by default as a Windows GUI app, so no
 console will appear in normal usage. This is the version that will typically be
 used. A second copy is also made with a +.com+ extension, rather than +.exe+. In
 this second copy, the PE header is modified to indicate that it's a console app.
 This is useful because the +.com+ is found in the path before the +.exe+, so
 when run normally from a shell using only the basename (without an explicit
 +.com+ or +.exe+ extension), the +.com+ console version will be chosen, and so
 stdio will be hooked up as expected to the parent console so that logging output
 will be visible.

 It is not normally appropriate to invoke this program directly. Usually, it will
 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'.
 Either this option or *--mach-service*, but not both, is required. This option
 is only valid on OS X.

 *--initial-client-data*='HANDLE_request_crash_dump','HANDLE_request_non_crash_dump','HANDLE_non_crash_dump_completed','HANDLE_first_pipe_instance','HANDLE_client_process','Address_crash_exception_information','Address_non_crash_exception_information','Address_debug_critical_section'::
 Register the initial client using the inherited handles and data provided. For
 more information on the arguments, see the implementations of +CrashpadClient+
 and +ExceptionHandlerServer+. Either this option or *--pipe-name*, but not both,
 is required. This option is only valid on Windows.
 +
 When this option is present, the server creates a new named pipe at a random
 name and informs its client of the name. The server waits for at least one
 client to register, and exits when all clients have exited, after waiting for
 any uploads in progress to complete.

 *--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.

 *--no-rate-limit*::
 Do not rate limit the upload of crash reports. By default uploads are throttled
 to one per hour. Using this option disables that behavior, and Crashpad will
 attempt to upload all captured reports.

 *--pipe-name*='PIPE'::
 Listen on the given pipe name for connections from clients. 'PIPE' must be of
 the form +\\.\pipe\<somename>+. Either this option or *--initial-client-data*,
 but not both, is required. This option is only valid on Windows.
 +
 When this option is present, the server creates a named pipe at 'PIPE', a name
 known to both the server and its clients. The server continues running even
 after all clients have exited.

 *--reset-own-crash-exception-port-to-system-default*::
 Causes the exception handler server to set its own crash handler to the system
 default before beginning operation. This is only expected to be useful in cases
 where the server inherits an inappropriate crash handler from its parent
 process. This option is only valid on OS X. Use of this option is discouraged.
 It should not be used absent extraordinary circumstances.

 *--url*='URL'::
 If uploads are enabled, sends crash reports to the Breakpad-type crash report
 collection server at 'URL'. Uploads are disabled by default, and can only be
 enabled for a database by a Crashpad client using the Crashpad client library,
 typically in response to a user requesting this behavior. If this option is not
 specified, this program will behave as if uploads are disabled.

 *--help*::
 Display help and exit.

 *--version*::
 Output version information and exit.

 == Exit Status

 *0*::
 Success.

 *1*::
 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[]
	// 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

	= crashpad_handler(8)

	== Name

	crashpad_handler - Crashpad’s exception handler server

	== Synopsis

	[verse]
	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 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. Alternatively, the server
	can inherit an already-created pipe from a parent process by using the
	--initial-client-data mechanism. That argument also takes all of the arguments
	that would normally be passed in a registration message, and so constitutes
	registration of the first client. Subsequent clients may then register by
	communicating with the server via the pipe. 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 a server started via the
	--initial-client-data mechanism loses all of its clients, it exits after
	allowing any upload in progress to complete.

	On Windows, this executable is built by default as a Windows GUI app, so no
	console will appear in normal usage. This is the version that will typically be
	used. A second copy is also made with a +.com+ extension, rather than +.exe+. In
	this second copy, the PE header is modified to indicate that it's a console app.
	This is useful because the +.com+ is found in the path before the +.exe+, so
	when run normally from a shell using only the basename (without an explicit
	+.com+ or +.exe+ extension), the +.com+ console version will be chosen, and so
	stdio will be hooked up as expected to the parent console so that logging output
	will be visible.

	It is not normally appropriate to invoke this program directly. Usually, it will
	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'.
	Either this option or --mach-service, but not both, is required. This option
	is only valid on OS X.

	--initial-client-data='HANDLE_request_crash_dump','HANDLE_request_non_crash_dump','HANDLE_non_crash_dump_completed','HANDLE_first_pipe_instance','HANDLE_client_process','Address_crash_exception_information','Address_non_crash_exception_information','Address_debug_critical_section'::
	Register the initial client using the inherited handles and data provided. For
	more information on the arguments, see the implementations of +CrashpadClient+
	and +ExceptionHandlerServer+. Either this option or --pipe-name, but not both,
	is required. This option is only valid on Windows.
	+
	When this option is present, the server creates a new named pipe at a random
	name and informs its client of the name. The server waits for at least one
	client to register, and exits when all clients have exited, after waiting for
	any uploads in progress to complete.

	--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.

	--no-rate-limit::
	Do not rate limit the upload of crash reports. By default uploads are throttled
	to one per hour. Using this option disables that behavior, and Crashpad will
	attempt to upload all captured reports.

	--pipe-name='PIPE'::
	Listen on the given pipe name for connections from clients. 'PIPE' must be of
	the form +\\.\pipe\<somename>+. Either this option or --initial-client-data,
	but not both, is required. This option is only valid on Windows.
	+
	When this option is present, the server creates a named pipe at 'PIPE', a name
	known to both the server and its clients. The server continues running even
	after all clients have exited.

	--reset-own-crash-exception-port-to-system-default::
	Causes the exception handler server to set its own crash handler to the system
	default before beginning operation. This is only expected to be useful in cases
	where the server inherits an inappropriate crash handler from its parent
	process. This option is only valid on OS X. Use of this option is discouraged.
	It should not be used absent extraordinary circumstances.

	--url='URL'::
	If uploads are enabled, sends crash reports to the Breakpad-type crash report
	collection server at 'URL'. Uploads are disabled by default, and can only be
	enabled for a database by a Crashpad client using the Crashpad client library,
	typically in response to a user requesting this behavior. If this option is not
	specified, this program will behave as if uploads are disabled.

	--help::
	Display help and exit.

	--version::
	Output version information and exit.

	== Exit Status

	0::
	Success.

	1::
	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[]