I/O with file descriptors

Read data from an Fd and convert it to a ByteString. Throws an exception if this is an invalid descriptor, or EOF has been reached. This is essentially equivalent to fdReadBuf; the differences are that we allocate a byte buffer for the ByteString, and that we detect EOF and throw an IOError.

Read data from an Fd into memory. This is exactly equivalent to the POSIX.1 read(2) system call, except that we return 0 bytes read if the ByteCount argument is less than or equal to zero (instead of throwing an errno exception). N.B., this behavior is different from the version in unix-2.4.2.0 which only checks for equality to zero. If there are any errors, then they are thrown as IOError exceptions.

Since: 0.3.0

Read data from an Fd into memory. This is a variation of fdReadBuf which returns errors with an Either instead of throwing exceptions.

Since: 0.3.3

Read data from an Fd and convert it to a ByteString. Throws an exception if this is an invalid descriptor, or EOF has been reached.

This version takes a kind of stateful predicate for whether and how long to keep retrying. Assume the function is called as fdReads f z0 fd n0. We will attempt to read n0 bytes from fd. If we fall short, then we will call f len z where len is the total number of bytes read so far and z is the current state (initially z0). If it returns Nothing then we will give up and return the current buffer; otherwise we will retry with the new state, continuing from where we left off.

For example, to define a function that tries up to n times, we can use:

fdReadUptoNTimes :: Int -> Fd -> ByteCount -> IO ByteString
fdReadUptoNTimes n0 = fdReads retry n0
    where
    retry _ 0 = Nothing
    retry _ n = Just $! n-1

The benefit of doing this instead of the naive approach of calling fdRead repeatedly is that we only need to allocate one byte buffer, and trim it once at the end--- whereas the naive approach would allocate a buffer, trim it to the number of bytes read, and then concatenate with the previous one (another allocation, plus copying everything over) for each time around the loop.

Since: 0.2.1

Read data from an Fd and scatter it into memory. This is exactly equivalent to the XPG4.2 readv(2) system call, except that we return 0 bytes read if the Int argument is less than or equal to zero (instead of throwing an eINVAL exception). If there are any errors, then they are thrown as IOError exceptions.

TODO: better documentation.

Since: 0.3.0

Read data from an Fd and scatter it into memory. This is a variation of fdReadvBuf which returns errors with an Either instead of throwing exceptions.

Since: 0.3.3

Read data from a specified position in the Fd and convert it to a ByteString, without altering the position stored in the Fd. Throws an exception if this is an invalid descriptor, or EOF has been reached. This is essentially equivalent to fdPreadBuf; the differences are that we allocate a byte buffer for the ByteString, and that we detect EOF and throw an IOError.

Since: 0.3.0

Read data from a specified position in the Fd into memory, without altering the position stored in the Fd. This is exactly equivalent to the XPG4.2 pread(2) system call, except that we return 0 bytes read if the Int argument is less than or equal to zero (instead of throwing an errno exception). If there are any errors, then they are thrown as IOError exceptions.

Since: 0.3.0

Read data from a specified position in the Fd into memory, without altering the position stored in the Fd. This is a variation of fdPreadBuf which returns errors with an Either instead of throwing exceptions.

Since: 0.3.3

Read data from a specified position in the Fd and convert it to a ByteString, without altering the position stored in the Fd. Throws an exception if this is an invalid descriptor, or EOF has been reached. This is a fdPreadBuf based version of fdReads; see those functions for more details.

Since: 0.3.1

Write a ByteString to an Fd. The return value is the total number of bytes actually written. This is exactly equivalent to fdWriteBuf; we just convert the ByteString into its underlying Ptr Word8 and ByteCount components for passing to fdWriteBuf.

Write data from memory to an Fd. This is exactly equivalent to the POSIX.1 write(2) system call, except that we return 0 bytes written if the ByteCount argument is less than or equal to zero (instead of throwing an errno exception). N.B., this behavior is different from the version in unix-2.4.2.0 which doesn't check the byte count. If there are any errors, then they are thrown as IOError exceptions.

Since: 0.3.0

Write data from memory to an Fd. This is a variation of fdWriteBuf which returns errors with an Either instead of throwing exceptions.

Since: 0.3.3

Write a sequence of ByteStrings to an Fd. The return value is a triple of: the total number of bytes written, the number of bytes written from the first of the remaining strings, and the remaining (unwritten) strings. We return this triple instead of a pair adjusting the head of the remaining strings (i.e., removing the bytes already written) in case there is some semantic significance to the way the input is split into chunks.

This version consumes the list lazily and will call fdWrite once for each ByteString, thus making O(n) system calls. This laziness allows the early parts of the list to be garbage collected and prevents needing to hold the whole list of ByteStrings in memory at once. Compare against fdWritev.

Write a sequence of ByteStrings to an Fd. The return value is the total number of bytes written. Unfortunately the writev(2) system call does not provide enough information to return the triple that fdWrites does.

This version will force the spine of the list, converting each ByteString into an iovec (see CIovec), and then call fdWritevBuf. This means we only make one system call, which reduces the overhead of performing context switches. But it also means that we must store the whole list of ByteStrings in memory at once, and that we must perform some allocation and conversion. Compare against fdWrites.

Write data from memory to an Fd. This is exactly equivalent to the XPG4.2 writev(2) system call, except that we return 0 bytes written if the Int argument is less than or equal to zero (instead of throwing an eINVAL exception). If there are any errors, then they are thrown as IOError exceptions.

TODO: better documentation.

Since: 0.3.0

Write data from memory to an Fd. This is a variation of fdWritevBuf which returns errors with an Either instead of throwing exceptions.

Since: 0.3.3

Write data from memory to a specified position in the Fd, but without altering the position stored in the Fd. This is exactly equivalent to fdPwriteBuf; we just convert the ByteString into its underlying Ptr Word8 and ByteCount components for passing to fdPwriteBuf.

Since: 0.3.0

Write data from memory to a specified position in the Fd, but without altering the position stored in the Fd. This is exactly equivalent to the XPG4.2 pwrite(2) system call, except that we return 0 bytes written if the ByteCount argument is less than or equal to zero (instead of throwing an errno exception). If there are any errors, then they are thrown as IOError exceptions.

Since: 0.3.0

Write data from memory to a specified position in the Fd, but without altering the position stored in the Fd. This is a variation of fdPwriteBuf which returns errors with an Either instead of throwing exceptions.

Since: 0.3.3

Repositions the offset of the file descriptor according to the offset and the seeking mode. This is exactly equivalent to the POSIX.1 lseek(2) system call. If there are any errors, then they are thrown as IOError exceptions.

This is the same as fdSeek in unix-2.6.0.1, but provided here for consistency.

Since: 0.3.5

Repositions the offset of the file descriptor according to the offset and the seeking mode. This is a variation of fdSeek which returns errors with an Either instead of throwing exceptions.

Since: 0.3.5