local-lib5/man/man3/IPC::Run::Win32Helper.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "IPC::Run::Win32Helper 3"
 127 .TH IPC::Run::Win32Helper 3 "2009-07-13" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 IPC::Run::Win32Helper \- helper routines for IPC::Run on Win32 platforms.
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use IPC::Run::Win32Helper;   # Exports all by default
 138 .Ve
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 IPC::Run needs to use sockets to redirect subprocess I/O so that the \fIselect()\fR loop
 142 will work on Win32. This seems to only work on WinNT and Win2K at this time, not
 143 sure if it will ever work on Win95 or Win98. If you have experience in this area, please
 144 contact me at barries@slaysys.com, thanks!.
 145 .SH "FUNCTIONS"
 146 .IX Header "FUNCTIONS"
 147 .IP "\fIoptimize()\fR" 4
 148 .IX Item "optimize()"
 149 Most common incantations of \f(CW\*(C`run()\*(C'\fR (\fInot\fR \f(CW\*(C`harness()\*(C'\fR, \f(CW\*(C`start()\*(C'\fR,
 150 or \f(CW\*(C`finish()\*(C'\fR) now use temporary files to redirect input and output
 151 instead of pumper processes.
 152 .Sp
 153 Temporary files are used when sending to child processes if input is
 154 taken from a scalar with no filter subroutines.  This is the only time
 155 we can assume that the parent is not interacting with the child's
 156 redirected input as it runs.
 157 .Sp
 158 Temporary files are used when receiving from children when output is
 159 to a scalar or subroutine with or without filters, but only if
 160 the child in question closes its inputs or takes input from
 161 unfiltered SCALARs or named files.  Normally, a child inherits its \s-1STDIN\s0
 162 from its parent; to close it, use \*(L"0<&\-\*(R" or the \f(CW\*(C`noinherit =\*(C'\fR 1> option.
 163 If data is sent to the child from \s-1CODE\s0 refs, filehandles or from
 164 scalars through filters than the child's outputs will not be optimized
 165 because \f(CW\*(C`optimize()\*(C'\fR assumes the parent is interacting with the child.
 166 It is ok if the output is filtered or handled by a subroutine, however.
 167 .Sp
 168 This assumes that all named files are real files (as opposed to named
 169 pipes) and won't change; and that a process is not communicating with
 170 the child indirectly (through means not visible to IPC::Run).
 171 These can be an invalid assumptions, but are the 99% case.
 172 Write me if you need an option to enable or disable optimizations; I
 173 suspect it will work like the \f(CW\*(C`binary()\*(C'\fR modifier.
 174 .Sp
 175 To detect cases that you might want to optimize by closing inputs, try
 176 setting the \f(CW\*(C`IPCRUNDEBUG\*(C'\fR environment variable to the special \f(CW\*(C`notopt\*(C'\fR
 177 value:
 178 .Sp
 179 .Vb 2
 180 \&   C:> set IPCRUNDEBUG=notopt
 181 \&   C:> my_app_that_uses_IPC_Run.pl
 182 .Ve
 183 .IP "\fIoptimizer()\fR rationalizations" 4
 184 .IX Item "optimizer() rationalizations"
 185 Only for that limited case can we be sure that it's ok to batch all the
 186 input in to a temporary file.  If \s-1STDIN\s0 is from a \s-1SCALAR\s0 or from a named
 187 file or filehandle (again, only in \f(CW\*(C`run()\*(C'\fR), then outputs to \s-1CODE\s0 refs
 188 are also assumed to be safe enough to batch through a temp file,
 189 otherwise only outputs to \s-1SCALAR\s0 refs are batched.  This can cause a bit
 190 of grief if the parent process benefits from or relies on a bit of
 191 \&\*(L"early returns\*(R" coming in before the child program exits.  As long as
 192 the output is redirected to a \s-1SCALAR\s0 ref, this will not be visible.
 193 When output is redirected to a subroutine or (deprecated) filters, the
 194 subroutine will not get any data until after the child process exits,
 195 and it is likely to get bigger chunks of data at once.
 196 .Sp
 197 The reason for the optimization is that, without it, \*(L"pumper\*(R" processes
 198 are used to overcome the inconsistancies of the Win32 \s-1API\s0.  We need to
 199 use anonymous pipes to connect to the child processes' stdin, stdout,
 200 and stderr, yet \fIselect()\fR does not work on these.  \fIselect()\fR only works on
 201 sockets on Win32.  So for each redirected child handle, there is
 202 normally a \*(L"pumper\*(R" process that connects to the parent using a
 203 socket\*(--so the parent can \fIselect()\fR on that fd\*(--and to the child on an
 204 anonymous pipe\*(--so the child can read/write a pipe.
 205 .Sp
 206 Using a socket to connect directly to the child (as at least one \s-1MSDN\s0
 207 article suggests) seems to cause the trailing output from most children
 208 to be lost.  I think this is because child processes rarely close their
 209 stdout and stderr explicitly, and the winsock dll does not seem to flush
 210 output when a process that uses it exits without explicitly closing
 211 them.
 212 .Sp
 213 Because of these pumpers and the inherent slowness of Win32
 214 \&\fICreateProcess()\fR, child processes with redirects are quite slow to
 215 launch; so this routine looks for the very common case of
 216 reading/writing to/from scalar references in a \fIrun()\fR routine and
 217 converts such reads and writes in to temporary file reads and writes.
 218 .Sp
 219 Such files are marked as \s-1FILE_ATTRIBUTE_TEMPORARY\s0 to increase speed and
 220 as \s-1FILE_FLAG_DELETE_ON_CLOSE\s0 so it will be cleaned up when the child
 221 process exits (for input files).  The user's default permissions are
 222 used for both the temporary files and the directory that contains them,
 223 hope your Win32 permissions are secure enough for you.  Files are
 224 created with the Win32API::File defaults of
 225 FILE_SHARE_READ|FILE_SHARE_WRITE.
 226 .Sp
 227 Setting the debug level to \*(L"details\*(R" or \*(L"gory\*(R" will give detailed
 228 information about the optimization process; setting it to \*(L"basic\*(R" or
 229 higher will tell whether or not a given call is optimized.  Setting
 230 it to \*(L"notopt\*(R" will highligh those calls that aren't optimized.
 231 .IP "win32_parse_cmd_line" 4
 232 .IX Item "win32_parse_cmd_line"
 233 .Vb 1
 234 \&   @words = win32_parse_cmd_line( q{foo bar \*(Aqbaz baz\*(Aq "bat bat"} );
 235 .Ve
 236 .Sp
 237 returns 4 words. This parses like the bourne shell (see
 238 the bit about \fIshellwords()\fR in Text::ParseWords), assuming we're
 239 trying to be a little cross-platform here.  The only difference is
 240 that \*(L"\e\*(R" is *not* treated as an escape except when it precedes
 241 punctuation, since it's used all over the place in \s-1DOS\s0 path specs.
 242 .Sp
 243 \&\s-1TODO:\s0 globbing? probably not (it's unDOSish).
 244 .Sp
 245 \&\s-1TODO:\s0 shebang emulation? Probably, but perhaps that should be part
 246 of Run.pm so all spawned processes get the benefit.
 247 .Sp
 248 \&\s-1LIMITATIONS:\s0 shellwords dies silently on malformed input like
 249 .Sp
 250 .Vb 1
 251 \&   a\e"
 252 .Ve
 253 .IP "win32_spawn" 4
 254 .IX Item "win32_spawn"
 255 Spawns a child process, possibly with \s-1STDIN\s0, \s-1STDOUT\s0, and \s-1STDERR\s0 (file descriptors 0, 1, and 2, respectively) redirected.
 256 .Sp
 257 \&\fB\s-1LIMITATIONS\s0\fR.
 258 .Sp
 259 Cannot redirect higher file descriptors due to lack of support for this in the
 260 Win32 environment.
 261 .Sp
 262 This can be worked around by marking a handle as inheritable in the
 263 parent (or leaving it marked; this is the default in perl), obtaining it's
 264 Win32 handle with \f(CW\*(C`Win32API::GetOSFHandle(FH)\*(C'\fR or
 265 \&\f(CW\*(C`Win32API::FdGetOsFHandle($fd)\*(C'\fR and passing it to the child using the command
 266 line, the environment, or any other \s-1IPC\s0 mechanism (it's a plain old integer).
 267 The child can then use \f(CW\*(C`OsFHandleOpen()\*(C'\fR or \f(CW\*(C`OsFHandleOpenFd()\*(C'\fR and possibly
 268 \&\f(CW\*(C`<open FOO "\*(C'\fR&BAR">> or \f(CW\*(C`<open FOO "\*(C'\fR&$fd>> as need be.  Ach, the pain!
 269 .Sp
 270 Remember to check the Win32 handle against \s-1INVALID_HANDLE_VALUE\s0.
 271 .SH "AUTHOR"
 272 .IX Header "AUTHOR"
 273 Barries Slaymaker <barries@slaysys.com>.  Funded by Perforce Software, Inc.
 274 .SH "COPYRIGHT"
 275 .IX Header "COPYRIGHT"
 276 Copyright 2001, Barrie Slaymaker, All Rights Reserved.
 277 .PP
 278 You may use this under the terms of either the \s-1GPL\s0 2.0 ir the Artistic License.