Debian Codegraph @

src/System/Process/Typed.hs

raw
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE TypeFamilies #-}
3 {-# LANGUAGE DeriveDataTypeable #-}
4 {-# LANGUAGE RecordWildCards #-}
5 {-# LANGUAGE DataKinds #-}
6 {-# LANGUAGE DeriveFunctor #-}
7 {-# LANGUAGE RankNTypes #-}
8 {-# LANGUAGE ScopedTypeVariables #-}
9 -- | The simplest way to get started with this API is to turn on
10 -- @OverloadedStrings@ and call 'runProcess'. The following will
11 -- write the contents of @/home@ to @stdout@ and then print the exit
12 -- code (on a UNIX system).
13 --
14 -- @
15 -- {-\# LANGUAGE OverloadedStrings \#-}
16 --
17 -- 'runProcess' "ls -l /home" >>= print
18 -- @
19 --
20 -- Please see the [README.md](https://github.com/fpco/typed-process#readme)
21 -- file for more examples of using this API.
22 module System.Process.Typed
23 ( -- * Types
24 ProcessConfig
25 , StreamSpec
26 , StreamType (..)
27 , Process
28
29 -- * ProcessConfig
30 -- ** Smart constructors
31 , proc
32 , shell
33
34 -- | #processconfigsetters#
35
36 -- ** Setters
37 , setStdin
38 , setStdout
39 , setStderr
40 , setWorkingDir
41 , setWorkingDirInherit
42 , setEnv
43 , setEnvInherit
44 , setCloseFds
45 , setCreateGroup
46 , setDelegateCtlc
47 #if MIN_VERSION_process(1, 3, 0)
48 , setDetachConsole
49 , setCreateNewConsole
50 , setNewSession
51 #endif
52 #if MIN_VERSION_process(1, 4, 0) && !WINDOWS
53 , setChildGroup
54 , setChildGroupInherit
55 , setChildUser
56 , setChildUserInherit
57 #endif
58
59 -- | #streamspecs#
60
61 -- * Stream specs
62 -- ** Built-in stream specs
63 , inherit
64 , nullStream
65 , closed
66 , byteStringInput
67 , byteStringOutput
68 , createPipe
69 , useHandleOpen
70 , useHandleClose
71
72 -- ** Create your own stream spec
73 , mkStreamSpec
74 , mkPipeStreamSpec
75
76 -- | #launchaprocess#
77
78 -- * Launch a process
79 , runProcess
80 , readProcess
81 , readProcessStdout
82 , readProcessStderr
83 , readProcessInterleaved
84 , withProcessWait
85 , withProcessTerm
86 , startProcess
87 , stopProcess
88 -- ** Exception-throwing functions
89 -- | The functions ending in underbar (@_@) are the same as
90 -- their counterparts without underbar but instead of returning
91 -- an 'ExitCode' they throw 'ExitCodeException' on failure.
92 , runProcess_
93 , readProcess_
94 , readProcessStdout_
95 , readProcessStderr_
96 , readProcessInterleaved_
97 , withProcessWait_
98 , withProcessTerm_
99
100 -- | #interactwithaprocess#
101
102 -- * Interact with a process
103
104 -- ** Process exit code
105 , waitExitCode
106 , waitExitCodeSTM
107 , getExitCode
108 , getExitCodeSTM
109 , checkExitCode
110 , checkExitCodeSTM
111
112 -- ** Process ID
113 , getPid
114
115 -- ** Process streams
116 , getStdin
117 , getStdout
118 , getStderr
119
120 -- * Exceptions
121 , ExitCodeException (..)
122 , exitCodeExceptionWithOutput
123 , exitCodeExceptionNoOutput
124 , ByteStringOutputException (..)
125
126 -- * Re-exports
127 , ExitCode (..)
128 , P.StdStream (..)
129 , P.Pid
130
131 -- * Unsafe functions
132 , unsafeProcessHandle
133 -- * Deprecated functions
134 , withProcess
135 , withProcess_
136 ) where
137
138 import Control.Exception hiding (bracket, finally)
139 import Control.Monad.IO.Class
140 import qualified System.Process as P
141 import System.IO (hClose)
142 import System.IO.Error (isPermissionError)
143 import Control.Concurrent (threadDelay)
144 import Control.Concurrent.Async (asyncWithUnmask, cancel, waitCatch)
145 import Control.Concurrent.STM (newEmptyTMVarIO, atomically, putTMVar, TMVar, readTMVar, tryReadTMVar, STM, tryPutTMVar, throwSTM, catchSTM)
146 import System.Exit (ExitCode (ExitSuccess, ExitFailure))
147 import System.Process.Typed.Internal
148 import qualified Data.ByteString.Lazy as L
149 import GHC.RTS.Flags (getConcFlags, ctxtSwitchTime)
150 import Control.Monad.IO.Unlift
151
152 #if !MIN_VERSION_base(4, 8, 0)
153 import Control.Applicative (Applicative (..), (<$>), (<$))
154 #endif
155
156 #if !MIN_VERSION_process(1, 3, 0)
157 import qualified System.Process.Internals as P (createProcess_)
158 #endif
159
160 -- | A running process. The three type parameters provide the type of
161 -- the standard input, standard output, and standard error streams.
162 --
163 -- To interact with a @Process@ use the functions from the section
164 -- [Interact with a process](#interactwithaprocess).
165 --
166 -- @since 0.1.0.0
167 data Process stdin stdout stderr = Process
168 { pConfig :: !(ProcessConfig () () ())
169 , pCleanup :: !(IO ())
170 , pStdin :: !stdin
171 , pStdout :: !stdout
172 , pStderr :: !stderr
173 , pHandle :: !P.ProcessHandle
174 , pExitCode :: !(TMVar ExitCode)
175 }
176 instance Show (Process stdin stdout stderr) where
177 show p = "Running process: " ++ show (pConfig p)
178
179 -- | Launch a process based on the given 'ProcessConfig'. You should
180 -- ensure that you call 'stopProcess' on the result. It's usually
181 -- better to use one of the functions in this module which ensures
182 -- 'stopProcess' is called, such as 'withProcessWait'.
183 --
184 -- @since 0.1.0.0
185 startProcess :: MonadIO m
186 => ProcessConfig stdin stdout stderr
187 -- ^
188 -> m (Process stdin stdout stderr)
189 startProcess pConfig'@ProcessConfig {..} = liftIO $ do
190 ssStream pcStdin $ \realStdin ->
191 ssStream pcStdout $ \realStdout ->
192 ssStream pcStderr $ \realStderr -> do
193
194 let cp0 =
195 case pcCmdSpec of
196 P.ShellCommand cmd -> P.shell cmd
197 P.RawCommand cmd args -> P.proc cmd args
198 cp = cp0
199 { P.std_in = realStdin
200 , P.std_out = realStdout
201 , P.std_err = realStderr
202 , P.cwd = pcWorkingDir
203 , P.env = pcEnv
204 , P.close_fds = pcCloseFds
205 , P.create_group = pcCreateGroup
206 , P.delegate_ctlc = pcDelegateCtlc
207
208 #if MIN_VERSION_process(1, 3, 0)
209 , P.detach_console = pcDetachConsole
210 , P.create_new_console = pcCreateNewConsole
211 , P.new_session = pcNewSession
212 #endif
213
214 #if MIN_VERSION_process(1, 4, 0) && !WINDOWS
215 , P.child_group = pcChildGroup
216 , P.child_user = pcChildUser
217 #endif
218
219 }
220
221 (minH, moutH, merrH, pHandle) <- P.createProcess_ "startProcess" cp
222
223 ((pStdin, pStdout, pStderr), pCleanup1) <- runCleanup $ (,,)
224 <$> ssCreate pcStdin pConfig minH
225 <*> ssCreate pcStdout pConfig moutH
226 <*> ssCreate pcStderr pConfig merrH
227
228 pExitCode <- newEmptyTMVarIO
229 waitingThread <- asyncWithUnmask $ \unmask -> do
230 ec <- unmask $ -- make sure the masking state from a bracket isn't inherited
231 if multiThreadedRuntime
232 then P.waitForProcess pHandle
233 else do
234 switchTime <- fromIntegral . (`div` 1000) . ctxtSwitchTime
235 <$> getConcFlags
236 let minDelay = 1
237 maxDelay = max minDelay switchTime
238 loop delay = do
239 threadDelay delay
240 mec <- P.getProcessExitCode pHandle
241 case mec of
242 Nothing -> loop $ min maxDelay (delay * 2)
243 Just ec -> pure ec
244 loop minDelay
245 atomically $ putTMVar pExitCode ec
246 return ec
247
248 let pCleanup = pCleanup1 `finally` do
249 -- First: stop calling waitForProcess, so that we can
250 -- avoid race conditions where the process is removed from
251 -- the system process table while we're trying to
252 -- terminate it.
253 cancel waitingThread
254
255 -- Now check if the process had already exited
256 eec <- waitCatch waitingThread
257
258 case eec of
259 -- Process already exited, nothing to do
260 Right _ec -> return ()
261
262 -- Process didn't exit yet, let's terminate it and
263 -- then call waitForProcess ourselves
264 Left _ -> do
265 terminateProcess pHandle
266 ec <- P.waitForProcess pHandle
267 success <- atomically $ tryPutTMVar pExitCode ec
268 evaluate $ assert success ()
269
270 return Process {..}
271 where
272 pConfig = clearStreams pConfig'
273
274 terminateProcess pHandle = do
275 eres <- try $ P.terminateProcess pHandle
276 case eres of
277 Left e
278 -- On Windows, with the single-threaded runtime, it
279 -- seems that if a process has already exited, the
280 -- call to terminateProcess will fail with a
281 -- permission denied error. To work around this, we
282 -- catch this exception and then immediately
283 -- waitForProcess. There's a chance that there may be
284 -- other reasons for this permission error to appear,
285 -- in which case this code may allow us to wait too
286 -- long for a child process instead of erroring out.
287 -- Recommendation: always use the multi-threaded
288 -- runtime!
289 | isPermissionError e && not multiThreadedRuntime && isWindows ->
290 pure ()
291 | otherwise -> throwIO e
292 Right () -> pure ()
293
294 foreign import ccall unsafe "rtsSupportsBoundThreads"
295 multiThreadedRuntime :: Bool
296
297 isWindows :: Bool
298 #if WINDOWS
299 isWindows = True
300 #else
301 isWindows = False
302 #endif
303
304 -- | Close a process and release any resources acquired. This will
305 -- ensure 'P.terminateProcess' is called, wait for the process to
306 -- actually exit, and then close out resources allocated for the
307 -- streams. In the event of any cleanup exceptions being thrown this
308 -- will throw an exception.
309 --
310 -- @since 0.1.0.0
311 stopProcess :: MonadIO m
312 => Process stdin stdout stderr
313 -> m ()
314 stopProcess = liftIO . pCleanup
315
316 -- | Uses the bracket pattern to call 'startProcess' and ensures that
317 -- 'stopProcess' is called.
318 --
319 -- This function is usually /not/ what you want. You're likely better
320 -- off using 'withProcessWait'. See
321 -- <https://github.com/fpco/typed-process/issues/25>.
322 --
323 -- @since 0.2.5.0
324 withProcessTerm :: (MonadUnliftIO m)
325 => ProcessConfig stdin stdout stderr
326 -- ^
327 -> (Process stdin stdout stderr -> m a)
328 -- ^
329 -> m a
330 withProcessTerm config = bracket (startProcess config) stopProcess
331
332 -- | Uses the bracket pattern to call 'startProcess'. Unlike
333 -- 'withProcessTerm', this function will wait for the child process to
334 -- exit, and only kill it with 'stopProcess' in the event that the
335 -- inner function throws an exception.
336 --
337 -- To interact with a @Process@ use the functions from the section
338 -- [Interact with a process](#interactwithaprocess).
339 --
340 -- @since 0.2.5.0
341 withProcessWait :: (MonadUnliftIO m)
342 => ProcessConfig stdin stdout stderr
343 -- ^
344 -> (Process stdin stdout stderr -> m a)
345 -- ^
346 -> m a
347 withProcessWait config f =
348 bracket
349 (startProcess config)
350 stopProcess
351 (\p -> f p <* waitExitCode p)
352
353 -- | Deprecated synonym for 'withProcessTerm'.
354 --
355 -- @since 0.1.0.0
356 withProcess :: (MonadUnliftIO m)
357 => ProcessConfig stdin stdout stderr
358 -> (Process stdin stdout stderr -> m a)
359 -> m a
360 withProcess = withProcessTerm
361 {-# DEPRECATED withProcess "Please consider using `withProcessWait`, or instead use `withProcessTerm`" #-}
362
363 -- | Same as 'withProcessTerm', but also calls 'checkExitCode'
364 --
365 -- To interact with a @Process@ use the functions from the section
366 -- [Interact with a process](#interactwithaprocess).
367 --
368 -- @since 0.2.5.0
369 withProcessTerm_ :: (MonadUnliftIO m)
370 => ProcessConfig stdin stdout stderr
371 -- ^
372 -> (Process stdin stdout stderr -> m a)
373 -- ^
374 -> m a
375 withProcessTerm_ config = bracket
376 (startProcess config)
377 (\p -> stopProcess p `finally` checkExitCode p)
378
379 -- | Same as 'withProcessWait', but also calls 'checkExitCode'
380 --
381 -- @since 0.2.5.0
382 withProcessWait_ :: (MonadUnliftIO m)
383 => ProcessConfig stdin stdout stderr
384 -- ^
385 -> (Process stdin stdout stderr -> m a)
386 -- ^
387 -> m a
388 withProcessWait_ config f = bracket
389 (startProcess config)
390 stopProcess
391 (\p -> f p <* checkExitCode p)
392
393 -- | Deprecated synonym for 'withProcessTerm_'.
394 --
395 -- @since 0.1.0.0
396 withProcess_ :: (MonadUnliftIO m)
397 => ProcessConfig stdin stdout stderr
398 -> (Process stdin stdout stderr -> m a)
399 -> m a
400 withProcess_ = withProcessTerm_
401 {-# DEPRECATED withProcess_ "Please consider using `withProcessWait_`, or instead use `withProcessTerm_`" #-}
402
403 -- | Run a process, capture its standard output and error as a
404 -- 'L.ByteString', wait for it to complete, and then return its exit
405 -- code, output, and error.
406 --
407 -- Note that any previously used 'setStdout' or 'setStderr' will be
408 -- overridden.
409 --
410 -- @since 0.1.0.0
411 readProcess :: MonadIO m
412 => ProcessConfig stdin stdoutIgnored stderrIgnored
413 -- ^
414 -> m (ExitCode, L.ByteString, L.ByteString)
415 readProcess pc =
416 liftIO $ withProcess pc' $ \p -> atomically $ (,,)
417 <$> waitExitCodeSTM p
418 <*> getStdout p
419 <*> getStderr p
420 where
421 pc' = setStdout byteStringOutput
422 $ setStderr byteStringOutput pc
423
424 -- | Same as 'readProcess', but instead of returning the 'ExitCode',
425 -- checks it with 'checkExitCode'.
426 --
427 -- Exceptions thrown by this function will include stdout and stderr.
428 --
429 -- @since 0.1.0.0
430 readProcess_ :: MonadIO m
431 => ProcessConfig stdin stdoutIgnored stderrIgnored
432 -- ^
433 -> m (L.ByteString, L.ByteString)
434 readProcess_ pc =
435 liftIO $ withProcess pc' $ \p -> atomically $ do
436 stdout <- getStdout p
437 stderr <- getStderr p
438 checkExitCodeSTM p `catchSTM` \ece -> throwSTM ece
439 { eceStdout = stdout
440 , eceStderr = stderr
441 }
442 return (stdout, stderr)
443 where
444 pc' = setStdout byteStringOutput
445 $ setStderr byteStringOutput pc
446
447 -- | Same as 'readProcess', but only read the stdout of the process. Original settings for stderr remain.
448 --
449 -- @since 0.2.1.0
450 readProcessStdout
451 :: MonadIO m
452 => ProcessConfig stdin stdoutIgnored stderr
453 -- ^
454 -> m (ExitCode, L.ByteString)
455 readProcessStdout pc =
456 liftIO $ withProcess pc' $ \p -> atomically $ (,)
457 <$> waitExitCodeSTM p
458 <*> getStdout p
459 where
460 pc' = setStdout byteStringOutput pc
461
462 -- | Same as 'readProcessStdout', but instead of returning the
463 -- 'ExitCode', checks it with 'checkExitCode'.
464 --
465 -- Exceptions thrown by this function will include stdout.
466 --
467 -- @since 0.2.1.0
468 readProcessStdout_
469 :: MonadIO m
470 => ProcessConfig stdin stdoutIgnored stderr
471 -- ^
472 -> m L.ByteString
473 readProcessStdout_ pc =
474 liftIO $ withProcess pc' $ \p -> atomically $ do
475 stdout <- getStdout p
476 checkExitCodeSTM p `catchSTM` \ece -> throwSTM ece
477 { eceStdout = stdout
478 }
479 return stdout
480 where
481 pc' = setStdout byteStringOutput pc
482
483 -- | Same as 'readProcess', but only read the stderr of the process.
484 -- Original settings for stdout remain.
485 --
486 -- @since 0.2.1.0
487 readProcessStderr
488 :: MonadIO m
489 => ProcessConfig stdin stdout stderrIgnored
490 -- ^
491 -> m (ExitCode, L.ByteString)
492 readProcessStderr pc =
493 liftIO $ withProcess pc' $ \p -> atomically $ (,)
494 <$> waitExitCodeSTM p
495 <*> getStderr p
496 where
497 pc' = setStderr byteStringOutput pc
498
499 -- | Same as 'readProcessStderr', but instead of returning the
500 -- 'ExitCode', checks it with 'checkExitCode'.
501 --
502 -- Exceptions thrown by this function will include stderr.
503 --
504 -- @since 0.2.1.0
505 readProcessStderr_
506 :: MonadIO m
507 => ProcessConfig stdin stdout stderrIgnored
508 -- ^
509 -> m L.ByteString
510 readProcessStderr_ pc =
511 liftIO $ withProcess pc' $ \p -> atomically $ do
512 stderr <- getStderr p
513 checkExitCodeSTM p `catchSTM` \ece -> throwSTM ece
514 { eceStderr = stderr
515 }
516 return stderr
517 where
518 pc' = setStderr byteStringOutput pc
519
520 withProcessInterleave :: (MonadUnliftIO m)
521 => ProcessConfig stdin stdoutIgnored stderrIgnored
522 -- ^
523 -> (Process stdin (STM L.ByteString) () -> m a)
524 -- ^
525 -> m a
526 withProcessInterleave pc inner =
527 -- Create a pipe to be shared for both stdout and stderr
528 bracket P.createPipe (\(r, w) -> hClose r >> hClose w) $ \(readEnd, writeEnd) -> do
529 -- Use the writer end of the pipe for both stdout and stderr. For
530 -- the stdout half, use byteStringFromHandle to read the data into
531 -- a lazy ByteString in memory.
532 let pc' = setStdout (mkStreamSpec (P.UseHandle writeEnd) (\pc'' _ -> byteStringFromHandle pc'' readEnd))
533 $ setStderr (useHandleOpen writeEnd)
534 pc
535 withProcess pc' $ \p -> do
536 -- Now that the process is forked, close the writer end of this
537 -- pipe, otherwise the reader end will never give an EOF.
538 liftIO $ hClose writeEnd
539 inner p
540
541 -- | Same as 'readProcess', but interleaves stderr with stdout.
542 --
543 -- Motivation: Use this function if you need stdout interleaved with stderr
544 -- output (e.g. from an HTTP server) in order to debug failures.
545 --
546 -- @since 0.2.4.0
547 readProcessInterleaved
548 :: MonadIO m
549 => ProcessConfig stdin stdoutIgnored stderrIgnored
550 -- ^
551 -> m (ExitCode, L.ByteString)
552 readProcessInterleaved pc =
553 liftIO $
554 withProcessInterleave pc $ \p ->
555 atomically $ (,)
556 <$> waitExitCodeSTM p
557 <*> getStdout p
558
559 -- | Same as 'readProcessInterleaved', but instead of returning the 'ExitCode',
560 -- checks it with 'checkExitCode'.
561 --
562 -- Exceptions thrown by this function will include stdout.
563 --
564 -- @since 0.2.4.0
565 readProcessInterleaved_
566 :: MonadIO m
567 => ProcessConfig stdin stdoutIgnored stderrIgnored
568 -- ^
569 -> m L.ByteString
570 -- ^
571 readProcessInterleaved_ pc =
572 liftIO $
573 withProcessInterleave pc $ \p -> atomically $ do
574 stdout' <- getStdout p
575 checkExitCodeSTM p `catchSTM` \ece -> throwSTM ece
576 { eceStdout = stdout'
577 }
578 return stdout'
579
580 -- | Run the given process, wait for it to exit, and returns its
581 -- 'ExitCode'.
582 --
583 -- @since 0.1.0.0
584 runProcess :: MonadIO m
585 => ProcessConfig stdin stdout stderr
586 -- ^
587 -> m ExitCode
588 -- ^
589 runProcess pc = liftIO $ withProcess pc waitExitCode
590
591 -- | Same as 'runProcess', but instead of returning the
592 -- 'ExitCode', checks it with 'checkExitCode'.
593 --
594 -- @since 0.1.0.0
595 runProcess_ :: MonadIO m
596 => ProcessConfig stdin stdout stderr
597 -- ^
598 -> m ()
599 runProcess_ pc = liftIO $ withProcess pc checkExitCode
600
601 -- | Wait for the process to exit and then return its 'ExitCode'.
602 --
603 -- @since 0.1.0.0
604 waitExitCode :: MonadIO m => Process stdin stdout stderr -> m ExitCode
605 waitExitCode = liftIO . atomically . waitExitCodeSTM
606
607 -- | Same as 'waitExitCode', but in 'STM'.
608 --
609 -- @since 0.1.0.0
610 waitExitCodeSTM :: Process stdin stdout stderr -> STM ExitCode
611 waitExitCodeSTM = readTMVar . pExitCode
612
613 -- | Check if a process has exited and, if so, return its 'ExitCode'.
614 --
615 -- @since 0.1.0.0
616 getExitCode :: MonadIO m => Process stdin stdout stderr -> m (Maybe ExitCode)
617 getExitCode = liftIO . atomically . getExitCodeSTM
618
619 -- | Same as 'getExitCode', but in 'STM'.
620 --
621 -- @since 0.1.0.0
622 getExitCodeSTM :: Process stdin stdout stderr -> STM (Maybe ExitCode)
623 getExitCodeSTM = tryReadTMVar . pExitCode
624
625 -- | Wait for a process to exit, and ensure that it exited
626 -- successfully. If not, throws an 'ExitCodeException'.
627 --
628 -- Exceptions thrown by this function will not include stdout or stderr (This prevents unbounded memory usage from reading them into memory).
629 -- However, some callers such as 'readProcess_' catch the exception, add the stdout and stderr, and rethrow.
630 --
631 -- @since 0.1.0.0
632 checkExitCode :: MonadIO m => Process stdin stdout stderr -> m ()
633 checkExitCode = liftIO . atomically . checkExitCodeSTM
634
635 -- | Same as 'checkExitCode', but in 'STM'.
636 --
637 -- @since 0.1.0.0
638 checkExitCodeSTM :: Process stdin stdout stderr -> STM ()
639 checkExitCodeSTM p = do
640 ec <- readTMVar (pExitCode p)
641 case ec of
642 ExitSuccess -> return ()
643 _ -> throwSTM $ exitCodeExceptionNoOutput p ec
644
645 -- | Returns the PID (process ID) of a subprocess.
646 --
647 -- 'Nothing' is returned if the underlying 'P.ProcessHandle' was already closed.
648 -- Otherwise a PID is returned that remains valid as long as the handle is
649 -- open. The operating system may reuse the PID as soon as the last handle to
650 -- the process is closed.
651 --
652 -- @since 0.2.12.0
653 getPid :: Process stdin stdout stderr -> IO (Maybe P.Pid)
654 getPid = P.getPid . pHandle
655
656 -- | Internal
657 clearStreams :: ProcessConfig stdin stdout stderr -> ProcessConfig () () ()
658 clearStreams pc = pc
659 { pcStdin = inherit
660 , pcStdout = inherit
661 , pcStderr = inherit
662 }
663
664 -- | Get the child's standard input stream value.
665 --
666 -- @since 0.1.0.0
667 getStdin :: Process stdin stdout stderr -> stdin
668 getStdin = pStdin
669
670 -- | Get the child's standard output stream value.
671 --
672 -- @since 0.1.0.0
673 getStdout :: Process stdin stdout stderr -> stdout
674 getStdout = pStdout
675
676 -- | Get the child's standard error stream value.
677 --
678 -- @since 0.1.0.0
679 getStderr :: Process stdin stdout stderr -> stderr
680 getStderr = pStderr
681
682 -- | Get a process's configuration.
683 --
684 -- This is useful for constructing 'ExitCodeException's.
685 --
686 -- Note that the stdin, stdout, and stderr streams are stored in the 'Process',
687 -- not the 'ProcessConfig', so the returned 'ProcessConfig' will always have
688 -- empty stdin, stdout, and stderr values.
689 --
690 -- @since 0.2.12.0
691 getProcessConfig :: Process stdin stdout stderr -> ProcessConfig () () ()
692 getProcessConfig = pConfig
693
694 -- | Take 'System.Process.ProcessHandle' out of the 'Process'.
695 -- This method is needed in cases one need to use low level functions
696 -- from the @process@ package. Use cases for this method are:
697 --
698 -- 1. Send a special signal to the process.
699 -- 2. Terminate the process group instead of terminating single process.
700 -- 3. Use platform specific API on the underlying process.
701 --
702 -- This method is considered unsafe because the actions it performs on
703 -- the underlying process may overlap with the functionality that
704 -- @typed-process@ provides. For example the user should not call
705 -- 'System.Process.waitForProcess' on the process handle as either
706 -- 'System.Process.waitForProcess' or 'stopProcess' will lock.
707 -- Additionally, even if process was terminated by the
708 -- 'System.Process.terminateProcess' or by sending signal,
709 -- 'stopProcess' should be called either way in order to cleanup resources
710 -- allocated by the @typed-process@.
711 --
712 -- @since 0.1.1
713 unsafeProcessHandle :: Process stdin stdout stderr -> P.ProcessHandle
714 unsafeProcessHandle = pHandle
715
716 -- | Get an 'ExitCodeException' containing the process's stdout and stderr data.
717 --
718 -- Note that this will call 'waitExitCode' to block until the process exits, if
719 -- it has not exited already.
720 --
721 -- Unlike 'checkExitCode' and similar, this will return an 'ExitCodeException'
722 -- even if the process exits with 'ExitSuccess'.
723 --
724 -- @since 0.2.12.0
725 exitCodeExceptionWithOutput :: MonadIO m
726 => Process stdin (STM L.ByteString) (STM L.ByteString)
727 -> m ExitCodeException
728 exitCodeExceptionWithOutput process = liftIO $ atomically $ do
729 exitCode <- waitExitCodeSTM process
730 stdout <- getStdout process
731 stderr <- getStderr process
732 pure ExitCodeException
733 { eceExitCode = exitCode
734 , eceProcessConfig = pConfig process
735 , eceStdout = stdout
736 , eceStderr = stderr
737 }
738
739 -- | Get an 'ExitCodeException' containing no data other than the exit code and
740 -- process config.
741 --
742 -- Unlike 'checkExitCode' and similar, this will return an 'ExitCodeException'
743 -- even if the process exits with 'ExitSuccess'.
744 --
745 -- @since 0.2.12.0
746 exitCodeExceptionNoOutput :: Process stdin stdout stderr
747 -> ExitCode
748 -> ExitCodeException
749 exitCodeExceptionNoOutput process exitCode =
750 ExitCodeException
751 { eceExitCode = exitCode
752 , eceProcessConfig = pConfig process
753 , eceStdout = L.empty
754 , eceStderr = L.empty
755 }
756