properly define perl_parse() return value
authorZefram <zefram@fysh.org>
Sun, 10 Dec 2017 21:37:16 +0000 (21:37 +0000)
committerZefram <zefram@fysh.org>
Sun, 10 Dec 2017 21:59:42 +0000 (21:59 +0000)
commit0301e899536a22752f40481d8a1d141b7a7dda82
treec54c033097f69e8054c5d950316b8f74f44073f1
parentc9ffefcc81905ed7e70f5e766cd1a0f2f7d90d51
properly define perl_parse() return value

perl_parse()'s return value has historically had conflicting purposes.
perlmain.c uses it as a truth value, but perlembed.pod has shown it being
used as an exit code.  perl_parse() has not had its own documentation.
What the function has actually done is to return zero for normal
completion and an exit code for early termination.  For this to be
a usable convention depended on early termination never using exit
code 0, and that's specifically *native* exit code 0, which could have
any significance.  In fact exit code 0 could arise for a compile-time
termination even on Unix through "CHECK { exit 0 }", and the mishandling
of that situation was bug [perl #2754].

Since perl_destruct() provides a native exit code unencumbered by any
attempt to simultaneously be a truth value, perl_parse() doesn't really
need to provide an exit code.  So define that perl_parse()'s return
value is principally a truth value.  Change the perlembed tutorial to
show it being so used, with an exit code coming from perl_destruct().
However, most of the historical usage of perl_parse()'s return value
as an exit code can be preserved.  Make it return 0x100 for exit(0),
which both serves as the essential truth value and on Unix also serves
as the proper exit code, because that set bit will be masked off when
actually exiting.  This works on Unix but will have variable effect on
other OSes; at least it will reliably indicate an actual exit.

perl_run() has a similar problem in the interpretation of its return
value, but not affecting the main perl executable, because perlmain.c
ignores its return value.  Similarly define that it is principally a
truth value, with preserved usage of non-zero return values as exit
codes, with exit code 0 transformed into 0x100.  This requires some
extra logic to distinguish between local completion and exit(0), which
were not previously distinguished.

Fully document perl_parse(), perl_run(), and perl_destruct() as API
functions.  Make the perlembed tutorial always show a proper exit
from main(), using "exit(EXIT_SUCCESS)" for portability when errors
are not being checked.  Make perlembed always show a null argv[argc]
being supplied to perl_parse(), where an argv is constructed.  (Commit
54c85bb058e15520a2fc0ba34007743aae56be34 added a note to perlembed saying
that that's required, but didn't fix the examples to show it being done.)
perl.c
pod/perlembed.pod
t/op/blocks.t