|
|
|
|
Synopsis |
|
setFileMode' :: FilePath -> FileMode -> IO () | | subproc :: IO a -> IO () | | call :: IO a -> IO () | | spawn :: IO a -> IO ProcessID | | spawn_loc :: String -> IO a -> IO ProcessID | | run :: FilePath -> [String] -> IO () | | data RunError = RunError {} | | show_runerror :: RunError -> String | | explain_processstatus :: ProcessStatus -> String | | to_ioe :: RunError -> IOError | | as_ioe :: IO a -> IO a | | runprog :: FilePath -> [String] -> IO () | | echo :: (FilePath -> [String] -> IO ()) -> FilePath -> [String] -> IO () | | exec :: String -> [String] -> IO a | | execp :: String -> [String] -> IO a | | exece :: String -> [String] -> [(String, String)] -> IO a | | execpe :: String -> [String] -> [(String, String)] -> IO a | | (-|-) :: IO a -> IO b -> IO a | | (=|-) :: IO a -> IO b -> IO a | | (-|=) :: IO a -> IO b -> IO b | | (=|=) :: IO a -> IO b -> IO b | | redirect :: Handle -> Handle -> IO a -> IO a | | (->-) :: IO a -> FilePath -> IO a | | (->>-) :: IO a -> FilePath -> IO a | | (=>-) :: IO a -> FilePath -> IO a | | (=>>-) :: IO a -> FilePath -> IO a | | (-&>-) :: IO a -> FilePath -> IO a | | (-&>>-) :: IO a -> FilePath -> IO a | | (-<-) :: IO a -> FilePath -> IO a | | err_to_out :: IO a -> IO a | | out_to_err :: IO a -> IO a | | pipe_fork_dup :: IO a -> Bool -> Bool -> Bool -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessID) | | pipe_to :: String -> IO a -> IO () | | h_pipe_to :: IO a -> IO (Handle, ProcessID) | | pipe_from :: IO a -> IO String | | pipe_from2 :: IO a -> IO (String, ProcessStatus) | | h_pipe_from :: IO a -> IO (Handle, ProcessID) | | h_pipe_from2 :: IO a -> IO (Handle, ProcessID) | | lazy_pipe_from :: IO a -> IO (String, ProcessID) | | lazy_pipe_from2 :: IO a -> IO (String, ProcessID) | | pipes :: IO a -> Bool -> Bool -> Bool -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessID) | | _exit :: Int -> IO a | | strerror :: Errno -> IO String | | errno :: IO Errno | | perror' :: Errno -> String -> IO () | | perror :: String -> IO () | | failIO :: String -> IO a | | exitcode :: IO () -> IO ExitCode | | throwErrno' :: String -> Maybe Handle -> Maybe FilePath -> IO a | | show_ioerror :: IOError -> String | | system_throw :: String -> IO () | | system_runprog :: String -> IO () | | silently :: IORef String -> IO () -> IO () | | child :: IO a -> IO b | | isatty :: Handle -> IO Bool | | outm :: String -> IO () | | outm_ :: String -> IO () | | logm :: String -> IO () | | logm_ :: String -> IO () | | errm :: String -> IO () | | errm_ :: String -> IO () | | fill_in_filename :: String -> IO a -> IO a | | fill_in_location :: String -> IO a -> IO a | | add_location :: String -> IO a -> IO a | | execute_file :: FilePath -> Bool -> [String] -> Maybe [(String, String)] -> IO a | | hDuplicateTo :: Handle -> Handle -> IO () | | flushBuffer :: Handle__ -> IO () | | dEFAULT_BUFFER_SIZE :: Int | | receive_ioerror :: Fd -> IO (Maybe IOError) | | decode_ioerror :: String -> Maybe IOError | | c_close_on_exec :: CInt -> IO CInt | | fork :: IO CInt | | _exit_prim :: CInt -> IO () | | foreign_strerror :: CInt -> Ptr CChar | | hssh_c_isatty :: CInt -> IO CInt | | c_save_fdflags :: IO (Ptr CInt) | | c_prepare_fd_flags_for_exec :: IO () | | c_restore_fdflags :: Ptr CInt -> IO () | | c_fcntl_dupfd :: CInt -> CInt -> IO CInt | | close :: CInt -> IO CInt | | dup2 :: CInt -> CInt -> IO CInt |
|
|
Documentation |
|
setFileMode' :: FilePath -> FileMode -> IO () |
Improved version of System.Posix.Files.setFileMode, which sets the file name in the IOError which is thrown in case of an error. The
implementation in GHC 6.2.2 neglects to do this.
setFileMode' path mode =
fill_in_filename path $
setFileMode path mode
|
|
subproc |
:: | | => IO a | Action to execute in a child process
| -> IO () | | Execute an IO action as a separate process, and wait for it to finish.
Report errors as exceptions.
The program forks a child process and performs the specified action.
Then it waits for the child process to finish. If it exits in any way
which indicates an error, the ProcessStatus is thrown as an
exception.
When the action throws an IOError, it is transmitted to the parent.
It is then raised there, as if it happened locally. The child then aborts
quietly with an exit code of 0.
When used in conjunction with an exec variant, this means that the parent
process can tell the difference between failure of the exec call itself,
and failure of the program being executed. You get the IOError, which
happened in the child when calling executeFile (GHC hierarchical
libraries). Of course, the action can prevent this form happening, by
itself catching IOErrors.
The parent process waits for the child process, if it has been stopped by a
signal.
See HsShellScript for further details.
Examples:
Run a program with the environment replaced:
subproc (execpe "foobar" ["1","2","3"] new_env)
This results in a ProcessStatus exception:
subproc (exec "/bin/false" [])
This results in an IOError (unless you actually have /frooble):
subproc (exec "/frooble" [])
See runprog, spawn, exec, execp, exece, execpe.
|
|
|
call |
:: | | => IO a | action to execute as a child process
| -> IO () | | Execute an IO action as a separate process, and wait for it to finish.
Report errors as exceptions.
This function is included only for backwards compatibility. New code should
use subproc instead, which has better error handling.
The program forks a child process and performs the specified action.
Then it waits for the child process to finish. If it exits in any way
which indicates an error, the ProcessStatus is thrown.
The parent process waits for the child processes, which have been stopped by
a signal.
See HsShellScript for further details.
See subproc, spawn.
|
|
|
spawn |
:: | | => IO a | Action to execute as a child process.
| -> IO ProcessID | Process ID of the new process.
| Execute an IO action as a separate process, and continue without waiting
for it to finish.
The program forks a child process, which performs the specified action and terminates.
The child's process ID is returned.
See HsShellScript for further details.
See subproc.
|
|
|
spawn_loc :: String -> IO a -> IO ProcessID |
|
run |
:: FilePath | Name of the executable to run
| -> [String] | Command line arguments
| -> IO () | | Run an external program. This starts a program as a child
process, and waits for it to finish. The executable is searched via the
PATH.
This function is included only for backwards compatibility. New code should
use runprog, which has much better error handling.
When the specified program can't be executed, an error message is printed, and the main process
gets a ProcessStatus thrown, with the value Exited
(ExitFailure 1). This means that the main program can't distinguish between
failure of calling the program and the program exiting with an exit code of
1. However, an error message "Error calling ...", including the description in the IOError produced
by the failed execp call, is printed on stderr.
run prog par is essentially call (execp prog par).
Example:
run "/usr/bin/foobar" ["some", "args"]
`catch` (\ps -> do -- oops...
)
See runprog, subproc, spawn.
|
|
|
data RunError |
An error which occured when calling an external program via runprog.
The fields specifiy the details of the call.
See show_runerror, to_ioe, as_ioe, System.Posix.ProcessStatus.
| Constructors | RunError | | re_prog :: String | Program name
| re_pars :: [String] | Program arguments
| re_env :: [(String, String)] | The environment in use when the call was done
| re_wd :: String | The working directory when the call was done
| re_ps :: ProcessStatus | The process status of the failure
|
|
| Instances | |
|
|
show_runerror :: RunError -> String |
Make a readable error message. This includes all the
fields of RunError except for the environment.
See RunError.
|
|
explain_processstatus :: ProcessStatus -> String |
Generate a human-readable description of a ProcessStatus.
See exec, runprog and System.Posix.ProcessStatus in the GHC hierarchical
library documentation.
|
|
to_ioe :: RunError -> IOError |
Convert a RunError to an IOError.
The IOError type isn't capable of holding all the information which is
contained in a RunError. The environment is left out, and most of the other
fields are included only informally, in the description.
The fields of the generated IOError are:
- ioe_handle: Nothing
- ioe_type: GHC.IOBase.SystemError
- ioe_location: "runprog"
- ioe_description: The error message, as procuded by show_runerror.
- ioe_filename: This is Just (shell_command prog pars), with prog
and pars being the program and its arguments.
See as_ioe, runprog, show_runerror.
|
|
as_ioe :: IO a -> IO a |
Call the specified IO action (which is expected to contain calls of
runprog) and convert any RunError exceptions to IOErrors.
The conversion is done by to_ioe.
See to_ioe, runprog.
|
|
runprog |
:: FilePath | Name of the executable to run
| -> [String] | Command line arguments
| -> IO () | | Run an external program, and report errors as exceptions. The executable is
searched via the PATH.
In case the program exits in an way which indicates an error, or is
terminated by a signal, a RunError is thrown. It
contains the details of the call. The runprog action can also be converted
to throw IOErrors instaed, by applying as_ioe to it. Either can be used
to generate an informative error message.
In case of starting the program itself failed, an IOError is thrown.
runprog prog par is essentially subproc (execp prog par).
Example 1:
do runprog "foo" ["some", "args"]
...
`catch` (\re -> do errm (show_runerror re)
...
)
Example 2:
do as_ioe $ runprog "foo" ["some", "args"]
...
`catch` (\ioe -> do errm (show_ioerror ioe)
...
)
See subproc, spawn, RunError, show_runerror, to_ioe, as_ioe.
|
|
|
echo |
:: FilePath -> [String] -> IO () | Action to perform
| -> FilePath | Name or path of the executable to run
| -> [String] | Command line arguments
| -> IO () | | Print an action as a shell command, then perform it.
This is used with actions such as runprog, exec or subproc. For instance,
echo runprog prog args is a variant of runprog prog args, which prints what
is being done before doing it.
See runprog, subproc, exec.
|
|
|
exec |
:: | | => String | Full path to the executable
| -> [String] | Command line arguments
| -> IO a | Never returns
| Execute an external program. This replaces the running process. The path isn't searched, the environment isn't changed. In case of failure,
an IOError is thrown.
exec path args =
execute_file path False args Nothing
See execute_file, HsShellScript.
|
|
|
execp |
:: | | => String | Name or path of the executable
| -> [String] | Command line arguments
| -> IO a | Never returns
| Execute an external program. This replaces the running process. The path is searched, the environment isn't changed. In case of failure,
an IOError is thrown.
execp prog args =
execute_file prog True args Nothing
See execute_file, HsShellScript.
|
|
|
exece |
:: | | => String | Full path to the executable
| -> [String] | Command line arguments
| -> [(String, String)] | New environment
| -> IO a | Never returns
| Execute an external program. This replaces the running process. The path isn't searched, the environment of the program is set as specified. In
case of failure, an IOError is thrown.
exece path args env =
execute_file path False args (Just env)
See execute_file, HsShellScript.
|
|
|
execpe |
:: | | => String | Name or path of the executable
| -> [String] | Command line arguments
| -> [(String, String)] | New environment
| -> IO a | Never returns
| Execute an external program. This replaces the running process. The path is searched, the environment of the program is set as specified. In
case of failure, an IOError is thrown.
execpe prog args env =
execute_file prog True args (Just env)
See execute_file, HsShellScript.
|
|
|
(-|-) |
:: | | => IO a | Action which won't be forked
| -> IO b | Action which will be forked and connected with a pipe
| -> IO a | Result action
| Build left handed pipe of stdout.
"p -|- q" builds an IO action from the two IO actions p and q.
q is executed in an external process. The standard output of p is sent
to the standard input of q through a pipe. The result action consists
of forking off q (connected with a pipe), and p.
The result action does not run p in a separate process. So, the pipe
itself can be seen as a modified action p, forking a connected q. The
pipe is called "left handed", because p remains unforked, and not q.
The exit code of q is silently ignored. The process ID of the forked
copy of q isn't returned to the caller, so it's lost.
See HsShellScript and
HsShellScript for further details.
Examples:
call (exec "/usr/bin/foo" [] -|- exec "/usr/bin/bar" [])
call ( execp "foo" ["..."]
-|= ( -- Do something with foo's output
do cnt <- lazy_contents "-"
...
)
)
See subproc, '(=|-)', '(-|=)'.
|
|
|
(=|-) |
:: | | => IO a | Action which won't be forked
| -> IO b | Action which will be forked and connected with a pipe
| -> IO a | Result action
| Build left handed pipe of stderr.
"p =|- q" builds an IO action from the two IO actions p and q.
q is executed in an external process. The standard error output of p is sent
to the standard input of q through a pipe. The result action consists
of forking off q (connected with a pipe), and p.
The result action does not run p in a separate process. So, the pipe
itself can be seen as a modified action p, forking a connected q. The
pipe is called "left handed", because p has this property, and not q.
The exit code of q is silently ignored. The process ID of the forked
copy of q isn't returned to the caller, so it's lost.
See HsShellScript and
HsShellScript for further details.
Example:
call (exec "/usr/bin/foo" [] =|- exec "/usr/bin/bar" [])
See subproc, '(-|-)', '(-|=)'.
|
|
|
(-|=) |
:: | | => IO a | Action which will be forked and connected with a pipe
| -> IO b | Action which won't be forked
| -> IO b | Result action
| Build right handed pipe of stdout.
"p -|= q" builds an IO action from the two IO actions p and q.
p is executed in an external process. The standard output of p is sent
to the standard input of q through a pipe. The result action consists
of forking off p (connected with a pipe), and q.
The result action does not run q in a separate process. So, the pipe
itself can be seen as a modified action q, forking a connected p.
The pipe is called "right
handed", because q has this property, and not p.
The exit code of p is silently ignored. The process ID of the forked
copy of q isn't returned to the caller, so it's lost.
See HsShellScript and
HsShellScript for further details.
Example:
@call (exec \"\/usr\/bin\/foo\" [] -|= exec \"\/usr\/bin\/bar\" [])@
See subproc, '(=|-)', '(=|=)'.
|
|
|
(=|=) |
:: | | => IO a | Action which will be forked and connected with a pipe
| -> IO b | Action which won't be forked
| -> IO b | Result action
| Build right handed pipe of stderr.
"p =|= q" builds an IO action from the two IO actions p and q.
p is executed in an external process. The standard error output of p is sent
to the standard input of q through a pipe. The result action consists
of forking off p (connected with a pipe), and q.
The result action does not run q in a separate process. So, the pipe
itself can be seen as a modified action q, forking a connected p.
The pipe is called "right
handed", because q has this property, and not p.
The exit code of p is silently ignored. The process ID of the forked
copy of q isn't returned to the caller, so it's lost.
See HsShellScript and
HsShellScript for further details.
Example:
call (exec "/usr/bin/foo" [] =|= exec "/usr/bin/bar" [])
See subproc, =|-, -|=.
|
|
|
redirect |
:: | | => Handle | Handle to replace
| -> Handle | Handle to replace it with
| -> IO a | Action
| -> IO a | | Temporarily replace a handle. This makes a backup copy of the original handle (typically a standard handle), overwrites it with the specified one,
runs the specified action, and restores the handle from the backup.
Example:
h <- openFile "/tmp/log" WriteMode
redirect stdout h io
hClose h
This is the same as
io ->- "/tmp/log"
See -|-, =|-.
|
|
|
(->-) |
:: | | => IO a | Action, whose output will be redirected
| -> FilePath | File to redirect the output to
| -> IO a | Result action
| Redirect the standard output of the specified IO action to a file. The file will be overwritten, if it already exists.
What's actually modified is the stdout handle, not the file descriptor 1. The
exec functions know about this. See HsShellScript and
HsShellScript for details.
Example:
run "/some/program" [] ->- "/tmp/output"
Note: You can't redirect to "/dev/null" this way, because GHC 6.4's openFile throws an "invalid argument"
IOError. (This may be a bug in the GHC 6.4 libraries). Use ->>- instead.
See subproc, runprog, ->>-, =>-.
|
|
|
(->>-) |
:: | | => IO a | Action, whose output will be redirected
| -> FilePath | File to redirect the output to
| -> IO a | Result action
| Redirect the standard output of the specified IO action to a file. If the file already exists, the output will be appended.
What's actually modified is the stdout handle, not the file descriptor 1. The
exec functions know about this. See HsShellScript and
HsShellScript for details.
Example:
run "/some/noisy/program" [] ->>- "/dev/null"
See subproc, runprog, '(->-)', '(=>>-)'.
|
|
|
(=>-) |
:: | | => IO a | Action, whose error output will be redirected
| -> FilePath | File to redirect the error output to
| -> IO a | Result action
| Redirect the standard error output of the specified IO action to a file. If the file already exists, it will be overwritten.
What's actually modified is the stderr handle, not the file descriptor 2. The
exec functions know about this. See HsShellScript and
HsShellScript for details.
Note: You can't redirect to "/dev/null" this way, because GHC 6.4's openFile throws an "invalid argument"
IOError. (This may be a bug in the GHC 6.4 libraries). Use =>>- instead.
Example:
run "/path/to/foo" [] =>- "/tmp/errlog"
See subproc, runprog, '(->-)', '(=>>-)'.
|
|
|
(=>>-) |
:: | | => IO a | Action, whose error output will be redirected
| -> FilePath | File to redirect the error output to
| -> IO a | Result action
| Redirect the standard error output of the specified IO action to a file. If the file already exists, the output will be appended.
What's actually modified is the stderr handle, not the file descriptor 2. The
exec functions know about this. See HsShellScript and
HsShellScript for details.
Example:
run "/some/program" [] =>>- "/dev/null"
See subproc, runprog, '(->>-)', '(=>-)'.
|
|
|
(-&>-) |
:: | | => IO a | Action, whose output and error output will be redirected
| -> FilePath | File to redirect to
| -> IO a | Result action
| Redirect both stdout and stderr to a file. This is equivalent to the
shell's &> operator. If the file already exists, it will be overwritten.
What's actually modified are the stdout and stderr handles, not the file
descriptors 1 and 2. The exec functions know about this. See
HsShellScript and
HsShellScript for details.
Note: You can't redirect to "/dev/null" this way, because GHC 6.4's openFile throws an "invalid argument"
IOError. (This may be a bug in the GHC 6.4 libraries). Use -&>>- instead.
(-&>-) io path = err_to_out io ->- path
Example:
call (exec "/path/to/foo" [] -&>- "log") See '(-&>>-)', err_to_out.
|
|
|
(-&>>-) |
:: | | => IO a | Action, whose output and error output will be redirected
| -> FilePath | File to redirect to
| -> IO a | Result action
| Redirect both stdout and stderr to a file. If the file already exists, the
output will be appended.
What's actually modified are the stdout and stderr handles, not the file
descriptors 1 and 2. The exec functions know about this. See
HsShellScript and
HsShellScript for details.
(-&>>-) io path = (err_to_out >> io) ->>- path
Example:
run "/some/noisy/program" [] -&>>- "/dev/null"
See '(-&>-)', out_to_err.
|
|
|
(-<-) :: IO a -> FilePath -> IO a |
Redirect stdin from a file. This modifies the specified action, such
that the standard input is read from a file.
What's actually modified is the stdin handle, not the file
descriptor 0. The exec functions know about this. See
HsShellScript and
HsShellScript for details.
Example:
call (exec "/path/to/foo" [] -<- "bar") See exec, runprog, '(->-)', '(=>-)'.
|
|
err_to_out :: IO a -> IO a |
Send the error output of the specified action to its standard output.
What's actually modified is the stdout handle, not the file descriptor 1. The
exec functions know about this. See HsShellScript and
HsShellScript for details.
err_to_out = redirect stderr stdout
See redirect.
|
|
out_to_err :: IO a -> IO a |
Send the output of the specified action to its standard error output.
What's actually modified is the stderr handle, not the file descriptor 2. The
exec functions know about this. See HsShellScript and
HsShellScript for details.
redirect stdout stderr
See redirect.
|
|
pipe_fork_dup :: IO a -> Bool -> Bool -> Bool -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessID) |
|
pipe_to |
:: | | => String | Text to pipe
| -> IO a | Action to run as a separate process, and to pipe to
| -> IO () | | Run an IO action as a separate process, and pipe some text to its stdin.
Then close the pipe and wait for the child process to finish. If it
exits in a way which indicates an error, the ProcessStatus is thrown.
Example: pipe_to "blah" $ exec "/usr/bin/foo" ["bar"]
See subproc, runprog, -<-, h_pipe_to. See HsShellScript for more details.
|
|
|
h_pipe_to |
:: | | => IO a | Action to run as a separate process, and to pipe to
| -> IO (Handle, ProcessID) | Returns handle connected to the standard input of the child process, and the child's process ID
| Run an IO action as a separate process, and connect to its stdin
with a pipe.
Example: h <- h_pipe_to $ exec "/usr/bin/foo" ["bar"]
See -<-, pipe_to, pipe_from, pipe_from2. See HsShellScript for more details.
|
|
|
pipe_from |
:: | | => IO a | Action to run as a separate process
| -> IO String | The called program's standard output
| Run an IO action as a separate process, and read its stdout
strictly. Then wait for the child process to finish. This is like the
backquote feature of shells.
If the child process exits with a non-zero exit code, the
ProcessStatus is thrown.
The whole output is returned, no trailing newline character is removed, like the shell does with backquotes. You may want to apply chomp
to the result.
Example:
output <- pipe_from $ exec "/bin/foo" ["bar"]
See exec, pipe_to, pipe_from2, h_pipe_from, lazy_pipe_from, chomp, silently. See HsShellScript for more details.
|
|
|
pipe_from2 |
:: | | => IO a | Action to run as a separate process
| -> IO (String, ProcessStatus) | The called program's standard output
| Run an IO action as a separate process, and read its stderr
strictly. Then wait for the child process to finish, and return the text
along with its exit code.
Example:
(errmsg, ec) <- pipe_from2 $ exec "/bin/foo" ["bar"] ->- "/dev/null"
when (ec /= Exited ExitSuccess) $ do
errm errmsg
...
See exec, pipe_to, pipe_from, h_pipe_from2, lazy_pipe_from2, silently. See HsShellScript for more details.
|
|
|
h_pipe_from |
:: | | => IO a | Action to run as a separate process, and to pipe from
| -> IO (Handle, ProcessID) | Returns handle connected to the standard output of the child process, and the child's process ID
| Run an IO action as a separate process, and connect to its stdout
with a pipe.
A handle connected to the child process, and the process ID
of the child are returned. The process ID can be used with
System.Posix.getProcessStatus to get the child's exit code. You must either
ensure that all data has been read, or close the handle, before calling
getProcessStatus blockingly. Otherwise you'll get a deadlock. When you
close the handle before all data has been read, then the child gets a
SIGPIPE signal.
Example:
h <- h_pipe_from $ exec "/usr/bin/foo" ["bar"]
See exec, pipe_to, h_pipe_from2, pipe_from, lazy_pipe_from, chomp, silently. See HsShellScript for more details.
|
|
|
h_pipe_from2 |
:: | | => IO a | Action to run as a separate process, and to pipe from
| -> IO (Handle, ProcessID) | Returns handle connected to the standard output of the child process, and the child's process ID
| Run an IO action as a separate process, and connect to its stderr
with a pipe.
A handle connected to the child process' standard error output, and the process ID
of the child are returned. The process ID can be used with
System.Posix.getProcessStatus to get the child's exit code. You must either
ensure that all data has been read, or close the handle, before calling
getProcessStatus blockingly. Otherwise you'll get a deadlock. When you
close the handle before all data has been read, then the child gets a
SIGPIPE signal. Of course, you can also use the process ID to kill the
child process.
Example:
h <- h_pipe_from2 $ exec "/usr/bin/foo" ["bar"]
See exec, pipe_to, h_pipe_from, pipe_from2, lazy_pipe_from2, chomp, silently. See HsShellScript for more details.
|
|
|
lazy_pipe_from |
:: | | => IO a | Action to run as a separate process
| -> IO (String, ProcessID) | The action's lazy output and the process ID of the child process
| Run an IO action as a separate process, and read its stdout,
This is like the backquote feature of shells. The output is read
lazily, as the returned string is evaluated.
The child's output along with its process ID are returned. The process ID can
be used with System.Posix.getProcessStatus to get the child process' exit
code. Be aware that you must evaluate the whole string, before calling
getProcessStatus blockingly, or you'll get a deadlock.
The whole output is returned, no trailing newline character is removed, like
the shell does with backquotes. You'll possibly want to apply chomp to the
result.
Example:
(txt, pid) <- lazy_pipe_from $ exec "/usr/bin/foo" ["bar"]
...
-- Done, but must read the rest of the output
seq (length txt) (return ())
(Just ps) <- getProcessStatus True False pid
See exec, pipe_to, pipe_from, h_pipe_from, lazy_pipe_from2, silently. See HsShellScript for more details.
|
|
|
lazy_pipe_from2 |
:: | | => IO a | Action to run as a separate process
| -> IO (String, ProcessID) | The action's lazy output and the process ID of the child process
| Run an IO action as a separate process, and read its stderr. The output
is read lazily, as the returned string is evaluated.
The child's error output along with its process ID are returned. The process
ID can be used with System.Posix.getProcessStatus to get the child process'
exit code. Be aware that you must evaluate the whole string, before calling
getProcessStatus blockingly, or you'll get a deadlock.
Example:
(errmsg, pid) <- lazy_pipe_from2 $ exec "/usr/bin/foo" ["bar"] ->- "/dev/null"
...
-- Read enough error messages, terminate the child.
signalProcess killProcess pid
-- Make sure the file descriptor gets closed, or you may run out of file descriptors.
seq (length errmsg) (return ())
See exec, pipe_to, pipe_from2, h_pipe_from2, lazy_pipe_from, silently. See HsShellScript for more details.
|
|
|
pipes |
:: | | => IO a | Action to run in a new process
| -> Bool | Whether to make stdin pipe
| -> Bool | Whether to make stdout pipe
| -> Bool | Whether to make stderr pipe
| -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessID) | Pipes to the new process's stdin, stdout and stderr, if applicable; and its process id.
| Run an IO action as a separate process, and optionally connect to its
stdin, its stdout and its stderr output with
pipes.
See pipe_from, pipe_from2, pipe_to.
|
|
|
_exit |
:: | | => Int | Exit code
| -> IO a | Never returns
| Forcibly terminate the program, circumventing normal program shutdown.
This is the _exit(2) system call. No cleanup actions installed with bracket
are performed, no data buffered by file handles is written out, etc.
|
|
|
strerror |
:: Errno | errno value
| -> IO String | Corresponding error message
| Generate an error message from an errno value. This is the POSIX
strerror system library function.
See the man page strerror(3).
|
|
|
errno |
:: IO Errno | errno value
| Read the global system error number. This is the POSIX errno value. This
function is redundant. Use Foreign.C.Error.getErrno instead.
|
|
|
perror' |
:: Errno | errno error number
| -> String | Text to precede the message, separated by ": "
| -> IO () | | Print error message corresponding to the specified errno error
number. This is similar to the POSIX system library function perror.
See the man page perror(3).
|
|
|
perror |
:: String | Text to precede the message, separated by ": "
| -> IO () | | Print error message corresponding to the global errno error
number. This is the same as the POSIX system library function perror.
See the man page perror(3).
|
|
|
failIO :: String -> IO a |
Print a message to stderr and exit with an exit code
indicating an error.
failIO msg = hPutStrLn stderr msg >> exitFailure
|
|
exitcode |
:: IO () | Action to modify
| -> IO ExitCode | Modified action
| Modify an IO action to return the exit code of a failed program call,
instead of throwing an exception.
This is used to modify the error reporting behaviour of an IO action which
uses 'run'/'runprog' or 'call'/'subproc'. When an external program exits with
an exit code which indicates an error, normally an exception is thrown. After
exitcode has been applied, the exit code is retruned instead.
The caught exceptions are RunError and ProcessStatus. Termination by a
signal is still reported by an exception, which is passed through.
Example: ec <- exitcode $ runprog "foo" ["bar"]
See runprog, subproc, run, call.
|
|
|
throwErrno' |
:: | | => String | Description of the location where the error occurs in the program
| -> Maybe Handle | Optional handle
| -> Maybe FilePath | Optional file name (for failing operations on files)
| -> IO a | | Create and throw an IOError from the current errno value, an optional handle and an optional file name.
This is an extended version of the Foreign.C.Error.throwErrno function
from the GHC libraries, which additionally allows to specify a handle and a file
name to include in the IOError thrown.
See Foreign.C.Error.throwErrno, Foreign.C.Error.errnoToIOError.
|
|
|
show_ioerror :: IOError -> String |
Convert an IOError to a string.
There is an instance declaration of IOError in Show in the GHC.IOBase library, but show_ioerror produces a more readable, and more
complete, message.
|
|
system_throw :: String -> IO () |
Call the shell to execute a command. In case of an error, throw the ProcessStatus (such as (Exited (ExitFailure ec))) as an exception.
This is like the Haskell standard library function system, except that error handling is brought in accordance with HsShellScript's scheme.
exitcode . system_throw is the same as the system function, except that when the called shell is terminated or stopped by a signal, this still
lead to the ProcessStatus being thrown. The Haskell library report says nothing about what happens in this case, when using the
system function.
system_throw cmd = run "/bin/sh" ["-c", "--", cmd]
This function is deprecated. You should rather use system_runprog, which provides for much better error reporting.
|
|
system_runprog :: String -> IO () |
Call the shell to execute a command. In case of an error, a RunError ist thrown.
This is like the Haskell standard library function system, except that error handling is brought in accordance with HsShellScript's scheme. (It is
not a front end to system.)
system_runprog cmd = runprog "/bin/sh" ["-c", "--", cmd]
Example: Call "foo" and report Errors as IOErrors, rather than RunErrors.
as_ioe $ system_runprog "foo" ["bar", "baz"]
See RunError, as_ioe
|
|
silently |
:: IORef String | A mutable variable, which gets the output (stdout and stderr) of the action appended.
| -> IO () | The IO action to run.
| -> IO () | | Run a subroutine as a child process, but don't let it produce any messages.
Read its stdout and stderr instead, and append it to the contents of a
mutable variable. The idea is that you can run some commands silently, and
report them and their messages to the user only when something goes wrong.
If the child process terminates in a way which indicates an error, then the
process status is thrown, in the same way as runprog does. If the subroutine
throws an (Exited ec) exception (of type ProcessStatus), such as thrown by
runprog, then the child process exits with the same exit code, such that the
parent process reports it to the caller, again as a ProcessStatus exception.
When the subroutine finishes, the child process is terminated with _exit 0.
When it throws an exception, an error message is printed and it is terminated
with _exit 1. See HsShellScript for details.
The standard output (and the standard error output) of the parent process are
flushed before the fork, such that no output appears twice.
Example:
let handler :: IORef String -> ProcessStatus -> IO ()
handler msgref ps = do hPutStrLn stderr ("Command failed with " ++ show ps ++ ". Actions so far: ")
msg <- readIORef msgref
hPutStrLn stderr msg
exitWith (ExitFailure 1)
msgref <- newIORef ""
do silently msgref $ do putStrLn "Now doing foobar:"
echo exec "/foo/bar" ["arguments"]
silently msgref $ echo exec "/bar/baz" ["arguments"]
`catch` (handler msgref)
See lazy_pipe_from, subproc, runprog, GHC.IOBase.IORef.
|
|
|
child :: IO a -> IO b |
Modify a subroutine action in order to make it suitable to run as a child
process.
This is used by functions like call, silently, pipe_to etc. The action
is executed. When it returns, the (child) process is terminated with _exit 0
(after flushing stdout), circumventing normal program shutdown. When it
throws an exception, an error message is printed and the (child) process is
terminated with _exit 1.
|
|
isatty |
:: Handle | Handle to check
| -> IO Bool | Whether the handle is connected to a terminal
| Check if a handle is connected to a terminal.
This is a front end to the isatty(3) function (see man page). It is useful,
for instance, to determine if color escape sequences should be
generated.
|
|
|
outm |
:: String | Message to print
| -> IO () | | Print text to stdout.
This is a shorthand for putStrLn, except for stderr being flushed
beforehand. This way normal output and error output appear in
order, even when they aren't buffered as by default.
An additional newline is printed at the end.
outm msg = do
hFlush stderr
putStrLn msg
|
|
|
outm_ |
:: String | Message to print
| -> IO () | | Print text to stdout.
This is a shorthand for putStr, except for stderr being flushed
beforehand. This way normal output and error output appear in
order, even when they aren't buffered as by default.
No newline is printed at the end.
outm_ msg = do
hFlush stderr
putStr msg
|
|
|
logm |
:: String | Message to print
| -> IO () | | Colorful log message to stderr.
This prints a message to stderr. When stderr is connected to a terminal
(as determined by isatty(3)), additional escape sequences are printed,
which make the message appear in cyan. Additionally, a newline character is
output at the end.
stdout is flushed beforehand. So normal output and error output appear in
order, even when they aren't buffered as by default.
See logm_, errm, errm_.
|
|
|
logm_ :: String -> IO () |
Colorful log message to stderr.
This prints a message to stderr. When stderr is connected to a terminal
(as determined by isatty(3)), additional escape sequences are printed,
which make the message appear in cyan. No a newline character is output at the end.
stdout is flushed beforehand. So normal output and error output appear in
order, even when they aren't buffered as by default.
See logm, errm, errm_.
|
|
errm :: String -> IO () |
Colorful error message to stderr.
This prints a message to stderr. When stderr is connected to a terminal
(as determined by isatty(3)), additional escape sequences are printed,
which make the message appear in red. Additionally, a newline character is
output at the end.
stdout is flushed beforehand. So normal output and error output appear in
order, even when they aren't buffered as by default.
See logm, logm_, errm_.
|
|
errm_ :: String -> IO () |
Colorful error message to stderr.
This prints a message to stderr. When stderr is connected to a terminal
(as determined by isatty(3)), additional escape sequences are printed,
which make the message appear in red. No a newline character is output at the end.
stdout is flushed beforehand. So normal output and error output appear in
order, even when they aren't buffered as by default.
See logm, logm_, errm.
|
|
fill_in_filename |
:: | | => String | File name to fill in
| -> IO a | IO action to modify
| -> IO a | Modified IO action
| In case the specified action throws an IOError, fill in its filename field. This way, more useful error messages can be produced.
Example:
-- Oh, the GHC libraries neglect to fill in the file name
executeFile' prog a b c =
fill_in_filename prog $ executeFile prog a b c
See fill_in_location, add_location.
|
|
|
fill_in_location |
:: | | => String | Location name to fill in
| -> IO a | IO action to modify
| -> IO a | Modified IO action
| In case the specified action throws an IOError, fill in its location field. This way, more useful error messages can be produced.
Example:
my_fun a b c = do
-- ...
fill_in_location "my_fun" $ -- Give the caller a more useful location information in case of failure
rename "foo" "bar"
-- ...
See fill_in_filename.
|
|
|
add_location |
:: | | => String | Location name to add
| -> IO a | IO action to modify
| -> IO a | Modified IO action
| In case the specified action throws an IOError, add a line to its location field. This way, more useful error messages can be produced. The
specified string is prepended to the old location, separating it with a newline from the previous location, if any. When using this thoroughly, you
get a reverse call stack in IOErrors.
Example:
my_fun =
add_location "my_fun" $ do
-- ...
See fill_in_filename, fill_in_location.
|
|
|
execute_file |
:: | | => FilePath | Program to call
| -> Bool | Search PATH?
| -> [String] | Arguments
| -> Maybe [(String, String)] | Optionally new environment
| -> IO a | Never returns
| This is a replacement for System.Posix.Process.executeFile. It does
additional preparations, then calls executeFile.
executeFile /can't normally be used directly, because it doesn't do the
things which are outlined here./
This are the differences to executeFile:
1. stdout and stderr are flushed.
2. The standard file descriptors 0-2 are made copies of the file descriptors
which the standard handles currently use. This is necessary because they
might no longer use the standard handles. See HsShellScript.
If the standard handles stdin, stdout, stderr aren't in closed state,
and they aren't already connected to the respective standard file
descriptors, their file descriptors are copied to the respective standard
file descriptors (with dup2). Backup copies are made of the file
descriptors which are overwritten. If some of the standard handles are closed,
the corresponding standard file descriptors are closed as well.
3. All file descriptors, except for the standard ones, are set to close on
exec (see fcntl(2)), and will be closed on successful replacement of
the process. Before that, the old file descriptor flags are saved.
4. The standard file descriptors are set to blocking mode, since GHC 6.2.2
sets file descriptors to non-blocking (except 0-2, which may get
overwritten by a non-blocking one in step 2). The called program
doesn't expect that.
5. In case replacing the process fails, the file descriptors are reset to
the original state. The file descriptors flags are restored, and the file
descriptors 0-2 are overwritten again, with their backup copies. Then an
IOError is thrown.
6. In any IOError, the program is filled in as the file name (executeFile
neglects this).
7. The return type is a generic a, rather than ().
Also see HsShellScript.
|
|
|
hDuplicateTo :: Handle -> Handle -> IO () |
|
flushBuffer :: Handle__ -> IO () |
|
dEFAULT_BUFFER_SIZE :: Int |
|
receive_ioerror :: Fd -> IO (Maybe IOError) |
|
decode_ioerror :: String -> Maybe IOError |
|
c_close_on_exec :: CInt -> IO CInt |
|
fork :: IO CInt |
|
_exit_prim :: CInt -> IO () |
|
foreign_strerror :: CInt -> Ptr CChar |
|
hssh_c_isatty :: CInt -> IO CInt |
|
c_save_fdflags :: IO (Ptr CInt) |
|
c_prepare_fd_flags_for_exec :: IO () |
|
c_restore_fdflags :: Ptr CInt -> IO () |
|
c_fcntl_dupfd :: CInt -> CInt -> IO CInt |
|
close :: CInt -> IO CInt |
|
dup2 :: CInt -> CInt -> IO CInt |
|
Produced by Haddock version 2.4.2 |