src/engine/SCons/compat/_scons_subprocess.py

   1 # subprocess - Subprocesses with accessible I/O streams
   2 #
   3 # For more information about this module, see PEP 324.
   4 #
   5 # This module should remain compatible with Python 2.2, see PEP 291.
   6 #
   7 # Copyright (c) 2003-2005 by Peter Astrand <astrand@lysator.liu.se>
   8 #
   9 # Licensed to PSF under a Contributor Agreement.
  10 # See http://www.python.org/2.4/license for licensing details.
  11
  12 r"""subprocess - Subprocesses with accessible I/O streams
  13
  14 This module allows you to spawn processes, connect to their
  15 input/output/error pipes, and obtain their return codes.  This module
  16 intends to replace several other, older modules and functions, like:
  17
  18 os.system
  19 os.spawn*
  20 os.popen*
  21 popen2.*
  22 commands.*
  23
  24 Information about how the subprocess module can be used to replace these
  25 modules and functions can be found below.
  26
  27
  28
  29 Using the subprocess module
  30 ===========================
  31 This module defines one class called Popen:
  32
  33 class Popen(args, bufsize=0, executable=None,
  34             stdin=None, stdout=None, stderr=None,
  35             preexec_fn=None, close_fds=False, shell=False,
  36             cwd=None, env=None, universal_newlines=False,
  37             startupinfo=None, creationflags=0):
  38
  39
  40 Arguments are:
  41
  42 args should be a string, or a sequence of program arguments.  The
  43 program to execute is normally the first item in the args sequence or
  44 string, but can be explicitly set by using the executable argument.
  45
  46 On UNIX, with shell=False (default): In this case, the Popen class
  47 uses os.execvp() to execute the child program.  args should normally
  48 be a sequence.  A string will be treated as a sequence with the string
  49 as the only item (the program to execute).
  50
  51 On UNIX, with shell=True: If args is a string, it specifies the
  52 command string to execute through the shell.  If args is a sequence,
  53 the first item specifies the command string, and any additional items
  54 will be treated as additional shell arguments.
  55
  56 On Windows: the Popen class uses CreateProcess() to execute the child
  57 program, which operates on strings.  If args is a sequence, it will be
  58 converted to a string using the list2cmdline method.  Please note that
  59 not all MS Windows applications interpret the command line the same
  60 way: The list2cmdline is designed for applications using the same
  61 rules as the MS C runtime.
  62
  63 bufsize, if given, has the same meaning as the corresponding argument
  64 to the built-in open() function: 0 means unbuffered, 1 means line
  65 buffered, any other positive value means use a buffer of
  66 (approximately) that size.  A negative bufsize means to use the system
  67 default, which usually means fully buffered.  The default value for
  68 bufsize is 0 (unbuffered).
  69
  70 stdin, stdout and stderr specify the executed programs' standard
  71 input, standard output and standard error file handles, respectively.
  72 Valid values are PIPE, an existing file descriptor (a positive
  73 integer), an existing file object, and None.  PIPE indicates that a
  74 new pipe to the child should be created.  With None, no redirection
  75 will occur; the child's file handles will be inherited from the
  76 parent.  Additionally, stderr can be STDOUT, which indicates that the
  77 stderr data from the applications should be captured into the same
  78 file handle as for stdout.
  79
  80 If preexec_fn is set to a callable object, this object will be called
  81 in the child process just before the child is executed.
  82
  83 If close_fds is true, all file descriptors except 0, 1 and 2 will be
  84 closed before the child process is executed.
  85
  86 if shell is true, the specified command will be executed through the
  87 shell.
  88
  89 If cwd is not None, the current directory will be changed to cwd
  90 before the child is executed.
  91
  92 If env is not None, it defines the environment variables for the new
  93 process.
  94
  95 If universal_newlines is true, the file objects stdout and stderr are
  96 opened as a text files, but lines may be terminated by any of '\n',
  97 the Unix end-of-line convention, '\r', the Macintosh convention or
  98 '\r\n', the Windows convention.  All of these external representations
  99 are seen as '\n' by the Python program.  Note: This feature is only
 100 available if Python is built with universal newline support (the
 101 default).  Also, the newlines attribute of the file objects stdout,
 102 stdin and stderr are not updated by the communicate() method.
 103
 104 The startupinfo and creationflags, if given, will be passed to the
 105 underlying CreateProcess() function.  They can specify things such as
 106 appearance of the main window and priority for the new process.
 107 (Windows only)
 108
 109
 110 This module also defines two shortcut functions:
 111
 112 call(*popenargs, **kwargs):
 113     Run command with arguments.  Wait for command to complete, then
 114     return the returncode attribute.
 115
 116     The arguments are the same as for the Popen constructor.  Example:
 117
 118     retcode = call(["ls", "-l"])
 119
 120 check_call(*popenargs, **kwargs):
 121     Run command with arguments.  Wait for command to complete.  If the
 122     exit code was zero then return, otherwise raise
 123     CalledProcessError.  The CalledProcessError object will have the
 124     return code in the returncode attribute.
 125
 126     The arguments are the same as for the Popen constructor.  Example:
 127
 128     check_call(["ls", "-l"])
 129
 130 Exceptions
 131 ----------
 132 Exceptions raised in the child process, before the new program has
 133 started to execute, will be re-raised in the parent.  Additionally,
 134 the exception object will have one extra attribute called
 135 'child_traceback', which is a string containing traceback information
 136 from the childs point of view.
 137
 138 The most common exception raised is OSError.  This occurs, for
 139 example, when trying to execute a non-existent file.  Applications
 140 should prepare for OSErrors.
 141
 142 A ValueError will be raised if Popen is called with invalid arguments.
 143
 144 check_call() will raise CalledProcessError, if the called process
 145 returns a non-zero return code.
 146
 147
 148 Security
 149 --------
 150 Unlike some other popen functions, this implementation will never call
 151 /bin/sh implicitly.  This means that all characters, including shell
 152 metacharacters, can safely be passed to child processes.
 153
 154
 155 Popen objects
 156 =============
 157 Instances of the Popen class have the following methods:
 158
 159 poll()
 160     Check if child process has terminated.  Returns returncode
 161     attribute.
 162
 163 wait()
 164     Wait for child process to terminate.  Returns returncode attribute.
 165
 166 communicate(input=None)
 167     Interact with process: Send data to stdin.  Read data from stdout
 168     and stderr, until end-of-file is reached.  Wait for process to
 169     terminate.  The optional stdin argument should be a string to be
 170     sent to the child process, or None, if no data should be sent to
 171     the child.
 172
 173     communicate() returns a tuple (stdout, stderr).
 174
 175     Note: The data read is buffered in memory, so do not use this
 176     method if the data size is large or unlimited.
 177
 178 The following attributes are also available:
 179
 180 stdin
 181     If the stdin argument is PIPE, this attribute is a file object
 182     that provides input to the child process.  Otherwise, it is None.
 183
 184 stdout
 185     If the stdout argument is PIPE, this attribute is a file object
 186     that provides output from the child process.  Otherwise, it is
 187     None.
 188
 189 stderr
 190     If the stderr argument is PIPE, this attribute is file object that
 191     provides error output from the child process.  Otherwise, it is
 192     None.
 193
 194 pid
 195     The process ID of the child process.
 196
 197 returncode
 198     The child return code.  A None value indicates that the process
 199     hasn't terminated yet.  A negative value -N indicates that the
 200     child was terminated by signal N (UNIX only).
 201
 202
 203 Replacing older functions with the subprocess module
 204 ====================================================
 205 In this section, "a ==> b" means that b can be used as a replacement
 206 for a.
 207
 208 Note: All functions in this section fail (more or less) silently if
 209 the executed program cannot be found; this module raises an OSError
 210 exception.
 211
 212 In the following examples, we assume that the subprocess module is
 213 imported with "from subprocess import *".
 214
 215
 216 Replacing /bin/sh shell backquote
 217 ---------------------------------
 218 output=`mycmd myarg`
 219 ==>
 220 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
 221
 222
 223 Replacing shell pipe line
 224 -------------------------
 225 output=`dmesg | grep hda`
 226 ==>
 227 p1 = Popen(["dmesg"], stdout=PIPE)
 228 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
 229 output = p2.communicate()[0]
 230
 231
 232 Replacing os.system()
 233 ---------------------
 234 sts = os.system("mycmd" + " myarg")
 235 ==>
 236 p = Popen("mycmd" + " myarg", shell=True)
 237 pid, sts = os.waitpid(p.pid, 0)
 238
 239 Note:
 240
 241 * Calling the program through the shell is usually not required.
 242
 243 * It's easier to look at the returncode attribute than the
 244   exitstatus.
 245
 246 A more real-world example would look like this:
 247
 248 try:
 249     retcode = call("mycmd" + " myarg", shell=True)
 250     if retcode < 0:
 251         print >>sys.stderr, "Child was terminated by signal", -retcode
 252     else:
 253         print >>sys.stderr, "Child returned", retcode
 254 except OSError, e:
 255     print >>sys.stderr, "Execution failed:", e
 256
 257
 258 Replacing os.spawn*
 259 -------------------
 260 P_NOWAIT example:
 261
 262 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
 263 ==>
 264 pid = Popen(["/bin/mycmd", "myarg"]).pid
 265
 266
 267 P_WAIT example:
 268
 269 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
 270 ==>
 271 retcode = call(["/bin/mycmd", "myarg"])
 272
 273
 274 Vector example:
 275
 276 os.spawnvp(os.P_NOWAIT, path, args)
 277 ==>
 278 Popen([path] + args[1:])
 279
 280
 281 Environment example:
 282
 283 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
 284 ==>
 285 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
 286
 287
 288 Replacing os.popen*
 289 -------------------
 290 pipe = os.popen(cmd, mode='r', bufsize)
 291 ==>
 292 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
 293
 294 pipe = os.popen(cmd, mode='w', bufsize)
 295 ==>
 296 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
 297
 298
 299 (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
 300 ==>
 301 p = Popen(cmd, shell=True, bufsize=bufsize,
 302           stdin=PIPE, stdout=PIPE, close_fds=True)
 303 (child_stdin, child_stdout) = (p.stdin, p.stdout)
 304
 305
 306 (child_stdin,
 307  child_stdout,
 308  child_stderr) = os.popen3(cmd, mode, bufsize)
 309 ==>
 310 p = Popen(cmd, shell=True, bufsize=bufsize,
 311           stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
 312 (child_stdin,
 313  child_stdout,
 314  child_stderr) = (p.stdin, p.stdout, p.stderr)
 315
 316
 317 (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
 318 ==>
 319 p = Popen(cmd, shell=True, bufsize=bufsize,
 320           stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
 321 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
 322
 323
 324 Replacing popen2.*
 325 ------------------
 326 Note: If the cmd argument to popen2 functions is a string, the command
 327 is executed through /bin/sh.  If it is a list, the command is directly
 328 executed.
 329
 330 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
 331 ==>
 332 p = Popen(["somestring"], shell=True, bufsize=bufsize
 333           stdin=PIPE, stdout=PIPE, close_fds=True)
 334 (child_stdout, child_stdin) = (p.stdout, p.stdin)
 335
 336
 337 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
 338 ==>
 339 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
 340           stdin=PIPE, stdout=PIPE, close_fds=True)
 341 (child_stdout, child_stdin) = (p.stdout, p.stdin)
 342
 343 The popen2.Popen3 and popen3.Popen4 basically works as subprocess.Popen,
 344 except that:
 345
 346 * subprocess.Popen raises an exception if the execution fails
 347 * the capturestderr argument is replaced with the stderr argument.
 348 * stdin=PIPE and stdout=PIPE must be specified.
 349 * popen2 closes all filedescriptors by default, but you have to specify
 350   close_fds=True with subprocess.Popen.
 351
 352
 353 """
 354
 355 import sys
 356 mswindows = (sys.platform == "win32")
 357
 358 import os
 359 import types
 360 import traceback
 361
 362 # Exception classes used by this module.
 363 class CalledProcessError(Exception):
 364     """This exception is raised when a process run by check_call() returns
 365     a non-zero exit status.  The exit status will be stored in the
 366     returncode attribute."""
 367     def __init__(self, returncode, cmd):
 368         self.returncode = returncode
 369         self.cmd = cmd
 370     def __str__(self):
 371         return "Command '%s' returned non-zero exit status %d" % (self.cmd, self.returncode)
 372
 373
 374 if mswindows:
 375     try:
 376         import threading
 377     except ImportError:
 378         # SCons:  the threading module is only used by the communicate()
 379         # method, which we don't actually use, so don't worry if we
 380         # can't import it.
 381         pass
 382     import msvcrt
 383     try:
 384         # Try to get _subprocess
 385         from _subprocess import *
 386         class STARTUPINFO:
 387             dwFlags = 0
 388             hStdInput = None
 389             hStdOutput = None
 390             hStdError = None
 391             wShowWindow = 0
 392         class pywintypes:
 393             error = IOError
 394     except ImportError:
 395         # If not there, then drop back to requiring pywin32
 396         # TODO: Should this be wrapped in try as well? To notify user to install
 397         #       pywin32 ? With URL to it?
 398         import pywintypes
 399         from win32api import GetStdHandle, STD_INPUT_HANDLE, \
 400                              STD_OUTPUT_HANDLE, STD_ERROR_HANDLE
 401         from win32api import GetCurrentProcess, DuplicateHandle, \
 402                              GetModuleFileName, GetVersion
 403         from win32con import DUPLICATE_SAME_ACCESS, SW_HIDE
 404         from win32pipe import CreatePipe
 405         from win32process import CreateProcess, STARTUPINFO, \
 406                                  GetExitCodeProcess, STARTF_USESTDHANDLES, \
 407                                  STARTF_USESHOWWINDOW, CREATE_NEW_CONSOLE
 408         from win32event import WaitForSingleObject, INFINITE, WAIT_OBJECT_0
 409
 410
 411 else:
 412     import select
 413     import errno
 414     import fcntl
 415     import pickle
 416
 417     try:
 418         fcntl.F_GETFD
 419     except AttributeError:
 420         fcntl.F_GETFD = 1
 421
 422     try:
 423         fcntl.F_SETFD
 424     except AttributeError:
 425         fcntl.F_SETFD = 2
 426
 427 __all__ = ["Popen", "PIPE", "STDOUT", "call", "check_call", "CalledProcessError"]
 428
 429 try:
 430     MAXFD = os.sysconf("SC_OPEN_MAX")
 431 except KeyboardInterrupt:
 432     raise       # SCons:  don't swallow keyboard interrupts
 433 except:
 434     MAXFD = 256
 435
 436 # True/False does not exist on 2.2.0
 437 try:
 438     False
 439 except NameError:
 440     False = 0
 441     True = 1
 442
 443 try:
 444     isinstance(1, int)
 445 except TypeError:
 446     def is_int(obj):
 447         return isinstance(obj, type(1))
 448     def is_int_or_long(obj):
 449         return type(obj) in (type(1), type(1L))
 450 else:
 451     def is_int(obj):
 452         return isinstance(obj, int)
 453     def is_int_or_long(obj):
 454         return isinstance(obj, (int, long))
 455
 456 try:
 457     types.StringTypes
 458 except AttributeError:
 459     try:
 460         types.StringTypes = (str, unicode)
 461     except AttributeError:
 462         types.StringTypes = (str,)
 463     def is_string(obj):
 464         return type(obj) in types.StringTypes
 465 else:
 466     def is_string(obj):
 467         return isinstance(obj, types.StringTypes)
 468
 469 _active = []
 470
 471 def _cleanup():
 472     for inst in _active[:]:
 473         if inst.poll(_deadstate=sys.maxsize) >= 0:
 474             try:
 475                 _active.remove(inst)
 476             except ValueError:
 477                 # This can happen if two threads create a new Popen instance.
 478                 # It's harmless that it was already removed, so ignore.
 479                 pass
 480
 481 PIPE = -1
 482 STDOUT = -2
 483
 484
 485 def call(*popenargs, **kwargs):
 486     """Run command with arguments.  Wait for command to complete, then
 487     return the returncode attribute.
 488
 489     The arguments are the same as for the Popen constructor.  Example:
 490
 491     retcode = call(["ls", "-l"])
 492     """
 493     return apply(Popen, popenargs, kwargs).wait()
 494
 495
 496 def check_call(*popenargs, **kwargs):
 497     """Run command with arguments.  Wait for command to complete.  If
 498     the exit code was zero then return, otherwise raise
 499     CalledProcessError.  The CalledProcessError object will have the
 500     return code in the returncode attribute.
 501
 502     The arguments are the same as for the Popen constructor.  Example:
 503
 504     check_call(["ls", "-l"])
 505     """
 506     retcode = call(*popenargs, **kwargs)
 507     cmd = kwargs.get("args")
 508     if cmd is None:
 509         cmd = popenargs[0]
 510     if retcode:
 511         raise CalledProcessError(retcode, cmd)
 512     return retcode
 513
 514
 515 def list2cmdline(seq):
 516     """
 517     Translate a sequence of arguments into a command line
 518     string, using the same rules as the MS C runtime:
 519
 520     1) Arguments are delimited by white space, which is either a
 521        space or a tab.
 522
 523     2) A string surrounded by double quotation marks is
 524        interpreted as a single argument, regardless of white space
 525        contained within.  A quoted string can be embedded in an
 526        argument.
 527
 528     3) A double quotation mark preceded by a backslash is
 529        interpreted as a literal double quotation mark.
 530
 531     4) Backslashes are interpreted literally, unless they
 532        immediately precede a double quotation mark.
 533
 534     5) If backslashes immediately precede a double quotation mark,
 535        every pair of backslashes is interpreted as a literal
 536        backslash.  If the number of backslashes is odd, the last
 537        backslash escapes the next double quotation mark as
 538        described in rule 3.
 539     """
 540
 541     # See
 542     # http://msdn.microsoft.com/library/en-us/vccelng/htm/progs_12.asp
 543     result = []
 544     needquote = False
 545     for arg in seq:
 546         bs_buf = []
 547
 548         # Add a space to separate this argument from the others
 549         if result:
 550             result.append(' ')
 551
 552         needquote = (" " in arg) or ("\t" in arg)
 553         if needquote:
 554             result.append('"')
 555
 556         for c in arg:
 557             if c == '\\':
 558                 # Don't know if we need to double yet.
 559                 bs_buf.append(c)
 560             elif c == '"':
 561                 # Double backspaces.
 562                 result.append('\\' * len(bs_buf)*2)
 563                 bs_buf = []
 564                 result.append('\\"')
 565             else:
 566                 # Normal char
 567                 if bs_buf:
 568                     result.extend(bs_buf)
 569                     bs_buf = []
 570                 result.append(c)
 571
 572         # Add remaining backspaces, if any.
 573         if bs_buf:
 574             result.extend(bs_buf)
 575
 576         if needquote:
 577             result.extend(bs_buf)
 578             result.append('"')
 579
 580     return ''.join(result)
 581
 582
 583 try:
 584     object
 585 except NameError:
 586     class object:
 587         pass
 588
 589 class Popen(object):
 590     def __init__(self, args, bufsize=0, executable=None,
 591                  stdin=None, stdout=None, stderr=None,
 592                  preexec_fn=None, close_fds=False, shell=False,
 593                  cwd=None, env=None, universal_newlines=False,
 594                  startupinfo=None, creationflags=0):
 595         """Create new Popen instance."""
 596         _cleanup()
 597
 598         self._child_created = False
 599         if not is_int_or_long(bufsize):
 600             raise TypeError("bufsize must be an integer")
 601
 602         if mswindows:
 603             if preexec_fn is not None:
 604                 raise ValueError("preexec_fn is not supported on Windows "
 605                                  "platforms")
 606             if close_fds:
 607                 raise ValueError("close_fds is not supported on Windows "
 608                                  "platforms")
 609         else:
 610             # POSIX
 611             if startupinfo is not None:
 612                 raise ValueError("startupinfo is only supported on Windows "
 613                                  "platforms")
 614             if creationflags != 0:
 615                 raise ValueError("creationflags is only supported on Windows "
 616                                  "platforms")
 617
 618         self.stdin = None
 619         self.stdout = None
 620         self.stderr = None
 621         self.pid = None
 622         self.returncode = None
 623         self.universal_newlines = universal_newlines
 624
 625         # Input and output objects. The general principle is like
 626         # this:
 627         #
 628         # Parent                   Child
 629         # ------                   -----
 630         # p2cwrite   ---stdin--->  p2cread
 631         # c2pread    <--stdout---  c2pwrite
 632         # errread    <--stderr---  errwrite
 633         #
 634         # On POSIX, the child objects are file descriptors.  On
 635         # Windows, these are Windows file handles.  The parent objects
 636         # are file descriptors on both platforms.  The parent objects
 637         # are None when not using PIPEs. The child objects are None
 638         # when not redirecting.
 639
 640         (p2cread, p2cwrite,
 641          c2pread, c2pwrite,
 642          errread, errwrite) = self._get_handles(stdin, stdout, stderr)
 643
 644         self._execute_child(args, executable, preexec_fn, close_fds,
 645                             cwd, env, universal_newlines,
 646                             startupinfo, creationflags, shell,
 647                             p2cread, p2cwrite,
 648                             c2pread, c2pwrite,
 649                             errread, errwrite)
 650
 651         if p2cwrite:
 652             self.stdin = os.fdopen(p2cwrite, 'wb', bufsize)
 653         if c2pread:
 654             if universal_newlines:
 655                 self.stdout = os.fdopen(c2pread, 'rU', bufsize)
 656             else:
 657                 self.stdout = os.fdopen(c2pread, 'rb', bufsize)
 658         if errread:
 659             if universal_newlines:
 660                 self.stderr = os.fdopen(errread, 'rU', bufsize)
 661             else:
 662                 self.stderr = os.fdopen(errread, 'rb', bufsize)
 663
 664
 665     def _translate_newlines(self, data):
 666         data = data.replace("\r\n", "\n")
 667         data = data.replace("\r", "\n")
 668         return data
 669
 670
 671     def __del__(self):
 672         if not self._child_created:
 673             # We didn't get to successfully create a child process.
 674             return
 675         # In case the child hasn't been waited on, check if it's done.
 676         self.poll(_deadstate=sys.maxsize)
 677         if self.returncode is None and _active is not None:
 678             # Child is still running, keep us alive until we can wait on it.
 679             _active.append(self)
 680
 681
 682     def communicate(self, input=None):
 683         """Interact with process: Send data to stdin.  Read data from
 684         stdout and stderr, until end-of-file is reached.  Wait for
 685         process to terminate.  The optional input argument should be a
 686         string to be sent to the child process, or None, if no data
 687         should be sent to the child.
 688
 689         communicate() returns a tuple (stdout, stderr)."""
 690
 691         # Optimization: If we are only using one pipe, or no pipe at
 692         # all, using select() or threads is unnecessary.
 693         if [self.stdin, self.stdout, self.stderr].count(None) >= 2:
 694             stdout = None
 695             stderr = None
 696             if self.stdin:
 697                 if input:
 698                     self.stdin.write(input)
 699                 self.stdin.close()
 700             elif self.stdout:
 701                 stdout = self.stdout.read()
 702             elif self.stderr:
 703                 stderr = self.stderr.read()
 704             self.wait()
 705             return (stdout, stderr)
 706
 707         return self._communicate(input)
 708
 709
 710     if mswindows:
 711         #
 712         # Windows methods
 713         #
 714         def _get_handles(self, stdin, stdout, stderr):
 715             """Construct and return tupel with IO objects:
 716             p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
 717             """
 718             if stdin is None and stdout is None and stderr is None:
 719                 return (None, None, None, None, None, None)
 720
 721             p2cread, p2cwrite = None, None
 722             c2pread, c2pwrite = None, None
 723             errread, errwrite = None, None
 724
 725             if stdin is None:
 726                 p2cread = GetStdHandle(STD_INPUT_HANDLE)
 727             elif stdin == PIPE:
 728                 p2cread, p2cwrite = CreatePipe(None, 0)
 729                 # Detach and turn into fd
 730                 p2cwrite = p2cwrite.Detach()
 731                 p2cwrite = msvcrt.open_osfhandle(p2cwrite, 0)
 732             elif is_int(stdin):
 733                 p2cread = msvcrt.get_osfhandle(stdin)
 734             else:
 735                 # Assuming file-like object
 736                 p2cread = msvcrt.get_osfhandle(stdin.fileno())
 737             p2cread = self._make_inheritable(p2cread)
 738
 739             if stdout is None:
 740                 c2pwrite = GetStdHandle(STD_OUTPUT_HANDLE)
 741             elif stdout == PIPE:
 742                 c2pread, c2pwrite = CreatePipe(None, 0)
 743                 # Detach and turn into fd
 744                 c2pread = c2pread.Detach()
 745                 c2pread = msvcrt.open_osfhandle(c2pread, 0)
 746             elif is_int(stdout):
 747                 c2pwrite = msvcrt.get_osfhandle(stdout)
 748             else:
 749                 # Assuming file-like object
 750                 c2pwrite = msvcrt.get_osfhandle(stdout.fileno())
 751             c2pwrite = self._make_inheritable(c2pwrite)
 752
 753             if stderr is None:
 754                 errwrite = GetStdHandle(STD_ERROR_HANDLE)
 755             elif stderr == PIPE:
 756                 errread, errwrite = CreatePipe(None, 0)
 757                 # Detach and turn into fd
 758                 errread = errread.Detach()
 759                 errread = msvcrt.open_osfhandle(errread, 0)
 760             elif stderr == STDOUT:
 761                 errwrite = c2pwrite
 762             elif is_int(stderr):
 763                 errwrite = msvcrt.get_osfhandle(stderr)
 764             else:
 765                 # Assuming file-like object
 766                 errwrite = msvcrt.get_osfhandle(stderr.fileno())
 767             errwrite = self._make_inheritable(errwrite)
 768
 769             return (p2cread, p2cwrite,
 770                     c2pread, c2pwrite,
 771                     errread, errwrite)
 772
 773
 774         def _make_inheritable(self, handle):
 775             """Return a duplicate of handle, which is inheritable"""
 776             return DuplicateHandle(GetCurrentProcess(), handle,
 777                                    GetCurrentProcess(), 0, 1,
 778                                    DUPLICATE_SAME_ACCESS)
 779
 780
 781         def _find_w9xpopen(self):
 782             """Find and return absolut path to w9xpopen.exe"""
 783             w9xpopen = os.path.join(os.path.dirname(GetModuleFileName(0)),
 784                                     "w9xpopen.exe")
 785             if not os.path.exists(w9xpopen):
 786                 # Eeek - file-not-found - possibly an embedding
 787                 # situation - see if we can locate it in sys.exec_prefix
 788                 w9xpopen = os.path.join(os.path.dirname(sys.exec_prefix),
 789                                         "w9xpopen.exe")
 790                 if not os.path.exists(w9xpopen):
 791                     raise RuntimeError("Cannot locate w9xpopen.exe, which is "
 792                                        "needed for Popen to work with your "
 793                                        "shell or platform.")
 794             return w9xpopen
 795
 796
 797         def _execute_child(self, args, executable, preexec_fn, close_fds,
 798                            cwd, env, universal_newlines,
 799                            startupinfo, creationflags, shell,
 800                            p2cread, p2cwrite,
 801                            c2pread, c2pwrite,
 802                            errread, errwrite):
 803             """Execute program (MS Windows version)"""
 804
 805             if not isinstance(args, types.StringTypes):
 806                 args = list2cmdline(args)
 807
 808             # Process startup details
 809             if startupinfo is None:
 810                 startupinfo = STARTUPINFO()
 811             if None not in (p2cread, c2pwrite, errwrite):
 812                 startupinfo.dwFlags = startupinfo.dwFlags | STARTF_USESTDHANDLES
 813                 startupinfo.hStdInput = p2cread
 814                 startupinfo.hStdOutput = c2pwrite
 815                 startupinfo.hStdError = errwrite
 816
 817             if shell:
 818                 startupinfo.dwFlags = startupinfo.dwFlags | STARTF_USESHOWWINDOW
 819                 startupinfo.wShowWindow = SW_HIDE
 820                 comspec = os.environ.get("COMSPEC", "cmd.exe")
 821                 args = comspec + " /c " + args
 822                 if (GetVersion() >= 0x80000000 or
 823                         os.path.basename(comspec).lower() == "command.com"):
 824                     # Win9x, or using command.com on NT. We need to
 825                     # use the w9xpopen intermediate program. For more
 826                     # information, see KB Q150956
 827                     # (http://web.archive.org/web/20011105084002/http://support.microsoft.com/support/kb/articles/Q150/9/56.asp)
 828                     w9xpopen = self._find_w9xpopen()
 829                     args = '"%s" %s' % (w9xpopen, args)
 830                     # Not passing CREATE_NEW_CONSOLE has been known to
 831                     # cause random failures on win9x.  Specifically a
 832                     # dialog: "Your program accessed mem currently in
 833                     # use at xxx" and a hopeful warning about the
 834                     # stability of your system.  Cost is Ctrl+C wont
 835                     # kill children.
 836                     creationflags = creationflags | CREATE_NEW_CONSOLE
 837
 838             # Start the process
 839             try:
 840                 hp, ht, pid, tid = CreateProcess(executable, args,
 841                                          # no special security
 842                                          None, None,
 843                                          # must inherit handles to pass std
 844                                          # handles
 845                                          1,
 846                                          creationflags,
 847                                          env,
 848                                          cwd,
 849                                          startupinfo)
 850             except pywintypes.error, e:
 851                 # Translate pywintypes.error to WindowsError, which is
 852                 # a subclass of OSError.  FIXME: We should really
 853                 # translate errno using _sys_errlist (or simliar), but
 854                 # how can this be done from Python?
 855                 raise WindowsError(*e.args)
 856
 857             # Retain the process handle, but close the thread handle
 858             self._child_created = True
 859             self._handle = hp
 860             self.pid = pid
 861             ht.Close()
 862
 863             # Child is launched. Close the parent's copy of those pipe
 864             # handles that only the child should have open.  You need
 865             # to make sure that no handles to the write end of the
 866             # output pipe are maintained in this process or else the
 867             # pipe will not close when the child process exits and the
 868             # ReadFile will hang.
 869             if p2cread is not None:
 870                 p2cread.Close()
 871             if c2pwrite is not None:
 872                 c2pwrite.Close()
 873             if errwrite is not None:
 874                 errwrite.Close()
 875
 876
 877         def poll(self, _deadstate=None):
 878             """Check if child process has terminated.  Returns returncode
 879             attribute."""
 880             if self.returncode is None:
 881                 if WaitForSingleObject(self._handle, 0) == WAIT_OBJECT_0:
 882                     self.returncode = GetExitCodeProcess(self._handle)
 883             return self.returncode
 884
 885
 886         def wait(self):
 887             """Wait for child process to terminate.  Returns returncode
 888             attribute."""
 889             if self.returncode is None:
 890                 obj = WaitForSingleObject(self._handle, INFINITE)
 891                 self.returncode = GetExitCodeProcess(self._handle)
 892             return self.returncode
 893
 894
 895         def _readerthread(self, fh, buffer):
 896             buffer.append(fh.read())
 897
 898
 899         def _communicate(self, input):
 900             stdout = None # Return
 901             stderr = None # Return
 902
 903             if self.stdout:
 904                 stdout = []
 905                 stdout_thread = threading.Thread(target=self._readerthread,
 906                                                  args=(self.stdout, stdout))
 907                 stdout_thread.setDaemon(True)
 908                 stdout_thread.start()
 909             if self.stderr:
 910                 stderr = []
 911                 stderr_thread = threading.Thread(target=self._readerthread,
 912                                                  args=(self.stderr, stderr))
 913                 stderr_thread.setDaemon(True)
 914                 stderr_thread.start()
 915
 916             if self.stdin:
 917                 if input is not None:
 918                     self.stdin.write(input)
 919                 self.stdin.close()
 920
 921             if self.stdout:
 922                 stdout_thread.join()
 923             if self.stderr:
 924                 stderr_thread.join()
 925
 926             # All data exchanged.  Translate lists into strings.
 927             if stdout is not None:
 928                 stdout = stdout[0]
 929             if stderr is not None:
 930                 stderr = stderr[0]
 931
 932             # Translate newlines, if requested.  We cannot let the file
 933             # object do the translation: It is based on stdio, which is
 934             # impossible to combine with select (unless forcing no
 935             # buffering).
 936             if self.universal_newlines and hasattr(file, 'newlines'):
 937                 if stdout:
 938                     stdout = self._translate_newlines(stdout)
 939                 if stderr:
 940                     stderr = self._translate_newlines(stderr)
 941
 942             self.wait()
 943             return (stdout, stderr)
 944
 945     else:
 946         #
 947         # POSIX methods
 948         #
 949         def _get_handles(self, stdin, stdout, stderr):
 950             """Construct and return tupel with IO objects:
 951             p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
 952             """
 953             p2cread, p2cwrite = None, None
 954             c2pread, c2pwrite = None, None
 955             errread, errwrite = None, None
 956
 957             if stdin is None:
 958                 pass
 959             elif stdin == PIPE:
 960                 p2cread, p2cwrite = os.pipe()
 961             elif is_int(stdin):
 962                 p2cread = stdin
 963             else:
 964                 # Assuming file-like object
 965                 p2cread = stdin.fileno()
 966
 967             if stdout is None:
 968                 pass
 969             elif stdout == PIPE:
 970                 c2pread, c2pwrite = os.pipe()
 971             elif is_int(stdout):
 972                 c2pwrite = stdout
 973             else:
 974                 # Assuming file-like object
 975                 c2pwrite = stdout.fileno()
 976
 977             if stderr is None:
 978                 pass
 979             elif stderr == PIPE:
 980                 errread, errwrite = os.pipe()
 981             elif stderr == STDOUT:
 982                 errwrite = c2pwrite
 983             elif is_int(stderr):
 984                 errwrite = stderr
 985             else:
 986                 # Assuming file-like object
 987                 errwrite = stderr.fileno()
 988
 989             return (p2cread, p2cwrite,
 990                     c2pread, c2pwrite,
 991                     errread, errwrite)
 992
 993
 994         def _set_cloexec_flag(self, fd):
 995             try:
 996                 cloexec_flag = fcntl.FD_CLOEXEC
 997             except AttributeError:
 998                 cloexec_flag = 1
 999
