NAME

Win32::Status - convert Win32 status strings to integers and back

SYNOPSIS

  use Win32::Status;

  # Figure out what an exit code of 0xC0000417 actually means
  say $Win32::Status::INTEGER_TO_SYMBOL{ 0xC0000417 };
  # ...prints STATUS_INVALID_CRUNTIME_PARAMETER

  # Or the other way around:
  printf "0x%0x\n", $Win32::Status::SYMBOL_TO_INTEGER{ STATUS_INVALID_CRUNTIME_PARAMETER }

  # Or use the constants directly
  use Win32::Status qw( STATUS_ACCESS_VIOLATION );
  say STATUS_ACCESS_VIOLATION();
  # ...prints 3221225477

This module provides a perl interface to the symbols defined in the Windows ntstatus.h header. It allows mapping from integers to symbols and vice-versa.

DESCRIPTION

This module contains two public hashes:

%INTEGER_TO_SYMBOL

Map from an integer value to a status string (e.g. 0xC0000005 => 'STATUS_ACCESS_VIOLATION').

Note that a few integers have multiple associated symbols. In that case, the returned string is the string arbitrarily chosen as the most relevant.

%SYMBOL_TO_INTEGER

Map from a status string to an integer (e.g. 'STATUS_ACCESS_VIOLATION' => 0xC0000005)

On request, the module will also directly export any named status constants:

  use Win32::Status qw( STATUS_ACCESS_VIOLATION STATUS_INTEGER_OVERFLOW );
  # ... later:
  if ($process->exitcode() == STATUS_ACCESS_VIOLATION) {
    warn "Process crashed with access violation!";
  }
  elsif ($process->exitcode() == STATUS_INTEGER_OVERFLOW) {
    warn "Process died due to integer overflow!";
  }

CAVEATS

Be aware that, at time of writing, perl on Windows will always truncate 32-bit Windows exit codes into 16 bits before storing in $? and ${^CHILD_ERROR_NATIVE}. Therefore, this module can't be used with the return values of the builtin system(), waitpid() or similar functions.

Native Windows APIs for managing processes, such as Win32::Process, don't have this problem.

AUTHOR

Rohan McGovern, <rohan@mcgovern.id.au>

BUGS

Please use http://rt.cpan.org/ to view or report bugs.

LICENSE AND COPYRIGHT

Copyright 2012 Nokia Corporation and/or its subsidiary(-ies).

Copyright 2012 Rohan McGovern.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 2.1 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.