| Copyright | (c) The University of Glasgow 2004 |
|---|---|
| License | BSD-style (see the file libraries/base/LICENSE) |
| Maintainer | libraries@haskell.org |
| Stability | experimental |
| Portability | portable |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
System.Process.Internals
Description
Note: This module exports internal implementation details that may change anytime. If you want a more stable API, use System.Process instead.
Synopsis
- data ProcessHandle = ProcessHandle {
- phandle :: !(MVar ProcessHandle__)
- mb_delegate_ctlc :: !Bool
- waitpidLock :: !(MVar ())
- data ProcessHandle__
- = OpenHandle { }
- | OpenExtHandle { }
- | ClosedHandle ExitCode
- type PHANDLE = CPid
- closePHANDLE :: PHANDLE -> IO ()
- mkProcessHandle :: PHANDLE -> Bool -> IO ProcessHandle
- data CGid
- type GroupID = CGid
- type UserID = CUid
- modifyProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO (ProcessHandle__, a)) -> IO a
- withProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO a) -> IO a
- data CreateProcess = CreateProcess {
- cmdspec :: CmdSpec
- cwd :: Maybe FilePath
- env :: Maybe [(String, String)]
- std_in :: StdStream
- std_out :: StdStream
- std_err :: StdStream
- close_fds :: Bool
- create_group :: Bool
- delegate_ctlc :: Bool
- detach_console :: Bool
- create_new_console :: Bool
- new_session :: Bool
- child_group :: Maybe GroupID
- child_user :: Maybe UserID
- use_process_jobs :: Bool
- data CmdSpec
- data StdStream
- data ProcRetHandles = ProcRetHandles {}
- createProcess_ :: String -> CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- runGenProcess_ :: String -> CreateProcess -> Maybe CLong -> Maybe CLong -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- fdToHandle :: FD -> IO Handle
- startDelegateControlC :: IO ()
- endDelegateControlC :: ExitCode -> IO ()
- stopDelegateControlC :: IO ()
- unwrapHandles :: ProcRetHandles -> (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- pPrPr_disableITimers :: IO ()
- c_execvpe :: CString -> Ptr CString -> Ptr CString -> IO CInt
- runInteractiveProcess_lock :: MVar ()
- ignoreSignal :: CLong
- defaultSignal :: CLong
- withFilePathException :: FilePath -> IO a -> IO a
- withCEnvironment :: [(String, String)] -> (Ptr CString -> IO a) -> IO a
- translate :: String -> String
- createPipe :: IO (Handle, Handle)
- createPipeFd :: IO (FD, FD)
- interruptProcessGroupOf :: ProcessHandle -> IO ()
- withForkWait :: IO () -> (IO () -> IO a) -> IO a
- ignoreSigPipe :: IO () -> IO ()
Documentation
data ProcessHandle Source #
A handle to a process, which can be used to wait for termination
of the process using waitForProcess.
None of the process-creation functions in this library wait for
termination: they all return a ProcessHandle which may be used
to wait for the process later.
On Windows a second wait method can be used to block for event completion. This requires two handles. A process job handle and a events handle to monitor.
Constructors
| ProcessHandle | |
Fields
| |
data ProcessHandle__ Source #
Constructors
| OpenHandle | |
Fields
| |
| OpenExtHandle |
|
Fields
| |
| ClosedHandle ExitCode | |
closePHANDLE :: PHANDLE -> IO () Source #
mkProcessHandle :: PHANDLE -> Bool -> IO ProcessHandle Source #
Instances
| Storable CGid | |
Defined in System.Posix.Types | |
| Bits CGid | |
Defined in System.Posix.Types Methods (.&.) :: CGid -> CGid -> CGid # (.|.) :: CGid -> CGid -> CGid # complement :: CGid -> CGid # shift :: CGid -> Int -> CGid # rotate :: CGid -> Int -> CGid # setBit :: CGid -> Int -> CGid # clearBit :: CGid -> Int -> CGid # complementBit :: CGid -> Int -> CGid # testBit :: CGid -> Int -> Bool # bitSizeMaybe :: CGid -> Maybe Int # shiftL :: CGid -> Int -> CGid # unsafeShiftL :: CGid -> Int -> CGid # shiftR :: CGid -> Int -> CGid # unsafeShiftR :: CGid -> Int -> CGid # rotateL :: CGid -> Int -> CGid # | |
| FiniteBits CGid | |
Defined in System.Posix.Types Methods finiteBitSize :: CGid -> Int # countLeadingZeros :: CGid -> Int # countTrailingZeros :: CGid -> Int # | |
| Bounded CGid | |
| Enum CGid | |
| Ix CGid | |
| Num CGid | |
| Read CGid | |
| Integral CGid | |
| Real CGid | |
Defined in System.Posix.Types Methods toRational :: CGid -> Rational # | |
| Show CGid | |
| Eq CGid | |
| Ord CGid | |
modifyProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO (ProcessHandle__, a)) -> IO a Source #
withProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO a) -> IO a Source #
data CreateProcess Source #
Constructors
| CreateProcess | |
Fields
| |
Instances
| Show CreateProcess Source # | |
Defined in System.Process.Common Methods showsPrec :: Int -> CreateProcess -> ShowS # show :: CreateProcess -> String # showList :: [CreateProcess] -> ShowS # | |
| Eq CreateProcess Source # | |
Defined in System.Process.Common Methods (==) :: CreateProcess -> CreateProcess -> Bool # (/=) :: CreateProcess -> CreateProcess -> Bool # | |
Constructors
| ShellCommand String | A command line to execute using the shell |
| RawCommand FilePath [String] | The name of an executable with a list of arguments The
Windows does not have a mechanism for passing multiple arguments.
When using |
Constructors
| Inherit | Inherit Handle from parent |
| UseHandle Handle | Use the supplied Handle |
| CreatePipe | Create a new pipe. The returned
|
| NoStream | Close the stream's file descriptor without
passing a Handle. On POSIX systems this may
lead to strange behavior in the child process
because attempting to read or write after the
file has been closed throws an error. This
should only be used with child processes that
don't use the file descriptor at all. If you
wish to ignore the child process's output you
should either create a pipe and drain it
manually or pass a |
data ProcRetHandles Source #
contains the handles returned by a call to createProcess_Internal
Constructors
| ProcRetHandles | |
Fields
| |
Arguments
| :: String | Function name (for error messages). This can be any |
| -> CreateProcess | |
| -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) |
This function is almost identical to
createProcess. The only differences are:
Handles provided viaUseHandleare not closed automatically.- This function takes an extra
Stringargument to be used in creating error messages.
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.0
Arguments
| :: String | function name (for error messages) |
| -> CreateProcess | |
| -> Maybe CLong | handler for SIGINT |
| -> Maybe CLong | handler for SIGQUIT |
| -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) |
Deprecated: Please do not use this anymore, use the ordinary 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).
fdToHandle :: FD -> IO Handle #
Turn an existing file descriptor into a Handle. This is used by various external libraries to make Handles.
Makes a binary Handle. This is for historical reasons; it should probably be a text Handle with the default encoding and newline translation instead.
startDelegateControlC :: IO () Source #
endDelegateControlC :: ExitCode -> IO () Source #
stopDelegateControlC :: IO () Source #
unwrapHandles :: ProcRetHandles -> (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) Source #
pPrPr_disableITimers :: IO () #
runInteractiveProcess_lock :: MVar () Source #
runInteractiveProcess blocks signals around the fork().
Since blocking/unblocking of signals is a global state operation, we need to
ensure mutual exclusion of calls to runInteractiveProcess.
This lock is exported so that other libraries which also need to fork()
(and also need to make the same global state changes) can protect their changes
with the same lock.
See https://github.com/haskell/process/pull/154.
Since: 1.6.6.0
ignoreSignal :: CLong Source #
createPipe :: IO (Handle, Handle) Source #
Create a pipe for interprocess communication and return a
(readEnd, writeEnd) Handle pair.
- WinIO Support
When this function is used with WinIO enabled it's the caller's responsibility to register the handles with the I/O manager. If this is not done the operation will deadlock. Association can be done as follows:
#if defined(IO_MANAGER_WINIO)
import GHC.IO.SubSystem ((!))
import GHC.IO.Handle.Windows (handleToHANDLE)
import GHC.Event.Windows (associateHandle')
#endif
...
#if defined (IO_MANAGER_WINIO)
return () ! (do
associateHandle' =handleToHANDLE <handle)
#endif
Only associate handles that you are in charge of read/writing to. Do not associate handles passed to another process. It's the process's reponsibility to register the handle if it supports async access.
Since: 1.2.1.0
createPipeFd :: IO (FD, FD) Source #
Create a pipe for interprocess communication and return a
(readEnd, writeEnd) FD pair.
Since: 1.4.2.0
interruptProcessGroupOf Source #
Arguments
| :: ProcessHandle | A process in the process group |
| -> IO () |
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 flag
withForkWait :: IO () -> (IO () -> IO a) -> IO a Source #
Fork a thread while doing something else, but kill it if there's an exception.
This is important in the cases above because we want to kill the thread that is holding the Handle lock, because when we clean up the process we try to close that handle, which could otherwise deadlock.
Since: 1.6.20.0
ignoreSigPipe :: IO () -> IO () Source #
Handle any SIGPIPE errors in the given computation.
Since: 1.6.20.0