Say what perl -c returns

[jidanni]

The page forgets to say what -c returns. So I added my guess. Please improve it.

[scottchiefbaker]

I don't have any technical details on what this does, but I do think it would be useful information to have in the docs.

[Leont]

Yeah that totally doesn't actually return -1, I don't think any platform supports that. It returns a non-zero value (typically 255 on Unix)

[jidanni]

All I know is it is non-zero.
And well, e.g., the podchecker man page makes it clear what the return values etc. are. Same with most Unix man pages.

[tonycoz]

It depends on what you expect:

tony@venus:.../git/perl6$ perl -Mstrict -ce '++$x'
Global symbol "$x" requires explicit package name (did you forget to declare "my $x"?) at -e line 1.
-e had compilation errors.
tony@venus:.../git/perl6$ echo $?
255
# trying to load Unknown is compile-time
tony@venus:.../git/perl6$ perl -Mstrict -ce 'use Unknown;'
Can't locate Unknown.pm in @INC (you may need to install the Unknown module) (@INC contains: /etc/perl /usr/local/lib/x86_64-linux-gnu/perl/5.36.0 /usr/local/share/perl/5.36.0 /usr/lib/x86_64-linux-gnu/perl5/5.36 /usr/share/perl5 /usr/lib/x86_64-linux-gnu/perl-base /usr/lib/x86_64-linux-gnu/perl/5.36 /usr/share/perl/5.36 /usr/local/lib/site_perl) at -e line 1.
BEGIN failed--compilation aborted at -e line 1.
tony@venus:.../git/perl6$ echo $?
2
# some module you load happens to fail a system call, setting errno
tony@venus:.../git/perl6$ perl -ce 'BEGIN { $! = 21; } $x $x'
Scalar found where operator expected at -e line 1, near "$x $x"
        (Missing operator before $x?)
syntax error at -e line 1, near "$x $x
"
-e had compilation errors.
tony@venus:.../git/perl6$ echo $?
21

I think all you can really say is "non-zero".

[guest20]

useful to have in the docs

What would you use the exit code for in practice?

I can't even think of a useful corner case in a CI context ... It's always going to be does not compile -> build not green

[jidanni]

One would like to double check that all the Perl programs one is about to upload, are all grammatically correct, but one doesn't want to actually run the programs (that do big things.) That's an example of one of the many uses of the return value.

[guest20]

Exactly, you only care if the exit code is zero. You don't care which kind of non-valid perl program you have.

If you want to fix your script, you read the diagnostics perl prints just before exiting.

So to expand on my question: what would a hypothetical calling script do differently if the code you're perl -c 'ing died during a begin block, vs if it didn't have the module it wanted in @inc, vs the perl version not matching the one the script wants vs there being a missing ] at eof, vs an xs module being compiled against the wrong perl, vs perl not having permissions to read a module in @inc, or .... etc?

It just seems unreasonable to enumerate every single way a text file can be a non-valid perl program, especially when unix exit codes are finite.

[jidanni]

Yes. Just mention "Exit value: Returns 0 for success (no syntax errors) and various non-zero values if there were errors."

That way a person reading the man page will know s/he can count on using perl -c to check for syntax errors, unattended.

I mean even

$ man ls

has an Exit status section.