NAME
sendfile() — send the contents of a file through a socket
SYNOPSIS
#include <sys/socket.h>
sbsize_t sendfile(int s, int fd, off_t offset, bsize_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.
Notes
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.
See
sendfile64(2)
for a description of how sendfile can be used with large file
(over 2GB) with 32-bit applications.
Note that the types
sbsize_t
and
bsize_t
are similar to
ssize_t
and
size_t
except they are defined as 64-bit values when compiled with
the
_FILE_OFFSET_BITS=64
compile flag.
See
sendfile64(2).
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.
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.
- EOVERFLOW
An application has opened a large file (see
open(2))
and is trying to use sendfile without having been compiled with
the
_FILE_OFFSET_SIZE=64
and
_LARGEFILE_SOURCE/_LARGEFILE64_SOURCE
compile flags.
This operation is not allowed because the
return value,
offset,
and
nbytes
are not 64-bit values and may overflow.
Printable version
