.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IPC::Run::Win32Helper 3"
.TH IPC::Run::Win32Helper 3 "2014-12-11" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IPC::Run::Win32Helper \- helper routines for IPC::Run on Win32 platforms.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use IPC::Run::Win32Helper;   # Exports all by default
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
IPC::Run needs to use sockets to redirect subprocess I/O so that the \fIselect()\fR loop
will work on Win32. This seems to only work on WinNT and Win2K at this time, not
sure if it will ever work on Win95 or Win98. If you have experience in this area, please
contact me at barries@slaysys.com, thanks!.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fIoptimize()\fR" 4
.IX Item "optimize()"
Most common incantations of \f(CW\*(C`run()\*(C'\fR (\fInot\fR \f(CW\*(C`harness()\*(C'\fR, \f(CW\*(C`start()\*(C'\fR,
or \f(CW\*(C`finish()\*(C'\fR) now use temporary files to redirect input and output
instead of pumper processes.
.Sp
Temporary files are used when sending to child processes if input is
taken from a scalar with no filter subroutines.  This is the only time
we can assume that the parent is not interacting with the child's
redirected input as it runs.
.Sp
Temporary files are used when receiving from children when output is
to a scalar or subroutine with or without filters, but only if
the child in question closes its inputs or takes input from 
unfiltered SCALARs or named files.  Normally, a child inherits its \s-1STDIN\s0
from its parent; to close it, use \*(L"0<&\-\*(R" or the \f(CW\*(C`noinherit => 1\*(C'\fR option.
If data is sent to the child from \s-1CODE\s0 refs, filehandles or from
scalars through filters than the child's outputs will not be optimized
because \f(CW\*(C`optimize()\*(C'\fR assumes the parent is interacting with the child.
It is ok if the output is filtered or handled by a subroutine, however.
.Sp
This assumes that all named files are real files (as opposed to named
pipes) and won't change; and that a process is not communicating with
the child indirectly (through means not visible to IPC::Run).
These can be an invalid assumptions, but are the 99% case.
Write me if you need an option to enable or disable optimizations; I
suspect it will work like the \f(CW\*(C`binary()\*(C'\fR modifier.
.Sp
To detect cases that you might want to optimize by closing inputs, try
setting the \f(CW\*(C`IPCRUNDEBUG\*(C'\fR environment variable to the special \f(CW\*(C`notopt\*(C'\fR
value:
.Sp
.Vb 2
\&   C:> set IPCRUNDEBUG=notopt
\&   C:> my_app_that_uses_IPC_Run.pl
.Ve
.IP "\fIoptimizer()\fR rationalizations" 4
.IX Item "optimizer() rationalizations"
Only for that limited case can we be sure that it's ok to batch all the
input in to a temporary file.  If \s-1STDIN\s0 is from a \s-1SCALAR\s0 or from a named
file or filehandle (again, only in \f(CW\*(C`run()\*(C'\fR), then outputs to \s-1CODE\s0 refs
are also assumed to be safe enough to batch through a temp file,
otherwise only outputs to \s-1SCALAR\s0 refs are batched.  This can cause a bit
of grief if the parent process benefits from or relies on a bit of
\&\*(L"early returns\*(R" coming in before the child program exits.  As long as
the output is redirected to a \s-1SCALAR\s0 ref, this will not be visible.
When output is redirected to a subroutine or (deprecated) filters, the
subroutine will not get any data until after the child process exits,
and it is likely to get bigger chunks of data at once.
.Sp
The reason for the optimization is that, without it, \*(L"pumper\*(R" processes
are used to overcome the inconsistencies of the Win32 \s-1API. \s0 We need to
use anonymous pipes to connect to the child processes' stdin, stdout,
and stderr, yet \fIselect()\fR does not work on these.  \fIselect()\fR only works on
sockets on Win32.  So for each redirected child handle, there is
normally a \*(L"pumper\*(R" process that connects to the parent using a
socket\*(--so the parent can \fIselect()\fR on that fd\*(--and to the child on an
anonymous pipe\*(--so the child can read/write a pipe.
.Sp
Using a socket to connect directly to the child (as at least one \s-1MSDN\s0
article suggests) seems to cause the trailing output from most children
to be lost.  I think this is because child processes rarely close their
stdout and stderr explicitly, and the winsock dll does not seem to flush
output when a process that uses it exits without explicitly closing
them.
.Sp
Because of these pumpers and the inherent slowness of Win32
\&\fICreateProcess()\fR, child processes with redirects are quite slow to
launch; so this routine looks for the very common case of
reading/writing to/from scalar references in a \fIrun()\fR routine and
converts such reads and writes in to temporary file reads and writes.
.Sp
Such files are marked as \s-1FILE_ATTRIBUTE_TEMPORARY\s0 to increase speed and
as \s-1FILE_FLAG_DELETE_ON_CLOSE\s0 so it will be cleaned up when the child
process exits (for input files).  The user's default permissions are
used for both the temporary files and the directory that contains them,
hope your Win32 permissions are secure enough for you.  Files are
created with the Win32API::File defaults of
FILE_SHARE_READ|FILE_SHARE_WRITE.
.Sp
Setting the debug level to \*(L"details\*(R" or \*(L"gory\*(R" will give detailed
information about the optimization process; setting it to \*(L"basic\*(R" or
higher will tell whether or not a given call is optimized.  Setting
it to \*(L"notopt\*(R" will highlight those calls that aren't optimized.
.IP "win32_parse_cmd_line" 4
.IX Item "win32_parse_cmd_line"
.Vb 1
\&   @words = win32_parse_cmd_line( q{foo bar \*(Aqbaz baz\*(Aq "bat bat"} );
.Ve
.Sp
returns 4 words. This parses like the bourne shell (see
the bit about \fIshellwords()\fR in Text::ParseWords), assuming we're
trying to be a little cross-platform here.  The only difference is
that \*(L"\e\*(R" is *not* treated as an escape except when it precedes 
punctuation, since it's used all over the place in \s-1DOS\s0 path specs.
.Sp
\&\s-1TODO:\s0 globbing? probably not (it's unDOSish).
.Sp
\&\s-1TODO:\s0 shebang emulation? Probably, but perhaps that should be part
of Run.pm so all spawned processes get the benefit.
.Sp
\&\s-1LIMITATIONS:\s0 shellwords dies silently on malformed input like
.Sp
.Vb 1
\&   a\e"
.Ve
.IP "win32_spawn" 4
.IX Item "win32_spawn"
Spawns a child process, possibly with \s-1STDIN, STDOUT,\s0 and \s-1STDERR \s0(file descriptors 0, 1, and 2, respectively) redirected.
.Sp
\&\fB\s-1LIMITATIONS\s0\fR.
.Sp
Cannot redirect higher file descriptors due to lack of support for this in the
Win32 environment.
.Sp
This can be worked around by marking a handle as inheritable in the
parent (or leaving it marked; this is the default in perl), obtaining it's
Win32 handle with \f(CW\*(C`Win32API::GetOSFHandle(FH)\*(C'\fR or
\&\f(CW\*(C`Win32API::FdGetOsFHandle($fd)\*(C'\fR and passing it to the child using the command
line, the environment, or any other \s-1IPC\s0 mechanism (it's a plain old integer).
The child can then use \f(CW\*(C`OsFHandleOpen()\*(C'\fR or \f(CW\*(C`OsFHandleOpenFd()\*(C'\fR and possibly
\&\f(CW\*(C`<open FOO "\*(C'\fR&BAR">> or \f(CW\*(C`<open FOO "\*(C'\fR&$fd>> as need be.  Ach, the pain!
.Sp
Remember to check the Win32 handle against \s-1INVALID_HANDLE_VALUE.\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Barries Slaymaker <barries@slaysys.com>.  Funded by Perforce Software, Inc.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2001, Barrie Slaymaker, All Rights Reserved.
.PP
You may use this under the terms of either the \s-1GPL 2.0\s0 or the Artistic License.