Skip to content

Commit

Permalink
Base: Add CrashReporter(1), dbgputstr(2), dump_backtrace(2) manpages
Browse files Browse the repository at this point in the history
Importantly, these document two nonstandard system
calls that Serenity provides.
  • Loading branch information
kleinesfilmroellchen authored and nico committed Nov 1, 2024
1 parent 3375f7d commit a6435ac
Show file tree
Hide file tree
Showing 5 changed files with 109 additions and 0 deletions.
37 changes: 37 additions & 0 deletions Base/usr/share/man/man1/Applications/CrashReporter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
## Name

![Icon](/res/icons/16x16/app-crash-reporter.png) CrashReporter - information about crashed programs

[Open](file:///bin/CrashReporter)

## Synopsis

```sh
$ CrashReporter [--unlink] <coredump-path>
```

## Description

CrashReporter informs about crashed programs by providing a GUI to examine the crashed program's last state.

![](CrashReporter.png)

The four main tabs display the call stack (or backtrace) when the program crashed, the CPU registers just before crashing, the environment variables and the mapped memory regions. For registers and backtrace, there is one tab per thread.

The buttons allow to open the relevant files in HackStudio, or to save the text of the backtrace to a file.

If CrashDaemon is running, CrashReporter is automatically opened when a program crashes.

## Options

- `--help`: Display help message and exit
- `--version`: Print version
- `--unlink`: Delete the coredump after it's parsed

## Arguments

- `coredump-path`: Path to the core dump file to display

## See Also

- [`dump_backtrace`(2)](help://man/2/dump_backtrace)
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions Base/usr/share/man/man1/crash.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,7 @@ $ crash -F
Testing: "Write to freed memory"
Shell: Job 1 (crash -F) Segmentation violation
```

## See Also

- [`dump_backtrace`(2)](help://man/2/dump_backtrace)
35 changes: 35 additions & 0 deletions Base/usr/share/man/man2/dbgputstr.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
## Name

dbgputstr - print logs to the serial console

## Synopsis

```**c++
#include <stdio.h>
void dbgputstr(char const* characters, size_t length);
```

## Description

`dbgputstr` is Serenity's generic kernel-supported logging facility. Currently, logging submitted to `dbgputstr` is directly printed to the serial console.

`dbgputstr` takes as arguments a pointer to a string to be written, and the length of that string.

Users should access logging functionality via the `dbg`/`dbgln` functions, which add additional process information to the log output.

## Errors

The C library function does not propagate errors.

The system call itself can fail with the following errors:

- `EFAULT`: Invalid or inaccessible string.

No error is reported if the output cannot be written to a serial device.

If the return value is positive, this indicates the actual number of characters written, in case the provided string was null-terminated before the length was reached.

## See Also

- [`dump_backtrace`(2)](help://man/2/dump_backtrace)
33 changes: 33 additions & 0 deletions Base/usr/share/man/man2/dump_backtrace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
## Name

dump_backtrace - dump the process's current kernel backtrace

## Synopsis

```**c++
#include <unistd.h>
void dump_backtrace();
```

## Description

`dump_backtrace` prints the process's kernel backtrace to the serial console. This is most useful for information about a process crash. Note that the userspace backtrace, which in general is more useful, is not printed by this syscall, since it can be printed entirely by userspace examining its own stack.

The output may look something like this:

```
254.838 [#0 crash(55:55)]: Kernel + 0x000000000052b9f4 Kernel::Process::crash(int, AK::Optional<Kernel::RegisterState const&>, bool) +0x394
254.838 [#0 crash(55:55)]: Kernel + 0x000000000050f1d4 Kernel::handle_crash(Kernel::RegisterState const&, char const*, int, bool) +0x2ec
254.838 [#0 crash(55:55)]: Kernel + 0x000000000059e648 illegal_instruction_asm_entry +0x30
```

## Errors

This syscall does not return any errors to the user.

## See Also

- [`dbgputstr`(2)](help://man/2/dbgputstr)
- [`crash`(2)](help://man/1/crash)
- [`CrashReporter(1)`](help://man/1/Applications/CrashReporter)

0 comments on commit a6435ac

Please sign in to comment.