NAME

Process::Status - a handle on process termination, like $?

VERSION

version 0.010

OVERVIEW

When you run a system command with system or qx`` or a number of other mechanisms, the process termination status gets put into $? as an integer. In C, it's just an integer, and it stores a few pieces of data in different bits.

Process::Status just provides a few simple methods to make it easier to inspect. It exists almost entirely to provide as_struct and as_string, which provide a simple decomposition of $?.

Methods called on Process::Status without first calling a constructor will work on an implicitly-constructed object using the current value of $?. To get an object for a specific value, you can call new and pass an integer. You can also call new with no arguments to get an object for the current value of $?, if you want to keep that ugly variable out of your code.

PERL VERSION

This library should run on perls released even an extremely long time ago. It should work on any version of perl released in the last ten years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

METHODS

new

  my $ps = Process::Status->new( $status );
  my $ps = Process::Status->new; # acts as if you'd passed $?

status_code

This returns the value of the integer return value, as you might have found in $?.

is_success

This method returns true if the status code is zero.

exitstatus

This method returns the exit status encoded in the status. In other words, it's the number in the top eight bits.

signal

This returns the signal caught by the process, or zero.

cored

This method returns true if the process dumped core.

as_struct

This method returns a hashref describing the status. Its exact contents may change over time; it is meant for human, not computer, consumption.

as_string

This method returns a string describing the status. Its exact contents may change over time; it is meant for human, not computer, consumption.

Roughly, you might get things like this:

  exited 0
  exited 92
  exited 2, caught SIGDERP
  exited 2, caught SIGSEGV; dumped core

assert_ok

  Process::Status->assert_ok($program_name);

This method does nothing if $? is 0. Otherwise, it croaks with a message like:

  your-program-name exited 13, caught SIGNES

If a program name is not provided, "program" is used.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTORS

• Michael McClimon <michael@mcclimon.org>

• Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Process::Status

perl -MCPAN -e shell
install Process::Status