The length (in bytes) which should be sent

The file offset (in bytes) to start from

An iteratee for sendfile

In general, a whole file is not sent by a single call to sendfile(), but a series of calls which send successive pieces.

The high-level API in this sendfile library has calls which will send the entire file (or an entire requested offset+length), before returning.

However, there are instances where you want to be a bit more involved in the sending loop. For example, if you want to tickle a timeout after each chunk is sent or update a progress bar.

The Iter type gives you that power with out requiring you to manage all the low-level details of the sendfile loop. The interface is simple and consistant across all platforms.

A call to sendfile() can result in three different states:

1. the requested number of bytes for that iteration was sent successfully, there are more bytes left to send.
2. some (possibly 0) bytes were sent, but the file descriptor would now block if more bytes were written. There are more bytes left to send.
3. All the bytes were sent, and there is nothing left to send.

We handle these three cases by using a type with three constructors:

  data Iter
      = Sent       Int64    (IO Iter)
      | WouldBlock Int64 Fd (IO Iter)
      | Done       Int64             

All three constructors provide an Int64 which represents the number of bytes sent for that particular iteration. (Not the total byte count).

The Sent and WouldBlock constructors provide IO Iter as their final argument. Running this IO action will send the next block of data.

The WouldBlock constructor also provides the Fd for the output socket. You should not send anymore data until the Fd would not block. The easiest way to do that is to use threadWaitWrite to suspend the thread until the Fd is available.

A very simple function to drive the Iter might look like:

 runIter :: IO Iter -> IO ()
 runIter iter =
    do r <- iter
       case r of
         (Done _n)      -> return ()
         (Sent _n cont) -> runIter cont
         (WouldBlock _n fd cont) -> 
             do threadWaitWrite fd
                runIter cont

You would use it as the first argument to a *IterWith function, e.g.

  sendFileIterWith runIter outputSocket "/path/to/file" 2^16 

The runIter function provided by this module is similar, but also returns the total number of bytes sent.

NOTE: You must not use the Fd or the IO Iter after the call to *IterWith has returned. When the *IterWith functions return, the file descriptors may be closed due to finalizers running.

A simple function to drive the *IterWith functions. It returns the total number of bytes sent.

The simplest interface. Simply give it an output Socket and the FilePath to the input file.

The simplest interface. Simply give it an output Socket and the FilePath to the input file.

This variant takes a function to drive the iteration loop. See Iter for more information.

A more powerful interface than sendFile which accepts a starting offset, and the bytecount to send; the offset and the count must be a positive integer. The initial position of the input file handle matters not since the offset is absolute, and the final position may be different depending on the platform -- no assumptions can be made.

A more powerful interface than sendFile which accepts a starting offset, and the bytecount to send; the offset and the count must be a positive integer. The initial position of the input file handle matters not since the offset is absolute, and the final position may be different depending on the platform -- no assumptions can be made.

This variant takes a function to drive the iteration loop. See Iter for more information.

The unsafe version of sendFile which accepts a Handle instead of a Socket for the output. It will flush the output handle before sending any file data.

The unsafe version of sendFile which accepts a Handle instead of a Socket for the output. It will flush the output handle before sending any file data.

This variant takes a function to drive the iteration loop. See Iter for more information.

The unsafe version of sendFile' which accepts a Handle instead of a Socket for the output. It will flush the output handle before sending any file data.

The unsafe version of sendFile' which accepts a Handle instead of a Socket for the output. It will flush the output handle before sending any file data.

This variant takes a function to drive the iteration loop. See Iter for more information.

Returns the mode that sendfile was compiled with. Mainly for debugging use. Possible values are WIN32_SENDFILE, LINUX_SENDFILE, FREEBSD_SENDFILE, DARWIN_SENDFILE, and PORTABLE_SENDFILE.