Create directory. This is a shorthand to System.Directory.createDirectory from the Haskell standard library. In case of an error, the path is included in the IOError, which GHC's implementation neglects to do.

Remove directory. This is Directory.removeDirectory from the Haskell standard library. In case of an error, the path is included in the IOError, which GHC's implementation neglects to do.

Get program start working directory. This is the PWD environent variable, which is kept by the shell (bash, at least). It records the directory path in which the program has been started. Symbolic links in this path aren't expanded. In this way, it differs from getCurrentDirectory from the Haskell standard library.

Change directory. This is an alias for Directory.setCurrentDirectory from the Haskell standard library. In case of an error, the path is included in the IOError, which GHC's implementation neglects to do.

Note that this command is subtly different from the shell's cd command. It changes the process' working directory. This is always a realpath. Symlinks are expanded. The shell, on the other hand, keeps track of the current working directory separately, in a different way: symlinks are not expanded. The shell's idea of the working directory is different from the working directory which a process has.

This means that the same sequence of cd commands, when done in a real shell script, will lead into the same directory. But the working directory as reported by the shell's pwd command may differ from the corresponding one, reported by getCurrentDirectory.

(When talking about the "shell", I'm talking about bash, regardless of whether started as /bin/bash or in compatibility mode, as /bin/sh. I presume it's the standard behavior for the POSIX standard shell.)

See pwd.

Do a call to the realpath(3) system library function. This makes the path absolute, normalizes it and expands all symbolic links. In case of an error, an IOError is thrown.

Return the normalised, absolute version of a specified path. The path is made absolute with the current working directory, and is syntactically normalised afterwards. This is the same as what the realpath program reports with the -s option. It's almost the same as what it reports when called from a shell. The difference lies in the shell's idea of the current working directory. See cd for details.

See cd, normalise_path.

Test for the existence of a path. This is the disjunction of Directory.doesDirectoryExist and Directory.doesFileExist. For an dangling symlink, this will return False.

Test for the existence of a path. This uses System.Posix.Files.getFileStatus to determine whether the path exists in any form in the file system. For a dangling symlink, the result is True.

Test if path points to a file. This is a shortcut for Directory.doesFileExist.

Test if path points to a directory. This will return True for a symlink pointing to a directory. It's a shortcut for Directory.doesDirectoryExist.

Change the working directory temporarily. This executes the specified IO action with a new working directory, and restores it afterwards (exception-safely).

Determine whether a path is a symbolic link. The result for a dangling symlink is True. The path must exist in the file system. In case of an error, a proper IOError is thrown.

Make a symbolic link. This is the symlink(2) function. Any error results in an IOError thrown. The path of the intended symlink is included in the IOError and can be accessed with ioeGetFileName from the Haskell standard library IO.

Determine the target of a symbolic link. This uses the readlink(2) system call. The result is a path which is either absolute, or relative to the directory which the symlink is in. In case of an error, an IOError is thrown. The path is included and can be accessed with IO.ioeGetFileName. Note that, if the path to the symlink ends with a slash, this path denotes the directory pointed to, not the symlink. In this case the call to will fail because of "Invalid argument".

Determine the target of a symbolic link. This uses the readlink(2) system call. The target is converted, such that it is relative to the current working directory, if it isn't absolute. Note that, if the path to the symlink ends with a slash, this path denotes the directory pointed to, not the symlink. In this case the call to readlink will fail with an IOError because of "Invalid argument". In case of any error, a proper IOError is thrown.

Remove file. This is Directory.removeFile from the Haskell standard library, which is a direct frontend to the unlink(2) system call in GHC.

Execute /bin/chmod

chmod = run "/bin/chmod"

Execute /bin/chown

chown = run "/bin/chown"

Execute the cp program

Execute the mv program

The rename(2) system call to rename and/or move a file. The renameFile action from the Haskell standard library doesn't do it, because the two paths may not refer to directories. Failure results in an IOError thrown. The new path is included in the IOError and can be accessed with IO.ioeGetFileName.

Rename a file. This first tries rename, which is most efficient. If it fails, because source and target path point to different file systems (as indicated by the errno value EXDEV), then /bin/mv is called.

See rename, mv.

Rename a file or directory, and cope with read only issues.

