Add crashpad_database_util and its man page

tools/crashpad_database_util.ad

+// Copyright 2015 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_database_util(1)
+
+== Name
+
+crashpad_database_util - Operate on Crashpad crash report databases
+
+== Synopsis
+
+[verse]
+*crashpad_database_util* ['OPTION…']
+
+== Description
+
+Operates on Crashpad crash report databases. The database’s settings can be
+queried and modified, and information about crash reports stored in the
+database can be displayed.
+
+When this program is requested to both show and set information in a single
+invocation, all “show” operations will be completed prior to beginning any “set”
+operation.
+
+Programs that use the Crashpad client library directly will not normally use
+this tool, but may use the database through the programmatic interfaces in the
+client library. This tool exists to allow developers to manipulate a Crashpad
+database.
+
+== Options
+*-d*, *--database*='PATH'::
+Use 'PATH' as the path to the Crashpad crash report database. This option is
+required. If the database does not exist, it will be created, provided that the
+parent directory of 'PATH' exists.
+
+*--show-client-id*::
+Show the client ID stored in the database’s settings. The client ID is formatted
+as a UUID. The client ID is set when the database is created.
+
+*--show-uploads-enabled*::
+Show the status of the uploads-enabled bit stored in the database’s settings.
+man_link:crashpad_handler[8] does not upload reports when this bit is false.
+This bit is false when a database is created, and is under an application’s
+control via the Crashpad client library interface.
++
+See also *--set-uploads-enabled*.
+
+*--show-last-upload-attempt-time*::
+Show the last-upload-attempt time stored in the database’s settings. This value
+is +0+, meaning “never,” when the database is created.
+man_link:crashpad_handler[8] consults this value before attempting an upload to
+implement its rate-limiting behavior. The database updates this value whenever
+an upload is attempted.
++
+See also *--set-last-upload-attempt-time*.
+
+*--show-pending-reports*::
+Show reports eligible for upload.
+
+*--show-completed-reports*::
+Show reports not eligible for upload. A report is moved from the “pending” state
+to the “completed” state by man_link:crashpad_handler[8]. This may happen when a
+report is successfully uploaded, when a report is not uploaded because uploads
+are disabled, or when a report upload attempt fails and will not be retried.
+
+*--show-all-report-info*::
+With *--show-pending-reports* or *--show-completed-reports*, show all metadata
+for each report displayed. Without this option, only report IDs will be shown.
+
+*--show-report*='UUID'::
+Show a report from the database looked up by its identifier, 'UUID', which must
+be formatted in string representation per RFC 4122 §3. All metadata for each
+report found via a *--show-report* option will be shown. If 'UUID' is not found,
+the string +"not found"+ will be printed. If this program is only requested to
+show a single report and it is not found, it will treat this as a failure for
+the purposes of determining its exit status.
+
+*--set-report-uploads-enabled*='BOOL'::
+Enable or disable report upload in the database’s settings. 'BOOL' is a string
+representation of a boolean value, such as +"0"+ or +"true"+.
++
+See also *--show-uploads-enabled*.
+
+*--set-last-upload-attempt-time*='TIME'::
+Set the last-upload-attempt time in the database’s settings. 'TIME' is a string
+representation of a time, which may be in 'yyyy-mm-dd hh:mm:ss' format, a
+numeric +time_t+ value, or the special string +"never"+.
++
+See also *--show-last-upload-attempt-time*.
+
+*--utc*::
+When showing times, do so in UTC as opposed to the local time zone. When setting
+times, interpret ambiguous time strings in UTC as opposed to the local time
+zone.
+
+*--help*::
+Display help and exit.
+
+*--version*::
+Output version information and exit.
+
+== Examples
+
+Shows all crash reports in a crash report database that are in the “completed”
+state.
+[subs="quotes"]
+----
+$ *crashpad_database_util --database /tmp/crashpad_database \
+      --show-completed-reports*
+23f9512b-63e1-4ead-9dcd-e2e21fbccc68
+4bfca440-039f-4bc6-bbd4-6933cef5efd4
+56caeff8-b61a-43b2-832d-9e796e6e4a50
+----
+
+Disables report upload in a crash report database’s settings, and then verifies
+that the change was made.
+[subs="quotes"]
+----
+$ *crashpad_database_util --database /tmp/crashpad_database \
+      --set-uploads-enabled false*
+$ *crashpad_database_util --database /tmp/crashpad_database \
+      --show-uploads-enabled*
+false
+----
+
+== Exit Status
+
+*0*::
+Success.
+
+*1*::
+Failure, with a message printed to the standard error stream.
+
+== See Also
+
+man_link:crashpad_handler[8]
+
+include::../../doc/man_footer.ad[]