NAME

Proc::Background::Win32 - Windows-specific implementation of process create/wait/kill

DESCRIPTION

This module does not have a public interface. Use Proc::Background.

IMPLEMENTATION

Perl Fork Limitations

When Perl is built as a native Win32 application, the fork and exec are a broken approximation of their Unix counterparts. Calling fork creates a thread instead of a process, and there is no way to exit the thread without running Perl cleanup code, which could damage the parent in unpredictable ways, like closing file handles. Calling POSIX::_exit will kill both parent and child (the whole process), and even calling exec in the child still runs global destruction. File handles are shared between parent and child, so any file handle redirection you perform in the forked child will affect the parent and vice versa.

In short, never call fork or exec on native Win32 Perl.

Command Line

This module implements background processes using Win32::Process, which uses the Windows API's concepts of CreateProcess, TerminateProces, WaitForSingleObject, GetExitCode, and so on.

Windows CreateProcess expects an executable name and a command line; breaking the command line into an argument list is left to each individual application, most of which use the library function https://docs.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw|CommandLineToArgvW. This module uses Win32::ShellQuote to parse and format Windows command lines.

If you supply a single-string command line, and don't specify the executable with the exe option, this module parses the first argument from the command line to be the 'exe' option. It then looks for the 'exe' in $ENV{PATH}, and tries again with a suffix of .exe if it didn't find one. If you specify the option as { exe => undef }, this module skips that step and passes NULL to Win32 CreateProcess, which causes Windows to parse the first argument and find the executable on its own. (Letting Windows search for the executable is probably a better idea anyway, and this might become the default in the future. It only works with Win32::Process 0.17 or later)

If you supply an array of arguments as the command, this module combines them into a command line using Win32::ShellQuote/quote_native. The first argument is used as the executable (unless you specified the 'exe' option, like above).

Initial File Handles

When no handle options are specified, the new process does not inherit any file handles of the current process. This differs from the Unix implementation where they are all inherited by default, but I'm leaving it this way for backward compatibility. In other words, yes, they ought to be inherited by default, but changing that now is more likely to break things than fix things.

If you specify any of stdin, stdout, or stderr, any handle not specified will be inherited as-is. In other words, by indicating you are interested in passing file handles, the default Unix behavior occurs. If you wish to redirect a handle to NUL, set the option to undef:

  stdin  => undef,     # stdin will read from NUL device
  stdout => $some_fh,  # stdout will write to a file handle
  stderr => \*STDERR,  # stderr will go to the same STDERR of the current process

You may set a file handle to a pipe, but beware, Windows does not support non-blocking reads or writes to pipes.

AUTHORS

• Blair Zajac <blair@orcaware.com>

• Michael Conrad <mike@nrdvana.net>

VERSION

version 1.32

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Michael Conrad, (C) 1998-2009 by Blair Zajac.

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