This renames a file or directory, using rename, sets the necessary write permissions beforehand, and restores them afterwards. This is more efficient than force_mv, because no external program needs to be called, but it can rename files only inside the same file system. See force_cmd for a detailed description.

The new path may be an existing directory. In this case, it is assumed that the old file is to be moved into this directory (like with mv). The new path is then completed with the file name component of the old path. You won't get an "already exists" error.

force_rename = force_cmd rename

See force_cmd, rename.

Move a file or directory, and cope with read only issues.

This moves a file or directory, using the external command mv, sets the necessary write permissions beforehand, and restores them afterwards. This is less efficient than force_rename, because the external program mv needs to be called, but it can move files between file systems. See force_cmd for a detailed description.

force_mv src tgt = fill_in_location "force_mv" $ force_cmd (\src tgt -> run "/bin/mv" ["--", src, tgt]) src tgt

See force_cmd, force_mv.

Rename a file with rename, or when necessary with mv, and cope with read only issues.

The necessary write permissions are set, then the file is renamed, then the permissions are restored.

First, the rename system call is tried, which is most efficient. If it fails, because source and target path point to different file systems (as indicated by the errno value EXDEV), then /bin/mv is called.

force_rename_mv old new = fill_in_location "force_rename_mv" $ force_cmd rename_mv old new

See rename_mv, rename, mv, force_cmd.

Call a command which moves a file or directory, and cope with read only issues.

This function is for calling a command, which renames files. Beforehand, write permissions are set in order to enable the operation, and afterwards the permissions are restored. The command is meant to be something like rename or run "/bin/mv".

In order to change the name of a file or dirctory, but leave it in the super directory it is in, the super directory must be writeable. In order to move a file or directory to a different super directory, both super directories and the file/directory to be moved must be writeable. I don't know what this behaviour is supposed to be good for.

This function copes with the case that the file/directory to be moved or renamed, or the super directories are read only. It makes the necessary places writeable, calls the command, and makes them read only again, if they were before. The user needs the necessary permissions for changing the corresponding write permissions. If an error occurs (such as file not found, or insufficient permissions), then the write permissions are restored to the state before, before the exception is passed through to the caller.

The command must take two arguments, the old path and the new path. It is expected to create the new path in the file system, such that the correct write permissions of the new path can be set by force_cmd after executing it.

The new path may be an existing directory. In this case, it is assumed that the old file is to be moved into this directory (like with mv). The new path is completed with the file name component of the old path, before it is passed to the command, such that the command is supplied the complete new path.

Examples:

force_cmd rename from to
force_cmd (\from to -> run "/bin/mv" ["-i", "-v", "--", from, to]) from to

See force_rename, force_mv, rename.

Make a file or directory writeable for the user, perform an action, and restore its writeable status. An IOError is raised when the user doesn't have permission to make the file or directory writeable.

force_writeable path io = force_writeable2 path (io >>= \res -> return (path, res))

Example:

-- Need to create a new directory in /foo/bar, even if that's write protected
force_writeable "/foo/bar" $ mkdir "/foo/bar/baz"

See force_cmd, force_writeable2.

Make a file or directory writeable for the user, perform an action, and restore its writeable status. The action may change the name of the file or directory. Therefore it returns the new name, along with another return value, which is passed to the caller.

The writeable status is only changed back if it has been changed by force_writeable2 before. An IOError is raised when the user doesn'h have permission to make the file or directory writeable, or when the new path doesn't exist.

See force_cmd, force_writeable.

This is the System.Posix.Files.getFileStatus function from the GHC libraries, with improved error reporting. The GHC function doesn't include the file name in the IOError when the call fails, making error messages much less useful. getFileStatus' rectifies this.

See getFileStatus.

This is the System.Posix.Files.fileAccess function from the GHC libraries, with improved error reporting. The GHC function doesn't include the file name in the IOError when the call fails, making error messages much less useful. fileAccess' rectifies this.

See fileAccess.

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

Run the command mt status for querying the tape drive status, and parse its output.

Call the fdupes program in order to find identical files. It outputs a list of groups of file names, such that the files in each group are identical. Each of these groups is further analysed by the fdupes action. It is split to a list of lists of paths, such that each list of paths corresponds to one of the directories which have been searched by the fdupes program. If you just want groups of identical files, then apply map concat to the result.

