Bug/Feature Request: Exit Code documentation/implementation

[cyntheticfox]

As written, swaylock will exit one of four different values: 0, 1, 2, EXIT_SUCCESS, and EXIT_FAILURE, where the last two are undefined POSIX values that I believe GNU/Linux, BSD, and LLVM map to 0 and 1 respectively (supposedly VMS does something else, and EXIT_FAILURE could be -1 according to the FreeBSD manpage).

So far as I can tell, 2 is used when unable to lock with the legacy wayland API due to that lock being held (likely by another lockscreen), the display dispatch failing, and readiness notification failures.

0 being used as "success" in the sense of daemonization (hopefully) checking, no caught errors (excepting config reads... which always succeed) and PAM/shadow success.

Everything else (all errors) maps to 1.

Can we possibly get this documented in the manpage?

[emersion]

Ideally we'd pick more sensible/consistent exit codes while at it…

[cyntheticfox]

Looking through a few wikis, manpages, and POSIX specs, besides C only allowing an 8-bit integer return and POSIX only looking at 8 bits in most cases anyways, there's only really two common semantics for use beyond 0 and 1:

• Shells generally use 2 for built-ins errors, 127 for command not found, maybe 126 for command found but not executable, and 128+n for a command terminated by some signal number n (pretty sure this last part is done automatically).
• FreeBSD has a sysexits.h header that defines exit codes 64 through 78: https://man.freebsd.org/cgi/man.cgi?query=sysexits&sektion=3

I personally like the set of error codes that BSD defines, but it really just needs to be documented, whatever is used -- likely defined as macros in some header file. The main point of exit codes is for a calling program to know the exit status anyways, not really humans (that's what we have logs and stderr for).

For what's already used for errors, I can see classifying them (and so giving different error codes) in at least these ways:

• Argument parsing errors in main.c
• Memory allocation errors on password buffer creation
• Kernel structure allocation errors (pipes, file descriptors) on sigusr pipe creation and on daemonization attempts
• Compositor connection errors on initial connection
• Compositor read errors mulitple times
• Compositor output check errors when tested
• Compositor use errors on dispatch, on ready notify, and on screen lock state change
• Keymapping errors in keyboard_keymap
• Process permissions errors on euid check and on anti-check
• Child spawning errors in shadow.c and in pam.c
• Polling errors in loop.c

Broadly, they're probably just:

• Argument/config check errors
• OS/Unix errors
• Wayland errors
• Permission errors

Also is that a stray semicolon in pam.c? I'm not super familiar with the undefined C behavior stuff.

EDIT: Had to fix the file links. Works differently than I expected

[emersion]

I'd just use 1 everywhere tbh. No good reason why users would want to tell apart these.

[cyntheticfox]

Most of the time, yes, the specific exit code isn't important. The main time you really need it though is when you fork/manage it via another process.

My particular need is for running the application as a Systemd (oneshot) service, where I need to differentiate why a program exited -- so that for certain types of errors, the program is restarted, but isn't for other, more critical ones.

If nothing else, it could be set to EXIT_FAILURE, with some sort of advanced expectation of the executor to read the stderr to determine it's behavior. As far as I know, there's currently not any one approach taken (varying exit codes, fail-safe behavior in some cases, no error logged in others)

[cyntheticfox]

Whichever strategy is preferable, I can probably implement it in a PR myself if you'd like