Hosted exit status conditions?

[SirWumpus]

For a hosted environment, should the standard document non-zero exit status conditions?

[ruv]

There are many Forth systems running on operating systems and providing the similar capabilities in this regard. It is good for the entire ecosystem if such capabilities are available through the same interface. For example, same sub-set of common command line options, same sub-set (with the same meaning) of common exit statuses.

My attempt: Desktop Forth system requirements (in the ForthHub wiki). See also the corresponding discussion.

I think, a proposal can be development for that.

[ruv]

Do I really care what type of exception?

Sometimes it makes sense to assess how critical an error is. Otherwise only two values would be enough: 0 and 1.

The conditions of terminating a Forth system can be ordered from less to more critical (more severe) as follows:

• Normal termination
• Abort
• Unrecognized command line option
• Error while compiling a definition
• Uncaught exception
• Unspecified abnormal termination

If we want to use fewer different exit statuses, we can group multiple conditions under one exit status.

[ruv]

A possible approach is that for positive statuses, some lower status numbers cover the cases of all higher status number.

For example:

• 0 — Normal termination
• 1 — Unspecified abnormal termination
• 2 — Uncaught exception
• 3 — Static error in program
• 4 — Unrecognized command line argument
• 5 — Abort

Throw codes can be linked as follows:

• Static error in program: -13, -14, -16, -18, -19, -22, -27, -29, -30, -32, -39, -48, -51
• Abort: -1, -2, -28, -56

If the Forth system can detect conditions for multiple statuses, it should use the exit status with the highest number among them.

Which conditions a Forth system can detect/distinguish is implementation defined.

[ruv]

Perhaps, a better order (in terms of detecting different conditions, and "nesting" of them):

• 0 — Normal termination
• 1 — Unspecified abnormal termination
• 2 — Uncaught exception
• 3 — Abort
• 4 — Static error in program
• 5 — Unrecognized command line argument

[SirWumpus]

I think of grep(1) often when I think of exit status:

• 0 Success; match found
• 1 No match found, no answer, "I'm sorry Dave, I'm afraid I can't do that"
• 2 Command line usage error, eg. invalid option, bad regex.; program can't start
• 3 Uncaught exceptions including Abort
• >3 implementation or user program errors

I prefer exit 1 to reflect an intended negative result. Exit 2 for usage errors (bad command line options, bad regex, smells like fish, missing ingredients, things needed to start/initialise) since that is a frequent category of error.

Exit 3 : I see no need to need to distinguish between Uncaught Exception and Abort; an Abort is an Uncaught Exception. I expect Uncaught Exceptions to be the next most common error during the life of the process or user program.

Exit >3 should be either implementation defined and/or for the user program.

Slicing exits status into finer granularity seems pointless. The user can either view the console (or logs) for detailed error messages .

[ruv]

My idea is that if the Forth system does not distinguish different conditions, it can just return the exit status 1. That is, this status covers all cases of abnormal termination.

In general, less specific conditions cover (include) more specific conditions. Thus, if the system does not distinguish a more specific case, it uses the exit status for a more general case (with a lower exit status number).

The case "Unspecified abnormal termination" includes the case of "Uncaught exception" and cases of ambiguous conditions when the system's choice is to terminate.

The case "Uncaught exception" includes any exception, and also the cases of "Abort", "Error in program", "Error in command line arguments", etc.

The case "Static error in program" includes the case "Unrecognized command line argument".

So, it's up to the system what conditions it will distinguish.

Exit status numbers {16, ..., 31} could be reserved for system-defined conditions.

When a program is loaded, it is possible that the system is not a standard system (see 4.2.2). In this case, the meanings of exit status numbers are up to the program.

[ruv]

A citation from Post4 / Issue#54:

For example piping input echo ABORT | post4; I want to see a non-zero exit status because there was an exception at some point during the session. So echo no-such-word | post4 will result in -13 exception and a non-zero exit status.

echo " ' abort catch " | post4
echo -e " abort \n bye" | post4

Do you count above cases as "there was an exception at some point"?

If you mean only counting uncaught exceptions in interactive mode, then it's still a moot point. It will require adding a variable and counting these exceptions. And what the use?

In production (if not testing), multi-line scripts should not be run in interactive mode (i.e., be passed as the user input device).

[SirWumpus]

It is useful if batch/interactive mode can be selected with a command line argument. Otherwise, the system should automatically select the mode.

I do not think a command line option is necessary, since it should be detectable when stdin is redirected, eg. isatty(STDIN_FILENO).

[ruv]

it should be detectable when stdin is redirected, eg. isatty(STDIN_FILENO)

Yes. But for automated testing (for example, for testing quit) it is very useful if you can redirect stdin and the system will still be in interactive mode.

[ruv]

@SirWumpus wrote:

In batch mode I might want to stop processing with ABORT and drop into interactive mode to do some debugging too (especially for long jobs).

If a Forth system is started in batch mode, the Forth program cannot drop into interactive mode. Batch mode implies that there is no access to the user's interactive input device at all. For example, have a look at Linux daemons or Windows services.

[SirWumpus]

Umm. I think there is a terminology issue here. "Batch" mode or "scripted" is nothing like a daemon or service or embedded code, which are very different beasts in my mind. When I think daemons services, I think servers like HTTP, SMTP, DNS, DHCP, etc. A batch might be at and cron jobs or some user script.

[ruv]

Well, a cron job is also a good example of a situation where the user's interactive input device is not available. If redirection is available, it's up the the user should the redirected stdin be handled in interactive mode or in batch mode.