1000             old = fcntl.fcntl(fd, fcntl.F_GETFD)
1001             fcntl.fcntl(fd, fcntl.F_SETFD, old | cloexec_flag)
1002
1003
1004         def _close_fds(self, but):
1005             for i in xrange(3, MAXFD):
1006                 if i == but:
1007                     continue
1008                 try:
1009                     os.close(i)
1010                 except KeyboardInterrupt:
1011                     raise       # SCons:  don't swallow keyboard interrupts
1012                 except:
1013                     pass
1014
1015
1016         def _execute_child(self, args, executable, preexec_fn, close_fds,
1017                            cwd, env, universal_newlines,
1018                            startupinfo, creationflags, shell,
1019                            p2cread, p2cwrite,
1020                            c2pread, c2pwrite,
1021                            errread, errwrite):
1022             """Execute program (POSIX version)"""
1023
1024             if is_string(args):
1025                 args = [args]
1026
1027             if shell:
1028                 args = ["/bin/sh", "-c"] + args
1029
1030             if executable is None:
1031                 executable = args[0]
1032
1033             # For transferring possible exec failure from child to parent
1034             # The first char specifies the exception type: 0 means
1035             # OSError, 1 means some other error.
1036             errpipe_read, errpipe_write = os.pipe()
1037             self._set_cloexec_flag(errpipe_write)
1038
1039             self.pid = os.fork()
1040             self._child_created = True
1041             if self.pid == 0:
1042                 # Child
1043                 try:
1044                     # Close parent's pipe ends
1045                     if p2cwrite:
1046                         os.close(p2cwrite)
1047                     if c2pread:
1048                         os.close(c2pread)
1049                     if errread:
1050                         os.close(errread)
1051                     os.close(errpipe_read)
1052
1053                     # Dup fds for child
1054                     if p2cread:
1055                         os.dup2(p2cread, 0)
1056                     if c2pwrite:
1057                         os.dup2(c2pwrite, 1)
1058                     if errwrite:
1059                         os.dup2(errwrite, 2)
1060
1061                     # Close pipe fds.  Make sure we don't close the same
1062                     # fd more than once, or standard fds.
1063                     try:
1064                         set
1065                     except NameError:
1066                         # Fall-back for earlier Python versions, so epydoc
1067                         # can use this module directly to execute things.
1068                         if p2cread:
1069                             os.close(p2cread)
1070                         if c2pwrite and c2pwrite not in (p2cread,):
1071                             os.close(c2pwrite)
1072                         if errwrite and errwrite not in (p2cread, c2pwrite):
1073                             os.close(errwrite)
1074                     else:
1075                         for fd in set((p2cread, c2pwrite, errwrite))-set((0,1,2)):
1076                             if fd: os.close(fd)
1077
1078                     # Close all other fds, if asked for
1079                     if close_fds:
1080                         self._close_fds(but=errpipe_write)
1081
1082                     if cwd is not None:
1083                         os.chdir(cwd)
1084
1085                     if preexec_fn:
1086                         apply(preexec_fn)
1087
1088                     if env is None:
1089                         os.execvp(executable, args)
1090                     else:
1091                         os.execvpe(executable, args, env)
1092
1093                 except KeyboardInterrupt:
1094                     raise       # SCons:  don't swallow keyboard interrupts
1095
1096                 except:
1097                     exc_type, exc_value, tb = sys.exc_info()
1098                     # Save the traceback and attach it to the exception object
1099                     exc_lines = traceback.format_exception(exc_type,
1100                                                            exc_value,
1101                                                            tb)
1102                     exc_value.child_traceback = ''.join(exc_lines)
1103                     os.write(errpipe_write, pickle.dumps(exc_value))
1104
1105                 # This exitcode won't be reported to applications, so it
1106                 # really doesn't matter what we return.
1107                 os._exit(255)
1108
1109             # Parent
1110             os.close(errpipe_write)
1111             if p2cread and p2cwrite:
1112                 os.close(p2cread)
1113             if c2pwrite and c2pread:
1114                 os.close(c2pwrite)
1115             if errwrite and errread:
1116                 os.close(errwrite)
1117
1118             # Wait for exec to fail or succeed; possibly raising exception
1119             data = os.read(errpipe_read, 1048576) # Exceptions limited to 1 MB
1120             os.close(errpipe_read)
1121             if data != "":
1122                 os.waitpid(self.pid, 0)
1123                 child_exception = pickle.loads(data)
1124                 raise child_exception
1125
1126
1127         def _handle_exitstatus(self, sts):
1128             if os.WIFSIGNALED(sts):
1129                 self.returncode = -os.WTERMSIG(sts)
1130             elif os.WIFEXITED(sts):
1131                 self.returncode = os.WEXITSTATUS(sts)
1132             else:
1133                 # Should never happen
1134                 raise RuntimeError("Unknown child exit status!")
1135
1136
1137         def poll(self, _deadstate=None):
1138             """Check if child process has terminated.  Returns returncode
1139             attribute."""
1140             if self.returncode is None:
1141                 try:
1142                     pid, sts = os.waitpid(self.pid, os.WNOHANG)
1143                     if pid == self.pid:
1144                         self._handle_exitstatus(sts)
1145                 except os.error:
1146                     if _deadstate is not None:
1147                         self.returncode = _deadstate
1148             return self.returncode
1149
1150
1151         def wait(self):
1152             """Wait for child process to terminate.  Returns returncode
1153             attribute."""
1154             if self.returncode is None:
1155                 pid, sts = os.waitpid(self.pid, 0)
1156                 self._handle_exitstatus(sts)
1157             return self.returncode
1158
1159
1160         def _communicate(self, input):
1161             read_set = []
1162             write_set = []
1163             stdout = None # Return
1164             stderr = None # Return
1165
1166             if self.stdin:
1167                 # Flush stdio buffer.  This might block, if the user has
1168                 # been writing to .stdin in an uncontrolled fashion.
1169                 self.stdin.flush()
1170                 if input:
1171                     write_set.append(self.stdin)
1172                 else:
1173                     self.stdin.close()
1174             if self.stdout:
1175                 read_set.append(self.stdout)
1176                 stdout = []
1177             if self.stderr:
1178                 read_set.append(self.stderr)
1179                 stderr = []
1180
1181             input_offset = 0
1182             while read_set or write_set:
1183                 rlist, wlist, xlist = select.select(read_set, write_set, [])
1184
1185                 if self.stdin in wlist:
1186                     # When select has indicated that the file is writable,
1187                     # we can write up to PIPE_BUF bytes without risk
1188                     # blocking.  POSIX defines PIPE_BUF >= 512
1189                     bytes_written = os.write(self.stdin.fileno(), buffer(input, input_offset, 512))
1190                     input_offset = input_offset + bytes_written
1191                     if input_offset >= len(input):
1192                         self.stdin.close()
1193                         write_set.remove(self.stdin)
1194
1195                 if self.stdout in rlist:
1196                     data = os.read(self.stdout.fileno(), 1024)
1197                     if data == "":
1198                         self.stdout.close()
1199                         read_set.remove(self.stdout)
1200                     stdout.append(data)
1201
1202                 if self.stderr in rlist:
1203                     data = os.read(self.stderr.fileno(), 1024)
1204                     if data == "":
1205                         self.stderr.close()
1206                         read_set.remove(self.stderr)
1207                     stderr.append(data)
1208
1209             # All data exchanged.  Translate lists into strings.
1210             if stdout is not None:
1211                 stdout = ''.join(stdout)
1212             if stderr is not None:
1213                 stderr = ''.join(stderr)
1214
1215             # Translate newlines, if requested.  We cannot let the file
1216             # object do the translation: It is based on stdio, which is
1217             # impossible to combine with select (unless forcing no
1218             # buffering).
1219             if self.universal_newlines and hasattr(file, 'newlines'):
1220                 if stdout:
1221                     stdout = self._translate_newlines(stdout)
1222                 if stderr:
1223                     stderr = self._translate_newlines(stderr)
1224
1225             self.wait()
1226             return (stdout, stderr)
1227
1228
1229 def _demo_posix():
1230     #
1231     # Example 1: Simple redirection: Get process list
1232     #
1233     plist = Popen(["ps"], stdout=PIPE).communicate()[0]
1234     print "Process list:"
1235     print plist
1236
1237     #
1238     # Example 2: Change uid before executing child
1239     #
1240     if os.getuid() == 0:
1241         p = Popen(["id"], preexec_fn=lambda: os.setuid(100))
1242         p.wait()
1243
1244     #
1245     # Example 3: Connecting several subprocesses
1246     #
1247     print "Looking for 'hda'..."
1248     p1 = Popen(["dmesg"], stdout=PIPE)
1249     p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
1250     print repr(p2.communicate()[0])
1251
1252     #
1253     # Example 4: Catch execution error
1254     #
1255     print
1256     print "Trying a weird file..."
1257     try:
1258         print Popen(["/this/path/does/not/exist"]).communicate()
1259     except OSError, e:
1260         if e.errno == errno.ENOENT:
1261             print "The file didn't exist.  I thought so..."
1262             print "Child traceback:"
1263             print e.child_traceback
1264         else:
1265             print "Error", e.errno
1266     else:
1267         sys.stderr.write( "Gosh.  No error.\n" )
1268
1269
1270 def _demo_windows():
1271     #
1272     # Example 1: Connecting several subprocesses
1273     #
1274     print "Looking for 'PROMPT' in set output..."
1275     p1 = Popen("set", stdout=PIPE, shell=True)
1276     p2 = Popen('find "PROMPT"', stdin=p1.stdout, stdout=PIPE)
1277     print repr(p2.communicate()[0])
1278
1279     #
1280     # Example 2: Simple execution of program
1281     #
1282     print "Executing calc..."
1283     p = Popen("calc")
1284     p.wait()
1285
1286
1287 if __name__ == "__main__":
1288     if mswindows:
1289         _demo_windows()
1290     else:
1291         _demo_posix()
1292
1293 # Local Variables:
1294 # tab-width:4
1295 # indent-tabs-mode:nil
1296 # End:
1297 # vim: set expandtab tabstop=4 shiftwidth=4: