-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Portable temporary file and directory support
--   
--   Functions for creating temporary files and directories.
@package temporary
@version 1.2.1.1


-- | 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
--   <a>getCanonicalTemporaryDirectory</a>). The functions use the
--   user-supplied directory do not canonicalize the returned path.
--   
--   The action inside <a>withTempFile</a> or <a>withTempDirectory</a> is
--   allowed to remove the temporary file/directory if it needs to.
--   
--   <h2>Templates and file names</h2>
--   
--   The treatment of templates differs somewhat for files vs directories.
--   
--   For files, the template has form <tt>name.ext</tt>, and a random
--   number will be placed between between the name and the extension to
--   yield a unique file name, e.g. <tt>name1804289383846930886.ext</tt>.
--   
--   For directories, no extension is recognized, so a number will be
--   simply appended to the end of the template. Moreover, the number will
--   be smaller, as it is derived from the current process's PID (but the
--   result is still a unique directory name). So, for instance, the
--   directory template <tt>dir</tt> may result in a directory named
--   <tt>dir30112</tt>.
module System.IO.Temp

-- | 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 <a>withTempFile</a>, except that the
--   parent temporary directory will be that returned by
--   <a>getCanonicalTemporaryDirectory</a>.
withSystemTempFile :: (MonadIO m, MonadMask m) => String -> (FilePath -> Handle -> m a) -> m a

-- | Create and use a temporary directory in the system standard temporary
--   directory.
--   
--   Behaves exactly the same as <a>withTempDirectory</a>, except that the
--   parent temporary directory will be that returned by
--   <a>getCanonicalTemporaryDirectory</a>.
withSystemTempDirectory :: (MonadIO m, MonadMask m) => String -> (FilePath -> m a) -> m a

-- | Create, open, and use a temporary file in the given directory.
--   
--   The temp file is deleted after use.
withTempFile :: (MonadIO m, MonadMask m) => FilePath -> String -> (FilePath -> Handle -> m a) -> m a

-- | Create and use a temporary directory inside the given directory.
--   
--   The directory is deleted after use.
withTempDirectory :: (MonadMask m, MonadIO m) => FilePath -> String -> (FilePath -> m a) -> m a

-- | Like <a>openBinaryTempFile</a>, but uses 666 rather than 600 for the
--   permissions.
--   
--   Equivalent to <a>openBinaryTempFileWithDefaultPermissions</a>.
openNewBinaryFile :: FilePath -> String -> IO (FilePath, Handle)

-- | Create a temporary directory.
createTempDirectory :: FilePath -> String -> IO FilePath

-- | 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.
writeTempFile :: FilePath -> String -> String -> IO FilePath

-- | Like <a>writeTempFile</a>, but use the system directory for temporary
--   files.
writeSystemTempFile :: String -> String -> IO FilePath

-- | Create a unique new empty file. (Equivalent to <a>writeTempFile</a>
--   with empty data string.) This is useful if the actual content is
--   provided by an external process.
emptyTempFile :: FilePath -> String -> IO FilePath

-- | Like <a>emptyTempFile</a>, but use the system directory for temporary
--   files.
emptySystemTempFile :: String -> IO FilePath

-- | 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 creates 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 <tt>O_CREAT</tt> and <tt>O_EXCL</tt>
--   flags are used to prevent this attack, but note that <tt>O_EXCL</tt>
--   is sometimes not supported on NFS filesystems, so if you rely on this
--   behaviour it is best to use local filesystems only.
openTempFile :: FilePath -> String -> IO (FilePath, Handle)

-- | Like <a>openTempFile</a>, but opens the file in binary mode. See
--   <a>openBinaryFile</a> for more comments.
openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)

-- | Return the absolute and canonical path to the system temporary
--   directory.
--   
--   <pre>
--   &gt;&gt;&gt; setCurrentDirectory "/home/feuerbach/"
--   
--   &gt;&gt;&gt; setEnv "TMPDIR" "."
--   
--   &gt;&gt;&gt; getTemporaryDirectory
--   "."
--   
--   &gt;&gt;&gt; getCanonicalTemporaryDirectory
--   "/home/feuerbach"
--   </pre>
getCanonicalTemporaryDirectory :: IO FilePath
