From d5c3a6f03944db48dd9640524b40a6bb6b9d360e Mon Sep 17 00:00:00 2001
From: Justine Tunney <jtunney@gmail.com>
Date: Fri, 26 Jun 2020 16:09:04 -0700
Subject: [PATCH] Add example for auto debugging and asm() usage

---
 ape/ape.S                           |  2 +-
 examples/auto-launch-gdb-on-crash.c | 44 +++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 examples/auto-launch-gdb-on-crash.c

diff --git a/ape/ape.S b/ape/ape.S
index b940c33c..a29c9c4a 100644
--- a/ape/ape.S
+++ b/ape/ape.S
@@ -1932,4 +1932,4 @@ __data_start:
 	.hidden	__piro_start
 
 .end
-
+
\ No newline at end of file
diff --git a/examples/auto-launch-gdb-on-crash.c b/examples/auto-launch-gdb-on-crash.c
new file mode 100644
index 00000000..7e665243
--- /dev/null
+++ b/examples/auto-launch-gdb-on-crash.c
@@ -0,0 +1,44 @@
+#if 0
+/*─────────────────────────────────────────────────────────────────╗
+│ To the extent possible under law, Justine Tunney has waived      │
+│ all copyright and related or neighboring rights to this file,    │
+│ as it is written in the following disclaimers:                   │
+│   • http://unlicense.org/                                        │
+│   • http://creativecommons.org/publicdomain/zero/1.0/            │
+╚─────────────────────────────────────────────────────────────────*/
+#endif
+#include "libc/log/log.h"
+
+/**
+ * Automatically launchs GDB Debugger TUI during crash.
+ *
+ * Run the following inside a terminal:
+ *
+ *     sudo apt install gdb
+ *     make -j12 o//examples/auto-launch-gdb-on-crash.com
+ *     o//examples/auto-launch-gdb-on-crash.com
+ *
+ * Backtrace is logged instead if run outside interactive terminal.
+ * Environmental factors such as GDB, MAKEFLAGS, ADDR2LINE, TERM, and
+ * isatty(STDERR_FILENO) should also be taken into consideration:
+ *
+ *     $ export GDB=eoatuhshtuone
+ *     $ o//examples/auto-launch-gdb-on-crash.com
+ *     error: Uncaught SIGTRAP
+ *     etc. etc.
+ *
+ * @see https://www.felixcloutier.com/x86/intn:into:int3:int1
+ * @see https://en.wikipedia.org/wiki/INT_(x86_instruction)#INT3
+ * @see examples and reference material on using the asm() keyword
+ *     - libc/nexgen32e/bsf.h
+ *     - libc/nexgen32e/tzcnt.h
+ *     - libc/nexgen32e/cpuid4.h
+ *     - libc/nexgen32e/tinystrcmp.h
+ *     - https://gist.github.com/jart/fe8d104ef93149b5ba9b72912820282c
+ */
+
+int main(int argc, char *argv[]) {
+  showcrashreports();
+  asm("int3"); /* cf. die(), perror("msg"), abort(), exit(1), _Exit(1) */
+  return 0;
+}