MissingH API ManualContentsIndex
MissingH.Cmd
Portability portable to platforms with POSIX process/signal tools
Stability provisional
Maintainer jgoerzen@complete.org
Contents
High-Level Tools
Piping with lazy strings
Piping with handles
Low-Level Tools
Description

Command invocation utilities.

Written by John Goerzen, jgoerzen@complete.org

Please note: Most of this module is not compatible with Hugs.

Command lines executed will be logged using MissingH.Logging.Logger at the DEBUG level. Failure messages will be logged at the WARNING level in addition to being raised as an exception. Both are logged under "MissingH.Cmd.funcname" -- for instance, "MissingH.Cmd.safeSystem". If you wish to suppress these messages globally, you can simply run:

 updateGlobalLogger "MissingH.Cmd.safeSystem"
                     (setLevel CRITICAL)

See also: updateGlobalLogger, MissingH.Logging.Logger.

It is possible to set up pipelines with these utilities. Example:

 (pid1, x1) <- pipeFrom "ls" ["/etc"]
 (pid2, x2) <- pipeBoth "grep" ["x"] x1
 putStr x2
 ... the grep output is displayed ...
 forceSuccess pid2
 forceSuccess pid1

Remember, when you use the functions that return a String, you must not call forceSuccess until after all data from the String has been consumed. Failure to wait will cause your program to appear to hang.

Here is an example of the wrong way to do it:

 (pid, x) <- pipeFrom "ls" ["/etc"]
 forceSuccess pid         -- Hangs; the called program hasn't terminated yet
 processTheData x

You must instead process the data before calling forceSuccess.

When using the hPipe family of functions, this is probably more obvious.

Synopsis
data PipeHandle = PipeHandle {
processID :: ProcessID
phCommand :: FilePath
phArgs :: [String]
phCreator :: String
}
safeSystem :: FilePath -> [String] -> IO ()
forceSuccess :: PipeHandle -> IO ()
pipeFrom :: FilePath -> [String] -> IO (PipeHandle, String)
pipeLinesFrom :: FilePath -> [String] -> IO (PipeHandle, [String])
pipeTo :: FilePath -> [String] -> String -> IO PipeHandle
pipeBoth :: FilePath -> [String] -> String -> IO (PipeHandle, String)
hPipeFrom :: FilePath -> [String] -> IO (PipeHandle, Handle)
hPipeTo :: FilePath -> [String] -> IO (PipeHandle, Handle)
hPipeBoth :: FilePath -> [String] -> IO (PipeHandle, Handle, Handle)
data PipeMode
= ReadFromPipe
| WriteToPipe
pOpen :: PipeMode -> FilePath -> [String] -> (Handle -> IO a) -> IO a
pOpen3 :: Maybe Fd -> Maybe Fd -> Maybe Fd -> FilePath -> [String] -> (ProcessID -> IO a) -> IO () -> IO a
High-Level Tools
data PipeHandle
Return value from pipeFrom, pipeLinesFrom, pipeTo, or pipeBoth. Contains both a ProcessID and the original command that was executed. If you prefer not to use forceSuccess on the result of one of these pipe calls, you can use (processID ph), assuming ph is your PipeHandle, as a parameter to getProcessStatus.
Constructors
PipeHandle
processID :: ProcessID
phCommand :: FilePath
phArgs :: [String]
phCreator :: StringFunction that created it
Instances
Eq PipeHandle
Show PipeHandle
safeSystem :: FilePath -> [String] -> IO ()
Invokes the specified command in a subprocess, waiting for the result. If the command terminated successfully, return normally. Otherwise, raises a userError with the problem.
forceSuccess :: PipeHandle -> IO ()

Uses getProcessStatus to obtain the exit status of the given process ID. If the process terminated normally, does nothing. Otherwise, raises an exception with an appropriate error message.

This call will block waiting for the given pid to terminate.

Piping with lazy strings
pipeFrom :: FilePath -> [String] -> IO (PipeHandle, String)

Read data from a pipe. Returns a lazy string and a PipeHandle.

ONLY AFTER the string has been read completely, You must call either getProcessStatus or forceSuccess on the PipeHandle. Zombies will result otherwise.

pipeLinesFrom :: FilePath -> [String] -> IO (PipeHandle, [String])

Like pipeFrom, but returns data in lines instead of just a String. Shortcut for calling lines on the result from pipeFrom.

Note: this function logs as pipeFrom.

pipeTo :: FilePath -> [String] -> String -> IO PipeHandle

Write data to a pipe. Returns a ProcessID.

You must call either getProcessStatus or forceSuccess on the ProcessID. Zombies will result otherwise.

pipeBoth :: FilePath -> [String] -> String -> IO (PipeHandle, String)

Like a combination of pipeTo and pipeFrom; forks an IO thread to send data to the piped program, and simultaneously returns its output stream.

The same note about checking the return status applies here as with pipeFrom.

Piping with handles
hPipeFrom :: FilePath -> [String] -> IO (PipeHandle, Handle)

Read data from a pipe. Returns a Handle and a PipeHandle.

When done, you must hClose the handle, and then use either forceSuccess or getProcessStatus on the PipeHandle. Zomeibes will result otherwise.

This function logs as pipeFrom.

hPipeTo :: FilePath -> [String] -> IO (PipeHandle, Handle)

Write data to a pipe. Returns a PipeHandle and a new Handle to write to.

When done, you must hClose the handle, and then use either forceSuccess or getProcessStatus on the PipeHandle. Zomeibes will result otherwise.

This function logs as pipeTo.

hPipeBoth :: FilePath -> [String] -> IO (PipeHandle, Handle, Handle)

Like a combination of hPipeTo and hPipeFrom; returns a 3-tuple of (PipeHandle, Data From Pipe, Data To Pipe).

When done, you must hClose both handles, and then use either forceSuccess or getProcessStatus on the PipeHandle. Zomeibes will result otherwise.

Hint: you will usually need to ForkIO a thread to handle one of the Handles; otherwise, deadlock can result.

This function logs as pipeBoth.

Low-Level Tools
data PipeMode
Constructors
ReadFromPipe
WriteToPipe
pOpen :: PipeMode -> FilePath -> [String] -> (Handle -> IO a) -> IO a

Open a pipe to the specified command.

Passes the handle on to the specified function.

The PipeMode specifies what you will be doing. That is, specifing ReadFromPipe sets up a pipe from stdin, and WriteToPipe sets up a pipe from stdout.

pOpen3
:: Maybe FdSend stdin to this fd
-> Maybe FdGet stdout from this fd
-> Maybe FdGet stderr from this fd
-> FilePathCommand to run
-> [String]Command args
-> (ProcessID -> IO a)Action to run in parent
-> IO ()Action to run in child before execing (if you don't need something, set this to return ()) -- IGNORED IN HUGS
-> IO a
Runs a command, redirecting things to pipes.
Produced by Haddock version 0.6