compat/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(*args, **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
 121 Exceptions
 122 ----------
 123 Exceptions raised in the child process, before the new program has
 124 started to execute, will be re-raised in the parent.  Additionally,
 125 the exception object will have one extra attribute called
 126 'child_traceback', which is a string containing traceback information
 127 from the childs point of view.
 128
 129 The most common exception raised is OSError.  This occurs, for
 130 example, when trying to execute a non-existent file.  Applications
 131 should prepare for OSErrors.
 132
 133 A ValueError will be raised if Popen is called with invalid arguments.
 134
 135
 136 Security
 137 --------
 138 Unlike some other popen functions, this implementation will never call
 139 /bin/sh implicitly.  This means that all characters, including shell
 140 metacharacters, can safely be passed to child processes.
 141
 142
 143 Popen objects
 144 =============
 145 Instances of the Popen class have the following methods:
 146
 147 poll()
 148     Check if child process has terminated.  Returns returncode
 149     attribute.
 150
 151 wait()
 152     Wait for child process to terminate.  Returns returncode attribute.
 153
 154 communicate(input=None)
 155     Interact with process: Send data to stdin.  Read data from stdout
 156     and stderr, until end-of-file is reached.  Wait for process to
 157     terminate.  The optional stdin argument should be a string to be
 158     sent to the child process, or None, if no data should be sent to
 159     the child.
 160
 161     communicate() returns a tuple (stdout, stderr).
 162
 163     Note: The data read is buffered in memory, so do not use this
 164     method if the data size is large or unlimited.
 165
 166 The following attributes are also available:
 167
 168 stdin
 169     If the stdin argument is PIPE, this attribute is a file object
 170     that provides input to the child process.  Otherwise, it is None.
 171
 172 stdout
 173     If the stdout argument is PIPE, this attribute is a file object
 174     that provides output from the child process.  Otherwise, it is
 175     None.
 176
 177 stderr
 178     If the stderr argument is PIPE, this attribute is file object that
 179     provides error output from the child process.  Otherwise, it is
 180     None.
 181
 182 pid
 183     The process ID of the child process.
 184
 185 returncode
 186     The child return code.  A None value indicates that the process
 187     hasn't terminated yet.  A negative value -N indicates that the
 188     child was terminated by signal N (UNIX only).
 189
 190
 191 Replacing older functions with the subprocess module
 192 ====================================================
 193 In this section, "a ==> b" means that b can be used as a replacement
 194 for a.
 195
 196 Note: All functions in this section fail (more or less) silently if
 197 the executed program cannot be found; this module raises an OSError
 198 exception.
 199
 200 In the following examples, we assume that the subprocess module is
 201 imported with "from subprocess import *".
 202
 203
 204 Replacing /bin/sh shell backquote
 205 ---------------------------------
 206 output=`mycmd myarg`
 207 ==>
 208 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
 209
 210
 211 Replacing shell pipe line
 212 -------------------------
 213 output=`dmesg | grep hda`
 214 ==>
 215 p1 = Popen(["dmesg"], stdout=PIPE)
 216 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
 217 output = p2.communicate()[0]
 218
 219
 220 Replacing os.system()
 221 ---------------------
 222 sts = os.system("mycmd" + " myarg")
 223 ==>
 224 p = Popen("mycmd" + " myarg", shell=True)
 225 sts = os.waitpid(p.pid, 0)
 226
 227 Note:
 228
 229 * Calling the program through the shell is usually not required.
 230
 231 * It's easier to look at the returncode attribute than the
 232   exitstatus.
 233
 234 A more real-world example would look like this:
 235
 236 try:
 237     retcode = call("mycmd" + " myarg", shell=True)
 238     if retcode < 0:
 239         print >>sys.stderr, "Child was terminated by signal", -retcode
 240     else:
 241         print >>sys.stderr, "Child returned", retcode
 242 except OSError, e:
 243     print >>sys.stderr, "Execution failed:", e
 244
 245
 246 Replacing os.spawn*
 247 -------------------
 248 P_NOWAIT example:
 249
 250 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
 251 ==>
 252 pid = Popen(["/bin/mycmd", "myarg"]).pid
 253
 254
 255 P_WAIT example:
 256
 257 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
 258 ==>
 259 retcode = call(["/bin/mycmd", "myarg"])
 260
 261
 262 Vector example:
 263
 264 os.spawnvp(os.P_NOWAIT, path, args)
 265 ==>
 266 Popen([path] + args[1:])
 267
 268
 269 Environment example:
 270
 271 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
 272 ==>
 273 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
 274
 275
 276 Replacing os.popen*
 277 -------------------
 278 pipe = os.popen(cmd, mode='r', bufsize)
 279 ==>
 280 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
 281
 282 pipe = os.popen(cmd, mode='w', bufsize)
 283 ==>
 284 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
 285
 286
 287 (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
 288 ==>
 289 p = Popen(cmd, shell=True, bufsize=bufsize,
 290           stdin=PIPE, stdout=PIPE, close_fds=True)
 291 (child_stdin, child_stdout) = (p.stdin, p.stdout)
 292
 293
 294 (child_stdin,
 295  child_stdout,
 296  child_stderr) = os.popen3(cmd, mode, bufsize)
 297 ==>
 298 p = Popen(cmd, shell=True, bufsize=bufsize,
 299           stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
 300 (child_stdin,
 301  child_stdout,
 302  child_stderr) = (p.stdin, p.stdout, p.stderr)
 303
 304
 305 (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
 306 ==>
 307 p = Popen(cmd, shell=True, bufsize=bufsize,
 308           stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
 309 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
 310
 311
 312 Replacing popen2.*
 313 ------------------
 314 Note: If the cmd argument to popen2 functions is a string, the command
 315 is executed through /bin/sh.  If it is a list, the command is directly
 316 executed.
 317
 318 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
 319 ==>
 320 p = Popen(["somestring"], shell=True, bufsize=bufsize
 321           stdin=PIPE, stdout=PIPE, close_fds=True)
 322 (child_stdout, child_stdin) = (p.stdout, p.stdin)
 323
 324
 325 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
 326 ==>
 327 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
 328           stdin=PIPE, stdout=PIPE, close_fds=True)
 329 (child_stdout, child_stdin) = (p.stdout, p.stdin)
 330
 331 The popen2.Popen3 and popen3.Popen4 basically works as subprocess.Popen,
 332 except that:
 333
 334 * subprocess.Popen raises an exception if the execution fails
 335 * the capturestderr argument is replaced with the stderr argument.
 336 * stdin=PIPE and stdout=PIPE must be specified.
 337 * popen2 closes all filedescriptors by default, but you have to specify
 338   close_fds=True with subprocess.Popen.
 339
 340
 341 """
 342
 343 import sys
 344 mswindows = (sys.platform == "win32")
 345
 346 import os
 347 import types
 348 import traceback
 349
 350 if mswindows:
 351     import threading
 352     import msvcrt
 353     if 0: # <-- change this to use pywin32 instead of the _subprocess driver
 354         import pywintypes
 355         from win32api import GetStdHandle, STD_INPUT_HANDLE, \
 356                              STD_OUTPUT_HANDLE, STD_ERROR_HANDLE
 357         from win32api import GetCurrentProcess, DuplicateHandle, \
 358                              GetModuleFileName, GetVersion
 359         from win32con import DUPLICATE_SAME_ACCESS, SW_HIDE
 360         from win32pipe import CreatePipe
 361         from win32process import CreateProcess, STARTUPINFO, \
 362                                  GetExitCodeProcess, STARTF_USESTDHANDLES, \
 363                                  STARTF_USESHOWWINDOW, CREATE_NEW_CONSOLE
 364         from win32event import WaitForSingleObject, INFINITE, WAIT_OBJECT_0
 365     else:
 366         from _subprocess import *
 367         class STARTUPINFO:
 368             dwFlags = 0
 369             hStdInput = None
 370             hStdOutput = None
 371             hStdError = None
 372         class pywintypes:
 373             error = IOError
 374 else:
 375     import select
 376     import errno
 377     import fcntl
 378     import pickle
 379
 380 __all__ = ["Popen", "PIPE", "STDOUT", "call"]
 381
 382 try:
 383     MAXFD = os.sysconf("SC_OPEN_MAX")
 384 except:
 385     MAXFD = 256
 386
 387 # True/False does not exist on 2.2.0
 388 try:
 389     False
 390 except NameError:
 391     False = 0
 392     True = 1
 393
 394 _active = []
 395
 396 def _cleanup():
 397     for inst in _active[:]:
 398         inst.poll()
 399
 400 PIPE = -1
 401 STDOUT = -2
 402
 403
 404 def call(*args, **kwargs):
 405     """Run command with arguments.  Wait for command to complete, then
 406     return the returncode attribute.
 407
 408     The arguments are the same as for the Popen constructor.  Example:
 409
 410     retcode = call(["ls", "-l"])
 411     """
 412     return Popen(*args, **kwargs).wait()
 413
 414
 415 def list2cmdline(seq):
 416     """
 417     Translate a sequence of arguments into a command line
 418     string, using the same rules as the MS C runtime:
 419
 420     1) Arguments are delimited by white space, which is either a
 421        space or a tab.
 422
 423     2) A string surrounded by double quotation marks is
 424        interpreted as a single argument, regardless of white space
 425        contained within.  A quoted string can be embedded in an
 426        argument.
 427
 428     3) A double quotation mark preceded by a backslash is
 429        interpreted as a literal double quotation mark.
 430
 431     4) Backslashes are interpreted literally, unless they
 432        immediately precede a double quotation mark.
 433
 434     5) If backslashes immediately precede a double quotation mark,
 435        every pair of backslashes is interpreted as a literal
 436        backslash.  If the number of backslashes is odd, the last
 437        backslash escapes the next double quotation mark as
 438        described in rule 3.
 439     """
 440
 441     # See
 442     # http://msdn.microsoft.com/library/en-us/vccelng/htm/progs_12.asp
 443     result = []
 444     needquote = False
 445     for arg in seq:
 446         bs_buf = []
 447
 448         # Add a space to separate this argument from the others
 449         if result:
 450             result.append(' ')
 451
 452         needquote = (" " in arg) or ("\t" in arg)
 453         if needquote:
 454             result.append('"')
 455
 456         for c in arg:
 457             if c == '\\':
 458                 # Don't know if we need to double yet.
 459                 bs_buf.append(c)
 460             elif c == '"':
 461                 # Double backspaces.
 462                 result.append('\\' * len(bs_buf)*2)
 463                 bs_buf = []
 464                 result.append('\\"')
 465             else:
 466                 # Normal char
 467                 if bs_buf:
 468                     result.extend(bs_buf)
 469                     bs_buf = []
 470                 result.append(c)
 471
 472         # Add remaining backspaces, if any.
 473         if bs_buf:
 474             result.extend(bs_buf)
 475
 476         if needquote:
 477             result.extend(bs_buf)
 478             result.append('"')
 479
 480     return ''.join(result)
 481
 482
 483 class Popen(object):
 484     def __init__(self, args, bufsize=0, executable=None,
 485                  stdin=None, stdout=None, stderr=None,
 486                  preexec_fn=None, close_fds=False, shell=False,
 487                  cwd=None, env=None, universal_newlines=False,
 488                  startupinfo=None, creationflags=0):
 489         """Create new Popen instance."""
 490         _cleanup()
 491
 492         if not isinstance(bufsize, (int, long)):
 493             raise TypeError("bufsize must be an integer")
 494
 495         if mswindows:
 496             if preexec_fn is not None:
 497                 raise ValueError("preexec_fn is not supported on Windows "
 498                                  "platforms")
 499             if close_fds:
 500                 raise ValueError("close_fds is not supported on Windows "
 501                                  "platforms")
 502         else:
 503             # POSIX
 504             if startupinfo is not None:
 505                 raise ValueError("startupinfo is only supported on Windows "
 506                                  "platforms")
 507             if creationflags != 0:
 508                 raise ValueError("creationflags is only supported on Windows "
 509                                  "platforms")
 510
 511         self.stdin = None
 512         self.stdout = None
 513         self.stderr = None
 514         self.pid = None
 515         self.returncode = None
 516         self.universal_newlines = universal_newlines
 517
 518         # Input and output objects. The general principle is like
 519         # this:
 520         #
 521         # Parent                   Child
 522         # ------                   -----
 523         # p2cwrite   ---stdin--->  p2cread
 524         # c2pread    <--stdout---  c2pwrite
 525         # errread    <--stderr---  errwrite
 526         #
 527         # On POSIX, the child objects are file descriptors.  On
 528         # Windows, these are Windows file handles.  The parent objects
 529         # are file descriptors on both platforms.  The parent objects
 530         # are None when not using PIPEs. The child objects are None
 531         # when not redirecting.
 532
 533         (p2cread, p2cwrite,
 534          c2pread, c2pwrite,
 535          errread, errwrite) = self._get_handles(stdin, stdout, stderr)
 536
 537         self._execute_child(args, executable, preexec_fn, close_fds,
 538                             cwd, env, universal_newlines,
 539                             startupinfo, creationflags, shell,
 540                             p2cread, p2cwrite,
 541                             c2pread, c2pwrite,
 542                             errread, errwrite)
 543
 544         if p2cwrite:
 545             self.stdin = os.fdopen(p2cwrite, 'wb', bufsize)
 546         if c2pread:
 547             if universal_newlines:
 548                 self.stdout = os.fdopen(c2pread, 'rU', bufsize)
 549             else:
 550                 self.stdout = os.fdopen(c2pread, 'rb', bufsize)
 551         if errread:
 552             if universal_newlines:
 553                 self.stderr = os.fdopen(errread, 'rU', bufsize)
 554             else:
 555                 self.stderr = os.fdopen(errread, 'rb', bufsize)
 556
 557         _active.append(self)
 558
 559
 560     def _translate_newlines(self, data):
 561         data = data.replace("\r\n", "\n")
 562         data = data.replace("\r", "\n")
 563         return data
 564
 565
 566     if mswindows:
 567         #
 568         # Windows methods
 569         #
 570         def _get_handles(self, stdin, stdout, stderr):
 571             """Construct and return tuple with IO objects:
 572             p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
 573             """
 574             if stdin == None and stdout == None and stderr == None:
 575                 return (None, None, None, None, None, None)
 576
 577             p2cread, p2cwrite = None, None
 578             c2pread, c2pwrite = None, None
 579             errread, errwrite = None, None
 580
 581             if stdin == None:
 582                 p2cread = GetStdHandle(STD_INPUT_HANDLE)
 583             elif stdin == PIPE:
 584                 p2cread, p2cwrite = CreatePipe(None, 0)
 585                 # Detach and turn into fd
 586                 p2cwrite = p2cwrite.Detach()
 587                 p2cwrite = msvcrt.open_osfhandle(p2cwrite, 0)
 588             elif type(stdin) == types.IntType:
 589                 p2cread = msvcrt.get_osfhandle(stdin)
 590             else:
 591                 # Assuming file-like object
 592                 p2cread = msvcrt.get_osfhandle(stdin.fileno())
 593             p2cread = self._make_inheritable(p2cread)
 594
 595             if stdout == None:
 596                 c2pwrite = GetStdHandle(STD_OUTPUT_HANDLE)
 597             elif stdout == PIPE:
 598                 c2pread, c2pwrite = CreatePipe(None, 0)
 599                 # Detach and turn into fd
 600                 c2pread = c2pread.Detach()
 601                 c2pread = msvcrt.open_osfhandle(c2pread, 0)
 602             elif type(stdout) == types.IntType:
 603                 c2pwrite = msvcrt.get_osfhandle(stdout)
 604             else:
 605                 # Assuming file-like object
 606                 c2pwrite = msvcrt.get_osfhandle(stdout.fileno())
 607             c2pwrite = self._make_inheritable(c2pwrite)
 608
 609             if stderr == None:
 610                 errwrite = GetStdHandle(STD_ERROR_HANDLE)
 611             elif stderr == PIPE:
 612                 errread, errwrite = CreatePipe(None, 0)
 613                 # Detach and turn into fd
 614                 errread = errread.Detach()
 615                 errread = msvcrt.open_osfhandle(errread, 0)
 616             elif stderr == STDOUT:
 617                 errwrite = c2pwrite
 618             elif type(stderr) == types.IntType:
 619                 errwrite = msvcrt.get_osfhandle(stderr)
 620             else:
 621                 # Assuming file-like object
 622                 errwrite = msvcrt.get_osfhandle(stderr.fileno())
 623             errwrite = self._make_inheritable(errwrite)
 624
 625             return (p2cread, p2cwrite,
 626                     c2pread, c2pwrite,
 627                     errread, errwrite)
 628
 629
 630         def _make_inheritable(self, handle):
 631             """Return a duplicate of handle, which is inheritable"""
 632             return DuplicateHandle(GetCurrentProcess(), handle,
 633                                    GetCurrentProcess(), 0, 1,
 634                                    DUPLICATE_SAME_ACCESS)
 635
 636
 637         def _find_w9xpopen(self):
 638             """Find and return absolute path to w9xpopen.exe"""
 639             w9xpopen = os.path.join(os.path.dirname(GetModuleFileName(0)),
 640                                     "w9xpopen.exe")
 641             if not os.path.exists(w9xpopen):
 642                 # Eeek - file-not-found - possibly an embedding
 643                 # situation - see if we can locate it in sys.exec_prefix
 644                 w9xpopen = os.path.join(os.path.dirname(sys.exec_prefix),
 645                                         "w9xpopen.exe")
 646                 if not os.path.exists(w9xpopen):
 647                     raise RuntimeError("Cannot locate w9xpopen.exe, which is "
 648                                        "needed for Popen to work with your "
 649                                        "shell or platform.")
 650             return w9xpopen
 651
 652
 653         def _execute_child(self, args, executable, preexec_fn, close_fds,
 654                            cwd, env, universal_newlines,
 655                            startupinfo, creationflags, shell,
 656                            p2cread, p2cwrite,
 657                            c2pread, c2pwrite,
 658                            errread, errwrite):
 659             """Execute program (MS Windows version)"""
 660
 661             if not isinstance(args, types.StringTypes):
 662                 args = list2cmdline(args)
 663
 664             # Process startup details
 665             default_startupinfo = STARTUPINFO()
 666             if startupinfo == None:
 667                 startupinfo = default_startupinfo
 668             if not None in (p2cread, c2pwrite, errwrite):
 669                 startupinfo.dwFlags |= STARTF_USESTDHANDLES
 670                 startupinfo.hStdInput = p2cread
 671                 startupinfo.hStdOutput = c2pwrite
 672                 startupinfo.hStdError = errwrite
 673
 674             if shell:
 675                 default_startupinfo.dwFlags |= STARTF_USESHOWWINDOW
 676                 default_startupinfo.wShowWindow = SW_HIDE
 677                 comspec = os.environ.get("COMSPEC", "cmd.exe")
 678                 args = comspec + " /c " + args
 679                 if (GetVersion() >= 0x80000000L or
 680                         os.path.basename(comspec).lower() == "command.com"):
 681                     # Win9x, or using command.com on NT. We need to
 682                     # use the w9xpopen intermediate program. For more
 683                     # information, see KB Q150956
 684                     # (http://web.archive.org/web/20011105084002/http://support.microsoft.com/support/kb/articles/Q150/9/56.asp)
 685                     w9xpopen = self._find_w9xpopen()
 686                     args = '"%s" %s' % (w9xpopen, args)
 687                     # Not passing CREATE_NEW_CONSOLE has been known to
 688                     # cause random failures on win9x.  Specifically a
 689                     # dialog: "Your program accessed mem currently in
 690                     # use at xxx" and a hopeful warning about the
 691                     # stability of your system.  Cost is Ctrl+C wont
 692                     # kill children.
 693                     creationflags |= CREATE_NEW_CONSOLE
 694
 695             # Start the process
 696             try:
 697                 hp, ht, pid, tid = CreateProcess(executable, args,
 698                                          # no special security
 699                                          None, None,
 700                                          # must inherit handles to pass std
 701                                          # handles
 702                                          1,
 703                                          creationflags,
 704                                          env,
 705                                          cwd,
 706                                          startupinfo)
 707             except pywintypes.error, e:
 708                 # Translate pywintypes.error to WindowsError, which is
 709                 # a subclass of OSError.  FIXME: We should really
 710                 # translate errno using _sys_errlist (or simliar), but
 711                 # how can this be done from Python?
 712                 raise WindowsError(*e.args)
 713
 714             # Retain the process handle, but close the thread handle
 715             self._handle = hp
 716             self.pid = pid
 717             ht.Close()
 718
 719             # Child is launched. Close the parent's copy of those pipe
 720             # handles that only the child should have open.  You need
 721             # to make sure that no handles to the write end of the
 722             # output pipe are maintained in this process or else the
 723             # pipe will not close when the child process exits and the
 724             # ReadFile will hang.
 725             if p2cread != None:
 726                 p2cread.Close()
 727             if c2pwrite != None:
 728                 c2pwrite.Close()
 729             if errwrite != None:
 730                 errwrite.Close()
 731
 732
 733         def poll(self):
 734             """Check if child process has terminated.  Returns returncode
 735             attribute."""
 736             if self.returncode == None:
 737                 if WaitForSingleObject(self._handle, 0) == WAIT_OBJECT_0:
 738                     self.returncode = GetExitCodeProcess(self._handle)
 739                     _active.remove(self)
 740             return self.returncode
 741
 742
 743         def wait(self):
 744             """Wait for child process to terminate.  Returns returncode
 745             attribute."""
 746             if self.returncode == None:
 747                 obj = WaitForSingleObject(self._handle, INFINITE)
 748                 self.returncode = GetExitCodeProcess(self._handle)
 749                 _active.remove(self)
 750             return self.returncode
 751
 752
 753         def _readerthread(self, fh, buffer):
 754             buffer.append(fh.read())
 755
 756
 757         def communicate(self, input=None):
 758             """Interact with process: Send data to stdin.  Read data from
 759             stdout and stderr, until end-of-file is reached.  Wait for
 760             process to terminate.  The optional input argument should be a
 761             string to be sent to the child process, or None, if no data
 762             should be sent to the child.
 763
 764             communicate() returns a tuple (stdout, stderr)."""
 765             stdout = None # Return
 766             stderr = None # Return
 767
 768             if self.stdout:
 769                 stdout = []
 770                 stdout_thread = threading.Thread(target=self._readerthread,
 771                                                  args=(self.stdout, stdout))
 772                 stdout_thread.setDaemon(True)
 773                 stdout_thread.start()
 774             if self.stderr:
 775                 stderr = []
 776                 stderr_thread = threading.Thread(target=self._readerthread,
 777                                                  args=(self.stderr, stderr))
 778                 stderr_thread.setDaemon(True)
 779                 stderr_thread.start()
 780
 781             if self.stdin:
 782                 if input != None:
 783                     self.stdin.write(input)
 784                 self.stdin.close()
 785
 786             if self.stdout:
 787                 stdout_thread.join()
 788             if self.stderr:
 789                 stderr_thread.join()
 790
 791             # All data exchanged.  Translate lists into strings.
 792             if stdout != None:
 793                 stdout = stdout[0]
 794             if stderr != None:
 795                 stderr = stderr[0]
 796
 797             # Translate newlines, if requested.  We cannot let the file
 798             # object do the translation: It is based on stdio, which is
 799             # impossible to combine with select (unless forcing no
 800             # buffering).
 801             if self.universal_newlines and hasattr(open, 'newlines'):
 802                 if stdout:
 803                     stdout = self._translate_newlines(stdout)
 804                 if stderr:
 805                     stderr = self._translate_newlines(stderr)
 806
 807             self.wait()
 808             return (stdout, stderr)
 809
 810     else:
 811         #
 812         # POSIX methods
 813         #
 814         def _get_handles(self, stdin, stdout, stderr):
 815             """Construct and return tuple with IO objects:
 816             p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite
 817             """
 818             p2cread, p2cwrite = None, None
 819             c2pread, c2pwrite = None, None
 820             errread, errwrite = None, None
 821
 822             if stdin == None:
 823                 pass
 824             elif stdin == PIPE:
 825                 p2cread, p2cwrite = os.pipe()
 826             elif type(stdin) == types.IntType:
 827                 p2cread = stdin
 828             else:
 829                 # Assuming file-like object
 830                 p2cread = stdin.fileno()
 831
 832             if stdout == None:
 833                 pass
 834             elif stdout == PIPE:
 835                 c2pread, c2pwrite = os.pipe()
 836             elif type(stdout) == types.IntType:
 837                 c2pwrite = stdout
 838             else:
 839                 # Assuming file-like object
 840                 c2pwrite = stdout.fileno()
 841
 842             if stderr == None:
 843                 pass
 844             elif stderr == PIPE:
 845                 errread, errwrite = os.pipe()
 846             elif stderr == STDOUT:
 847                 errwrite = c2pwrite
 848             elif type(stderr) == types.IntType:
 849                 errwrite = stderr
 850             else:
 851                 # Assuming file-like object
 852                 errwrite = stderr.fileno()
 853
 854             return (p2cread, p2cwrite,
 855                     c2pread, c2pwrite,
 856                     errread, errwrite)
 857
 858
 859         def _set_cloexec_flag(self, fd):
 860             try:
 861                 cloexec_flag = fcntl.FD_CLOEXEC
 862             except AttributeError:
 863                 cloexec_flag = 1
 864
 865             old = fcntl.fcntl(fd, fcntl.F_GETFD)
 866             fcntl.fcntl(fd, fcntl.F_SETFD, old | cloexec_flag)
 867
 868
 869         def _close_fds(self, but):
 870             for i in range(3, MAXFD):
 871                 if i == but:
 872                     continue
 873                 try:
 874                     os.close(i)
 875                 except:
 876                     pass
 877
 878
 879         def _execute_child(self, args, executable, preexec_fn, close_fds,
 880                            cwd, env, universal_newlines,
 881                            startupinfo, creationflags, shell,
 882                            p2cread, p2cwrite,
 883                            c2pread, c2pwrite,
 884                            errread, errwrite):
 885             """Execute program (POSIX version)"""
 886
 887             if isinstance(args, types.StringTypes):
 888                 args = [args]
 889
 890             if shell:
 891                 args = ["/bin/sh", "-c"] + args
 892
 893             if executable == None:
 894                 executable = args[0]
 895
 896             # For transferring possible exec failure from child to parent
 897             # The first char specifies the exception type: 0 means
 898             # OSError, 1 means some other error.
 899             errpipe_read, errpipe_write = os.pipe()
 900             self._set_cloexec_flag(errpipe_write)
 901
 902             self.pid = os.fork()
 903             if self.pid == 0:
 904                 # Child
 905                 try:
 906                     # Close parent's pipe ends
 907                     if p2cwrite:
 908                         os.close(p2cwrite)
 909                     if c2pread:
 910                         os.close(c2pread)
 911                     if errread:
 912                         os.close(errread)
 913                     os.close(errpipe_read)
 914
 915                     # Dup fds for child
 916                     if p2cread:
 917                         os.dup2(p2cread, 0)
 918                     if c2pwrite:
 919                         os.dup2(c2pwrite, 1)
 920                     if errwrite:
 921                         os.dup2(errwrite, 2)
 922
 923                     # Close pipe fds.  Make sure we doesn't close the same
 924                     # fd more than once.
 925                     if p2cread:
 926                         os.close(p2cread)
 927                     if c2pwrite and c2pwrite not in (p2cread,):
 928                         os.close(c2pwrite)
 929                     if errwrite and errwrite not in (p2cread, c2pwrite):
 930                         os.close(errwrite)
 931
 932                     # Close all other fds, if asked for
 933                     if close_fds:
 934                         self._close_fds(but=errpipe_write)
 935
 936                     if cwd != None:
 937                         os.chdir(cwd)
 938
 939                     if preexec_fn:
 940                         apply(preexec_fn)
 941
 942                     if env == None:
 943                         os.execvp(executable, args)
 944                     else:
 945                         os.execvpe(executable, args, env)
 946
 947                 except:
 948                     exc_type, exc_value, tb = sys.exc_info()
 949                     # Save the traceback and attach it to the exception object
 950                     exc_lines = traceback.format_exception(exc_type,
 951                                                            exc_value,
 952                                                            tb)
 953                     exc_value.child_traceback = ''.join(exc_lines)
 954                     os.write(errpipe_write, pickle.dumps(exc_value))
 955
 956                 # This exitcode won't be reported to applications, so it
 957                 # really doesn't matter what we return.
 958                 os._exit(255)
 959
 960             # Parent
 961             os.close(errpipe_write)
 962             if p2cread and p2cwrite:
 963                 os.close(p2cread)
 964             if c2pwrite and c2pread:
 965                 os.close(c2pwrite)
 966             if errwrite and errread:
 967                 os.close(errwrite)
 968
 969             # Wait for exec to fail or succeed; possibly raising exception
 970             data = os.read(errpipe_read, 1048576) # Exceptions limited to 1 MB
 971             os.close(errpipe_read)
 972             if data != "":
 973                 os.waitpid(self.pid, 0)
 974                 child_exception = pickle.loads(data)
 975                 raise child_exception
 976
 977
 978         def _handle_exitstatus(self, sts):
 979             if os.WIFSIGNALED(sts):
 980                 self.returncode = -os.WTERMSIG(sts)
 981             elif os.WIFEXITED(sts):
 982                 self.returncode = os.WEXITSTATUS(sts)
 983             else:
 984                 # Should never happen
 985                 raise RuntimeError("Unknown child exit status!")
 986
 987             _active.remove(self)
 988
 989
 990         def poll(self):
 991             """Check if child process has terminated.  Returns returncode
 992             attribute."""
 993             if self.returncode == None:
 994                 try:
 995                     pid, sts = os.waitpid(self.pid, os.WNOHANG)
 996                     if pid == self.pid:
 997                         self._handle_exitstatus(sts)
 998                 except os.error:
 999                     pass
1000             return self.returncode
1001
1002
1003         def wait(self):
1004             """Wait for child process to terminate.  Returns returncode
1005             attribute."""
1006             if self.returncode == None:
1007                 pid, sts = os.waitpid(self.pid, 0)
1008                 self._handle_exitstatus(sts)
1009             return self.returncode
1010
1011
1012         def communicate(self, input=None):
1013             """Interact with process: Send data to stdin.  Read data from
1014             stdout and stderr, until end-of-file is reached.  Wait for
1015             process to terminate.  The optional input argument should be a
1016             string to be sent to the child process, or None, if no data
1017             should be sent to the child.
1018
1019             communicate() returns a tuple (stdout, stderr)."""
1020             read_set = []
1021             write_set = []
1022             stdout = None # Return
1023             stderr = None # Return
1024
1025             if self.stdin:
1026                 # Flush stdio buffer.  This might block, if the user has
1027                 # been writing to .stdin in an uncontrolled fashion.
1028                 self.stdin.flush()
1029                 if input:
1030                     write_set.append(self.stdin)
1031                 else:
1032                     self.stdin.close()
1033             if self.stdout:
1034                 read_set.append(self.stdout)
1035                 stdout = []
1036             if self.stderr:
1037                 read_set.append(self.stderr)
1038                 stderr = []
1039
1040             while read_set or write_set:
1041                 rlist, wlist, xlist = select.select(read_set, write_set, [])
1042
1043                 if self.stdin in wlist:
1044                     # When select has indicated that the file is writable,
1045                     # we can write up to PIPE_BUF bytes without risk
1046                     # blocking.  POSIX defines PIPE_BUF >= 512
1047                     bytes_written = os.write(self.stdin.fileno(), input[:512])
1048                     input = input[bytes_written:]
1049                     if not input:
1050                         self.stdin.close()
1051                         write_set.remove(self.stdin)
1052
1053                 if self.stdout in rlist:
1054                     data = os.read(self.stdout.fileno(), 1024)
1055                     if data == "":
1056                         self.stdout.close()
1057                         read_set.remove(self.stdout)
1058                     stdout.append(data)
1059
1060                 if self.stderr in rlist:
1061                     data = os.read(self.stderr.fileno(), 1024)
1062                     if data == "":
1063                         self.stderr.close()
1064                         read_set.remove(self.stderr)
1065                     stderr.append(data)
1066
1067             # All data exchanged.  Translate lists into strings.
1068             if stdout != None:
1069                 stdout = ''.join(stdout)
1070             if stderr != None:
1071                 stderr = ''.join(stderr)
1072
1073             # Translate newlines, if requested.  We cannot let the file
1074             # object do the translation: It is based on stdio, which is
1075             # impossible to combine with select (unless forcing no
1076             # buffering).
1077             if self.universal_newlines and hasattr(open, 'newlines'):
1078                 if stdout:
1079                     stdout = self._translate_newlines(stdout)
1080                 if stderr:
1081                     stderr = self._translate_newlines(stderr)
1082
1083             self.wait()
1084             return (stdout, stderr)
1085
1086
1087 def _demo_posix():
1088     #
1089     # Example 1: Simple redirection: Get process list
1090     #
1091     plist = Popen(["ps"], stdout=PIPE).communicate()[0]
1092     print "Process list:"
1093     print plist
1094
1095     #
1096     # Example 2: Change uid before executing child
1097     #
1098     if os.getuid() == 0:
1099         p = Popen(["id"], preexec_fn=lambda: os.setuid(100))
1100         p.wait()
1101
1102     #
1103     # Example 3: Connecting several subprocesses
1104     #
1105     print "Looking for 'hda'..."
1106     p1 = Popen(["dmesg"], stdout=PIPE)
1107     p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
1108     print repr(p2.communicate()[0])
1109
1110     #
1111     # Example 4: Catch execution error
1112     #
1113     print
1114     print "Trying a weird file..."
1115     try:
1116         print Popen(["/this/path/does/not/exist"]).communicate()
1117     except OSError, e:
1118         if e.errno == errno.ENOENT:
1119             print "The file didn't exist.  I thought so..."
1120             print "Child traceback:"
1121             print e.child_traceback
1122         else:
1123             print "Error", e.errno
1124     else:
1125         print >>sys.stderr, "Gosh.  No error."
1126
1127
1128 def _demo_windows():
1129     #
1130     # Example 1: Connecting several subprocesses
1131     #
1132     print "Looking for 'PROMPT' in set output..."
1133     p1 = Popen("set", stdout=PIPE, shell=True)
1134     p2 = Popen('find "PROMPT"', stdin=p1.stdout, stdout=PIPE)
1135     print repr(p2.communicate()[0])
1136
1137     #
1138     # Example 2: Simple execution of program
1139     #
1140     print "Executing calc..."
1141     p = Popen("calc")
1142     p.wait()
1143
1144
1145 if __name__ == "__main__":
1146     if mswindows:
1147         _demo_windows()
1148     else:
1149         _demo_posix()