temporary-1.3: Portable temporary file and directory support

Safe Haskell | Safe-Inferred
Language | Haskell2010

System.IO.Temp

Contents

- Re-exports from System.IO
- Auxiliary functions

Description

Functions to create temporary files and directories.

Most functions come in two flavours: those that create files/directories under the system standard temporary directory and those that use the user-supplied directory.

The functions that create files/directories under the system standard temporary directory will return canonical absolute paths (see `getCanonicalTemporaryDirectory`). The functions use the user-supplied directory do not canonicalize the returned path.

The action inside `withTempFile` or `withTempDirectory` is allowed to remove the temporary file/directory if it needs to.

## Templates and file names

The treatment of templates differs somewhat for files vs directories.

For files, the template has form `name.ext`, and a random number will be placed between between the name and the extension to yield a unique file name, e.g. `name1804289383846930886.ext`.

For directories, no extension is recognized. A random hexadecimal string (whose length depends on the system's word size) is appended to the end of the template. For instance, the directory template `dir` may result in a directory named `dir-e4bd89e5d00acdee`.

You shouldn't rely on the specific form of file or directory names generated by the library; it has changed in the past and may change in the future.

Synopsis

- withSystemTempFile :: (MonadIO m, MonadMask m) => String -> (FilePath -> Handle -> m a) -> m a
- withSystemTempDirectory :: (MonadIO m, MonadMask m) => String -> (FilePath -> m a) -> m a
- withTempFile :: (MonadIO m, MonadMask m) => FilePath -> String -> (FilePath -> Handle -> m a) -> m a
- withTempDirectory :: (MonadMask m, MonadIO m) => FilePath -> String -> (FilePath -> m a) -> m a
- openNewBinaryFile :: FilePath -> String -> IO (FilePath, Handle)
- createTempDirectory :: FilePath -> String -> IO FilePath
- writeTempFile :: FilePath -> String -> String -> IO FilePath
- writeSystemTempFile :: String -> String -> IO FilePath
- emptyTempFile :: FilePath -> String -> IO FilePath
- emptySystemTempFile :: String -> IO FilePath
- openTempFile :: FilePath -> String -> IO (FilePath, Handle)
- openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
- getCanonicalTemporaryDirectory :: IO FilePath

# Documentation

withSystemTempFile Source #

Arguments

:: (MonadIO m, MonadMask m) |
=> String | File name template
-> (FilePath -> Handle -> m a) | Callback that can use the file
-> m a |

Create, open, and use a temporary file in the system standard temporary directory.

The temp file is deleted after use.

Behaves exactly the same as `withTempFile`, except that the parent temporary directory will be that returned by `getCanonicalTemporaryDirectory`.

withSystemTempDirectory Source #

Arguments

:: (MonadIO m, MonadMask m) |
=> String | Directory name template
-> (FilePath -> m a) | Callback that can use the directory
-> m a |

Create and use a temporary directory in the system standard temporary directory.

Behaves exactly the same as `withTempDirectory`, except that the parent temporary directory will be that returned by `getCanonicalTemporaryDirectory`.

withTempFile Source #

Arguments

:: (MonadIO m, MonadMask m) |
=> FilePath | Parent directory to create the file in
-> String | File name template
-> (FilePath -> Handle -> m a) | Callback that can use the file
-> m a |

Create, open, and use a temporary file in the given directory.

The temp file is deleted after use.

withTempDirectory Source #

Arguments

:: (MonadMask m, MonadIO m) |
=> FilePath | Parent directory to create the directory in
-> String | Directory name template
-> (FilePath -> m a) | Callback that can use the directory
-> m a |

Create and use a temporary directory inside the given directory.

The directory is deleted after use.

openNewBinaryFile :: FilePath -> String -> IO (FilePath, Handle) Source #

Like `openBinaryTempFile`, but uses 666 rather than 600 for the permissions.

Equivalent to `openBinaryTempFileWithDefaultPermissions`.

createTempDirectory Source #

Arguments

:: FilePath | Parent directory to create the directory in
-> String | Directory name template
-> IO FilePath |

Create a temporary directory.

writeTempFile Source #

Arguments

:: FilePath | Parent directory to create the file in
-> String | File name template
-> String | Data to store in the file
-> IO FilePath | Path to the (written and closed) file

Create a unique new file, write (text mode) a given data string to it, and close the handle again. The file will not be deleted automatically, and only the current user will have permission to access the file.

Since: 1.2.1

writeSystemTempFile Source #

Arguments

:: String | File name template
-> String | Data to store in the file
-> IO FilePath | Path to the (written and closed) file

Like `writeTempFile`, but use the system directory for temporary files.

Since: 1.2.1

emptyTempFile Source #

Arguments

:: FilePath | Parent directory to create the file in
-> String | File name template
-> IO FilePath | Path to the (written and closed) file

Create a unique new empty file. (Equivalent to `writeTempFile` with empty data string.) This is useful if the actual content is provided by an external process.

Since: 1.2.1

emptySystemTempFile Source #

Arguments

:: String | File name template
-> IO FilePath | Path to the (written and closed) file

Like `emptyTempFile`, but use the system directory for temporary files.

Since: 1.2.1

# Re-exports from System.IO

openTempFile Source #

Arguments

:: FilePath | Directory in which to create the file
-> String | File name template. If the template is "foo.ext" then the created file will be "fooXXX.ext" where XXX is some random number. Note that this should not contain any path separator characters. On Windows, the template prefix may be truncated to 3 chars, e.g. "foobar.ext" will be "fooXXX.ext".
-> IO (FilePath, Handle) |

The function creates a temporary file in ReadWrite mode. The created file isn't deleted automatically, so you need to delete it manually.

The file is created with permissions such that only the current user can read/write it.

With some exceptions (see below), the file will be created securely in the sense that an attacker should not be able to cause openTempFile to overwrite another file on the filesystem using your credentials, by putting symbolic links (on Unix) in the place where the temporary file is to be created. On Unix the `O_CREAT` and `O_EXCL` flags are used to prevent this attack, but note that `O_EXCL` is sometimes not supported on NFS filesystems, so if you rely on this behaviour it is best to use local filesystems only.

openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle) Source #

Like `openTempFile`, but opens the file in binary mode. See `openBinaryFile` for more comments.

# Auxiliary functions

getCanonicalTemporaryDirectory :: IO FilePath Source #

Return the absolute and canonical path to the system temporary directory.

    >>> setCurrentDirectory "/home/feuerbach/"
    >>> setEnv "TMPDIR" "."
    >>> getTemporaryDirectory
    "."
    >>> getCanonicalTemporaryDirectory
    "/home/feuerbach"