Proc::Background::Win32(3p)

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.