{-# LANGUAGE CPP #-}{-# OPTIONS_HADDOCK not-home #-}{-# LANGUAGE Trustworthy #-}{-# LANGUAGE InterruptibleFFI #-}------------------------------------------------------------------------------- |-- Module : System.Process.Internals-- Copyright : (c) The University of Glasgow 2004-- License : BSD-style (see the file libraries/base/LICENSE)---- Maintainer : libraries@haskell.org-- Stability : experimental-- Portability : portable---- __Note:__ This module exports internal implementation details that may-- change anytime. If you want a more stable API, use "System.Process"-- instead.-------------------------------------------------------------------------------moduleSystem.Process.Internals(ProcessHandle (..),ProcessHandle__ (..),PHANDLE ,closePHANDLE ,mkProcessHandle ,#ifdef WINDOWSCGid(..),#elseCGid,#endifGroupID,UserID,modifyProcessHandle ,withProcessHandle ,CreateProcess (..),CmdSpec (..),StdStream (..),ProcRetHandles (..),createProcess_ ,runGenProcess_ ,--deprecatedfdToHandle,startDelegateControlC ,endDelegateControlC ,stopDelegateControlC ,unwrapHandles ,#ifdef WINDOWSterminateJob,waitForJobCompletion,timeout_Infinite,#elsepPrPr_disableITimers,c_execvpe,ignoreSignal ,defaultSignal ,#endifwithFilePathException ,withCEnvironment ,translate ,createPipe ,createPipeFd ,interruptProcessGroupOf ,)whereimportForeign.CimportSystem.IOimportGHC.IO.Handle.FD(fdToHandle)importSystem.Posix.Internals(FD)importSystem.Process.Common #ifdef WINDOWSimportSystem.Process.Windows#elseimportSystem.Process.Posix #endif-- ------------------------------------------------------------------------------ | This function is almost identical to-- 'System.Process.createProcess'. The only differences are:---- * 'Handle's provided via 'UseHandle' are not closed automatically.---- * This function takes an extra @String@ argument to be used in creating-- error messages.---- * 'use_process_jobs' can be set in CreateProcess since 1.5.0.0 in order to create-- an I/O completion port to monitor a process tree's progress on Windows.---- The function also returns two new handles:-- * an I/O Completion Port handle on which events-- will be signaled.-- * a Job handle which can be used to kill all running-- processes.---- On POSIX platforms these two new handles will always be Nothing------ This function has been available from the "System.Process.Internals" module-- for some time, and is part of the "System.Process" module since version-- 1.2.1.0.---- @since 1.2.1.0createProcess_::String-- ^ function name (for error messages)->CreateProcess ->IO(MaybeHandle,MaybeHandle,MaybeHandle,ProcessHandle )createProcess_ msg proc_ =unwrapHandles `fmap`createProcess_Internal msg proc_ {-# INLINE createProcess_ #-}-- -------------------------------------------------------------------------- Escaping commands for shells{-
On Windows we also use this for running commands. We use CreateProcess,
passing a single command-line string (lpCommandLine) as its argument.
(CreateProcess is well documented on http://msdn.microsoft.com.)
 - It parses the beginning of the string to find the command. If the
 file name has embedded spaces, it must be quoted, using double
 quotes thus
 "foo\this that\cmd" arg1 arg2
 - The invoked command can in turn access the entire lpCommandLine string,
 and the C runtime does indeed do so, parsing it to generate the
 traditional argument vector argv[0], argv[1], etc. It does this
 using a complex and arcane set of rules which are described here:
 https://msdn.microsoft.com/en-us/library/a1y7w461.aspx
 (if this URL stops working, you might be able to find it by
 searching for "Parsing C Command-Line Arguments" on MSDN. Also,
 the code in the Microsoft C runtime that does this translation
 is shipped with VC++).
Our goal in runProcess is to take a command filename and list of
arguments, and construct a string which inverts the translatsions
described above, such that the program at the other end sees exactly
the same arguments in its argv[] that we passed to rawSystem.
This inverse translation is implemented by 'translate' below.
Here are some pages that give informations on Windows-related
limitations and deviations from Unix conventions:
 http://support.microsoft.com/default.aspx?scid=kb;en-us;830473
 Command lines and environment variables effectively limited to 8191
 characters on Win XP, 2047 on NT/2000 (probably even less on Win 9x):
 http://www.microsoft.com/windowsxp/home/using/productdoc/en/default.asp?url=/WINDOWSXP/home/using/productdoc/en/percent.asp
 Command-line substitution under Windows XP. IIRC these facilities (or at
 least a large subset of them) are available on Win NT and 2000. Some
 might be available on Win 9x.
 http://www.microsoft.com/windowsxp/home/using/productdoc/en/default.asp?url=/WINDOWSXP/home/using/productdoc/en/Cmd.asp
 How CMD.EXE processes command lines.
Note: CreateProcess does have a separate argument (lpApplicationName)
with which you can specify the command, but we have to slap the
command into lpCommandLine anyway, so that argv[0] is what a C program
expects (namely the application name). So it seems simpler to just
use lpCommandLine alone, which CreateProcess supports.
-}translate::String->Stringtranslate =translateInternal {-# INLINE translate #-}-- ----------------------------------------------------------------------------- unwrapHandlesunwrapHandles::ProcRetHandles ->(MaybeHandle,MaybeHandle,MaybeHandle,ProcessHandle )unwrapHandles r =(hStdInputr ,hStdOutputr ,hStdErrorr ,procHandler )-- ------------------------------------------------------------------------------ Deprecated / compat{-# DEPRECATED runGenProcess_
 "Please do not use this anymore, use the ordinary 'System.Process.createProcess'. If you need the SIGINT handling, use delegate_ctlc = True (runGenProcess_ is now just an imperfectly emulated stub that probably duplicates or overrides your own signal handling)." #-}runGenProcess_::String-- ^ function name (for error messages)->CreateProcess ->MaybeCLong-- ^ handler for SIGINT->MaybeCLong-- ^ handler for SIGQUIT->IO(MaybeHandle,MaybeHandle,MaybeHandle,ProcessHandle )-- On Windows, setting delegate_ctlc has no impactrunGenProcess_ fun c (Justsig )(Justsig' )|isDefaultSignal sig &&sig ==sig' =createProcess_ fun c {delegate_ctlc=True}runGenProcess_fun c __=createProcess_ fun c -- ----------------------------------------------------------------------------- createPipe-- | Create a pipe for interprocess communication and return a-- @(readEnd, writeEnd)@ `Handle` pair.---- @since 1.2.1.0createPipe::IO(Handle,Handle)createPipe =createPipeInternal {-# INLINE createPipe #-}-- ----------------------------------------------------------------------------- createPipeFd-- | Create a pipe for interprocess communication and return a-- @(readEnd, writeEnd)@ `FD` pair.---- @since 1.4.2.0createPipeFd::IO(FD,FD)createPipeFd =createPipeInternalFd {-# INLINE createPipeFd #-}-- ------------------------------------------------------------------------------ interruptProcessGroupOf-- | Sends an interrupt signal to the process group of the given process.---- On Unix systems, it sends the group the SIGINT signal.---- On Windows systems, it generates a CTRL_BREAK_EVENT and will only work for-- processes created using 'createProcess' and setting the 'create_group' flaginterruptProcessGroupOf::ProcessHandle -- ^ A process in the process group->IO()interruptProcessGroupOf =interruptProcessGroupOfInternal