The fdupes /program doesn't handle multiple occurences of the same directory, or in recursive mode one specified directory containing another, properly. The same file may get reported multiple times, and identical files may not get reported./

The paths are normalised (using normalise_path).

Call the du program. See du(1).

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.

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.

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.

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.

Make a readable error message. This includes all the fields of RunError except for the environment.

See RunError.

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:

• The handle (ioeGetHandle): Nothing
• The error type (ioeGetErrorType): GHC.IO.Exception.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.

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.

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.

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.

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.

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.

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.

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, Data.IORef.

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

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.

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.

1. 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.
2. 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.
3. 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.
4. In any IOError, the program is filled in as the file name (executeFile neglects this).
5. The return type is a generic a, rather than ().

Also see HsShellScript.

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.

Generate a human-readable description of a ProcessStatus.

See exec, runprog and System.Posix.ProcessStatus in the GHC hierarchical library documentation.

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.

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 for backwards compatibility only. 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.

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, ->>-, =>-.

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, '(->-)', '(=>>-)'.

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, '(->-)', '(=>>-)'.

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, '(->>-)', '(=>-)'.

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, '(->-)', '(=>-)'.

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.

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.

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.

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.

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, '(=|-)', '(-|=)'.

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, '(-|-)', '(-|=)'.

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, '(=|-)', '(=|=)'.

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, =|-, -|=.

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 -|-, =|-.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Create a temporary file. This will create a new, empty file, with read-write permissions for the user, and no permissons for the group and others. The path consists of the specified prefix, a dot, and six random characters (digits and letters).

tmp_file prefix = temp_file 6 (prefix ++ ".") ""

See temp_file, tmp_dir, with_tmp_file.

