Merge bitcoin/bitcoin#22226: doc: add unittest core dump instructions

12313382e60c84f106127566d004c03384ca5abf doc: test: unittest segfault gdb (James O'Beirne)

Pull request description:

  Quick note on how to get core dumps out of the unittests.

ACKs for top commit:
  theStack:
    ACK 12313382e60c84f106127566d004c03384ca5abf

Tree-SHA512: d749d9117f96af85f9053884c57df766ac1d29e57b2555d4fc63bd9dc29df47487954cee1c7cd78ee420ae1c9c7da7ddc9797b6c636ce7641eae20622eaa3fee

1 files changed, 26 insertions, 0 deletions

diff --git a/src/test/README.md b/src/test/README.md
index 57cda26d7c..d03411c3ed 100644
--- a/src/test/README.md
+++ b/src/test/README.md
@@ -74,3 +74,29 @@ start debugging, just like you would with any other program:
 ```bash
 gdb src/test/test_bitcoin
 ```
+
+#### Segmentation faults
+
+If you hit a segmentation fault during a test run, you can diagnose where the fault
+is happening by running `gdb ./src/test/test_bitcoin` and then using the `bt` command
+within gdb.
+
+Another tool that can be used to resolve segmentation faults is
+[valgrind](https://valgrind.org/).
+
+If for whatever reason you want to produce a core dump file for this fault, you can do
+that as well. By default, the boost test runner will intercept system errors and not
+produce a core file. To bypass this, add `--catch_system_errors=no` to the
+`test_bitcoin` arguments and ensure that your ulimits are set properly (e.g. `ulimit -c
+unlimited`).
+
+Running the tests and hitting a segmentation fault should now produce a file called `core`
+(on Linux platforms, the file name will likely depend on the contents of
+`/proc/sys/kernel/core_pattern`).
+
+You can then explore the core dump using
+``` bash
+gdb src/test/test_bitcoin core
+
+(gbd) bt  # produce a backtrace for where a segfault occurred
+```