Tracking Issue: Documenting Exit Codes

[yoshuawuyts]

Being able to document exit codes would be a useful for many programs, especially when reimplementing existing programs where exit codes can have special meanings.

This thread serves to gather resources about discussions happening around this topic, with the goal that eventually we'll be in a position where it's possible to document all exit codes from our programs.

Related Issues

• signal handling https://github.com/rust-lang-nursery/cli-wg/issues/27
• man pages https://github.com/rust-lang-nursery/cli-wg/issues/38
• error handling in CLI apps https://github.com/rust-lang-nursery/cli-wg/issues/12
• support development of well-behaved CLI apps https://github.com/rust-lang-nursery/cli-wg/issues/21

Links

• https://internals.rust-lang.org/t/mini-pre-rfc-redesigning-process-exitstatus/5426/15
• Tracking issue for std::process::ExitCode (feature process_exitcode_placeholder) rust-lang/rust#48711

[killercup]

Also see "Error handling in CLI apps" (#12), and "Support development of well-behaved CLI apps" (#21), where exit codes came up before

[XAMPPRocky]

I wonder if as part of providing easy documentation on exit codes if there's a possibility for a standard set of error codes like HTTP. I think specifically having a way categorise common situations such as argument errors, file system errors, and internal errors. This could be used in a abstraction over StatusCode to be extended with third party libraries such as failure and clap.

Example error codes.

• 400: Incorrect arguments
  • When required arguments are missing or different arguments in conflict are used. (Could be handled directly in command line parsers like clap).
• 403: Permissions error
  • Program encounter permissions errors when using the file system.
• 404: File/Directory not found
  • When a path argument provided is not found in the file system.
• 415: Unsupported File Type
  • The path argument provided contains a file format the program can't handle.

[epage]

Didn't realize that sysexits.h hasn't been referenced yet in this issue. See exitcodes

[uazu]

You only get a byte for exit codes (portably), so numbers 400+ are out. 8 bits isn't a lot of space to pack in much information. I think 0 and 1 take care of most things, and enables the tool user to use if, &&, || etc in their shell. It's only worth passing through other numbers if it makes sense for how that tool is going to be used, e.g. if you expect the user to write shell-scripts that switch behaviour based on different types of failure. Certainly use sysexits.h if that covers your situation, but that is not a fixed rule. User convenience and "least surprise" probably count more.

[Dylan-DPC-zz]

This might be helpful: http://man7.org/linux/man-pages/man3/errno.3.html

[killercup]

I'll assign this to me to find a place to put these docs but would eventually like to work with @yoshuawuyts to produce said docs :)