interpret return codes for users

[mitzimorris]

Summary:

Improve error hadling by mapping stan::services::error_codes to messages that make sense to end-user.

Description:

Module stan::services adopted a small set of POSIX error codes following Unix conventions -
https://github.com/stan-dev/stan/blob/develop/src/stan/services/error_codes.hpp

Use of these codes is not consistent across the services, nor does command.hpp do a very good job of interpreting them for the user. Modify command.hpp to provide better feedback for common user mistakes, such as missing data inputs, etc.

All exceptions thrown from command.hpp are caught by main.cpp which uniformly returns error code 70 (stan::services::error_codes::SOFTWARE).

The stan::services error codes shouldn't be reported to end user in CmdStan. Instead, we should replace error code 70 et all with more generally accepted codes

Current Version:

v2.26.1

[mitzimorris]

note this: stan-dev/stan#2534

[mitzimorris]

PR #992 improved error messaging by sending error messages to stderr instead of stdout.
however, the problem with return codes remains; leaving issue open for further improvements.

[mitzimorris]

suggestion would be to follow this: https://shapeshed.com/unix-exit-codes/

What exit code should I use?

The Linux Documentation Project has a list of reserved codes that also offers advice on what code to use for specific scenarios. These are the standard error codes in Linux or UNIX.

1 - Catchall for general errors
2 - Misuse of shell builtins (according to Bash documentation)
126 - Command invoked cannot execute
127 - “command not found”
128 - Invalid argument to exit
128+n - Fatal error signal “n”
130 - Script terminated by Control-C
255* - Exit status out of range

[mitzimorris]

given the above, all stan::services return codes should map to either 1 or 126. recommend 1.