NAME
sendfile() — send the contents of a file through a socket
SYNOPSIS
#include <sys/socket.h>
ssize_t sendfile(int s, int fd, off_t offset, size_t nbytes,
const struct iovec *hdtrl, int flags);
DESCRIPTION
The
sendfile()
system call transmits the contents of
a file associated with the file
descriptor
fd ,
plus an optional header and trailer buffers across a socket connection
specified by
s .
sendfile()
can be used only when the socket is in a connected state.
offset
specifies the offset within the file at which to start the file data transfer.
nbytes
is the number of bytes to be sent from the file.
If this parameter is set to zero, data from the
offset
to the end of the file will be sent.
hdtrl
points to a two entry
iovec
structure.
See
write(2)
for a description of the
iovec
structure.
The first entry is for header
information. If this pointer is non-NULL, the contents of the buffer
are sent before sending any data from the file. The second entry is for
trailer information. If this pointer is non-NULL, the contents of the
buffer will be sent after the data from the file. If both pointers
are NULL, or
hdtrl
is a NULL pointer, only the specified range of
the file will be transferred.
At the end of the call,
the socket connection will be left completely open for both
reading and writing, unless the
flags
parameter
is set to:
- SF_DISCONNECT
Disallow further sends and receives.
RETURN VALUE
Upon successful completion,
sendfile()
returns the number of bytes sent. This includes the header, trailer,
and the file contents. Otherwise,
-1
is returned and
errno
is set to indicate the error.
If no buffer space is available to hold the data to be transmitted,
sendfile()
blocks unless nonblocking mode is enabled.
See
send(2)
for a description of the nonblocking mode behavior.
ERRORS
If
sendfile()
fails,
errno
is set to one of the following values.
- [EBADF]
An invalid socket descriptor
s ,
or file descriptor
fd
is specified.
- [ENOTSOCK]
s
is a valid file descriptor, but it is not a socket.
- [EFAULT]
An invalid pointer was specified in the
hdtrl
parameter or the
iovec
structure.
- [ENOBUFS]
No buffer space is available in the system to perform the operation.
- [EINTR]
The operation was interrupted by a signal before any data was sent.
(If some data was sent,
sendfile()
returns the number of bytes sent before the signal,
and [EINTR] is not set).
- [EINVAL]
The
offset
or
flags
parameter is invalid.
The
hdtrl
parameter, or a length in the
iovec
structure is invalid.
- [ENOTCONN]
A
sendfile()
on a socket that is not connected, or a
sendfile()
on a socket that has not completed the connect sequence with its peer,
or is no longer connected to its peer.
- [EPIPE]
With
SIGPIPE
signal.
An attempt was made to send on a socket that was connected,
but the connection has been shut down
either by the remote peer or by this side of the connection.
Note that the default action for
SIGPIPE,
unless the process has established a signal handler for this signal,
is to terminate the process.
- [EAGAIN]
Nonblocking I/O is enabled using the
O_NONBLOCK
flag with
fcntl(),
and the requested operation would block.
- [EWOULDBLOCK]
The socket is marked non-blocking
and the requested operation would block.
- [ENOMEM]
No memory is available in the system to perform the operation.
- [EOPNOTSUPP]
The socket is not a TCP socket.