Create a temporary directory. This will create a new directory, with read-write-execute permissions for the user (unless further restricted by the process's umask), and no permissons for the group and others. The path consists of the specified prefix, a dot, and six random characters (digits and letters).

tmp_dir prefix = temp_dir 6 (prefix ++ ".") ""

See temp_dir, tmp_file, with_tmp_dir.

Create a temporary file. This will create a new, empty file, with a path which did not previously exist in the file system. The path consists of the specified prefix, a sequence of random characters (digits and letters), and the specified suffix. The file is created with read-write permissions for the user, and no permissons for the group and others. The ownership is set to the effective user ID of the process. The group ownership is set either to the effective group ID of the process or to the group ID of the parent directory (depending on filesystem type and mount options on Linux - see open(2) for details).

See tmp_file, temp_dir, with_temp_file.

Create a temporary directory. This will create a new directory, with a path which did not previously exist in the file system. The path consists of the specified prefix, a sequence of random characters (digits and letters), and the specified suffix. The directory is normally created with read-write-execute permissions for the user, and no permissons for the group and others. But this may be further restricted by the process's umask in the usual way.

The newly created directory will be owned by the effective uid of the process. If the directory containing the it has the set group id bit set, or if the filesystem is mounted with BSD group semantics, the new directory will inherit the group ownership from its parent; otherwise it will be owned by the effective gid of the process. (See mkdir(2))

See tmp_dir, temp_file, with_temp_dir.

Create a temporary path. This will generate a path which does not yet exist in the file system. It consists of the specified prefix, a sequence of random characters (digits and letters), and the specified suffix.

Avoid relying on the generated path not to exist in the file system. Or else you'll get a potential race condition, since some other process might create the path after temp_path, before you use it. This is a security risk. The global random number generator (Random.randomRIO) is used to generate the random characters. These might not be that random after all, and could potentially be guessed. Rather use temp_file or temp_dir.

See temp_file, temp_dir.

Create and open a temporary file, perform some action with it, and delete it afterwards. This is a front end to the tmp_file function. The file and its path are created in the same way. The IO action is passed a handle of the new file. When it finishes - normally or with an exception - the file is deleted.

See tmp_file, with_temp_file, with_tmp_dir.

Create a temporary directory, perform some action with it, and delete it afterwards. This is a front end to the tmp_dir function. The directory and its path are created in the same way. The IO action is passed the path of the new directory. When it finishes - normally or with an exception - the directory is deleted.

The action must clean up any files it creates inside the directory by itself. with_temp_dir doesn't delete any files inside, so the directory could be removed. If the directory isn't empty, an IOError results (with the path filled in). When the action throws an exception, and the temporary directory cannot be removed, then the exception is passed through, rather than replacing it with the IOError. (This is because it's probably exactly because of that exception that the directory isn't empty and can't be removed).

with_tmp_dir prefix io = with_temp_dir 6 (prefix ++ ".") "" io

See tmp_dir, with_temp_dir, with_tmp_file.

Create and open a temporary file, perform some action with it, and delete it afterwards. This is a front end to the temp_file function. The file and its path are created in the same way. The IO action is passed a handle of the new file. When it finishes - normally or with an exception - the file is deleted.

See temp_file, with_tmp_file, with_temp_dir.

Create a temporary directory, perform some action with it, and delete it afterwards. This is a front end to the temp_dir function. The directory and its path are created in the same way. The IO action is passed the path of the new directory. When it finishes - normally or with an exception - the directory is deleted.

The action must clean up any files it creates inside the directory by itself. with_temp_dir doesn't delete any files inside, so the directory could be removed. If the directory isn't empty, an IOError results (with the path filled in). When the action throws an exception, and the temporary directory cannot be removed, then the exception is passed through, rather than replacing it with the IOError. (This is because it's probably exactly because of that exception that the directory isn't empty and can't be removed).

See temp_dir, with_tmp_dir, with_temp_file.

One entry of mount information. This is the same as struct mntent from <mntent.h>. A list of these is returned by the functions which read mount information.

See read_mounts, read_mtab, read_fstab.

Read mount information. This is a front end to the setmntent(3), getmntent(3), endmntent(3) system library functions.

When the setmntent call fails, the errno value is converted to an IOError and thrown.

See read_mtab, read_fstab.

Get the currently mounted file systems.

read_mtab = read_mounts "/etc/mtab"

See read_mounts.

Get the system wide file system table.

read_fstab = read_mounts "/etc/fstab"

See read_mounts.

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

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

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_.

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_.

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_.

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.

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.

Format an Int with leading zeros. If the string representation of the Inŧ is longer than the number of characters to fill up, this produces as many characters as needed.

Remove trailing newlines. This is silimar to perl's chomp procedure.

Get contents of a file or of stdin. This is a simple frontend to hGetContents. A file name of "-" designates stdin. The contents are read lazily as the string is evaluated.

(The handle which we read from will be in semi-closed state. Once all input has read, it is closed automatically (Haskell Library Report 11.2.1). Therefore we don't need to return it).

lazy_contents path = do
    h   <- if path == "-" then return stdin else openFile path ReadMode
    hGetContents h

Get contents of a file or of stdin eagerly. This is the same as lazy_contents, except for the contents being read immediately.

This is an interface to the POSIX glob function, which does wildcard expansion in paths. The list of matched paths is returned. It's empty for no match (rather than the original pattern). In case anything goes wrong (such as permission denied), an IOError is thrown.

This does not do tilde expansion, which is done (among many unwanted other things) by wordexp. The only flag used for the call to glob is GLOB_ERR.

The behaviour in case of non-existing path components is inconsistent in the GNU version of the underlying glob function. glob /doesnt_exist/foo will return the empty list, whereas glob /doesnt_exist/* causes a No such file or directory IOError.

See man pages glob(3) and wordexp(3).

Error reporting wrapper for the main function. This catches any HsShellScript generated exceptions, and IOErrors, prints an error message and exits with exitFailure. The main function typically looks like this:

main = mainwrapper $ do ...

The exceptions caught are ArgError, RunError, ProcessStatus and IOError.

Read the global system error number. This is the POSIX errno value. This function is redundant. Use Foreign.C.Error.getErrno instead.

Generate an error message from an errno value. This is the POSIX strerror system library function.

See the man page strerror(3).

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).

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).

Print a message to stderr and exit with an exit code indicating an error.

failIO msg = hPutStrLn stderr msg >> exitFailure

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.

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.

Convert an IOError to a string.

There is an instance declaration of IOError in Show in the GHC.IO library, but show_ioerror produces a more readable, and more complete, message.

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.

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.

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.