File.Binary

Binary file handling.

File path operations

withBinaryFile :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m a) -> m a

Unlifted version of withBinaryFile.

Since: unliftio-0.1.0.0

Reading

readFile :: FilePath -> IO ByteString

Read an entire file strictly into a ByteString.

readFileDeserialise

Arguments

:: Serialise a

=> FilePath

The file to read from.

-> IO a

The deserialised value.

Read the specified file (internally, by reading a ByteString) and attempt to decode it into a Haskell value using deserialise (the type of which is determined by the choice of the result type).

Throws: DeserialiseFailure if the file fails to deserialise properly.

Since: serialise-0.2.0.0

Writing

writeFile :: FilePath -> ByteString -> IO ()

Write a ByteString to a file.

writeFileSerialise

Arguments

:: Serialise a

=> FilePath

The file to write to.

-> a

The value to be serialised and written.

-> IO ()

Serialise a ByteString and write it directly to the specified file.

Since: serialise-0.2.0.0

appendFile :: FilePath -> ByteString -> IO ()

Append a ByteString to a file.

File handle operations

Reading

getContents :: IO ByteString

getContents. Read stdin strictly. Equivalent to hGetContents stdin The Handle is closed after the contents have been read.

hGetContents :: Handle -> IO ByteString

Read a handle's entire contents strictly into a ByteString.

This function reads chunks at a time, increasing the chunk size on each read. The final string is then realloced to the appropriate size. For files > half of available memory, this may lead to memory exhaustion. Consider using readFile in this case.

The Handle is closed once the contents have been read, or if an exception is thrown.

hGet :: Handle -> Int -> IO ByteString

Read a ByteString directly from the specified Handle. This is far more efficient than reading the characters into a String and then using pack. First argument is the Handle to read from, and the second is the number of bytes to read. It returns the bytes read, up to n, or empty if EOF has been reached.

hGet is implemented in terms of hGetBuf.

If the handle is a pipe or socket, and the writing end is closed, hGet will behave as if EOF was reached.

hGetSome :: Handle -> Int -> IO ByteString

Like hGet, except that a shorter ByteString may be returned if there are not enough bytes immediately available to satisfy the whole request. hGetSome only blocks if there is no data available, and EOF has not yet been reached.

hGetNonBlocking :: Handle -> Int -> IO ByteString

hGetNonBlocking is similar to hGet, except that it will never block waiting for data to become available, instead it returns only whatever data is available. If there is no data available to be read, hGetNonBlocking returns empty.

Note: on Windows and with Haskell implementation other than GHC, this function does not work correctly; it behaves identically to hGet.

Writing

putStr :: ByteString -> IO ()

Write a ByteString to stdout

hPutStr :: Handle -> ByteString -> IO ()

A synonym for hPut, for compatibility

hPutNonBlocking :: Handle -> ByteString -> IO ByteString

Similar to hPut except that it will never block. Instead it returns any tail that did not get written. This tail may be empty in the case that the whole string was written, or the whole original string if nothing was written. Partial writes are also possible.

Note: on Windows and with Haskell implementation other than GHC, this function does not work correctly; it behaves identically to hPut.