Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sendfile (3C)

Name

sendfile - send files over sockets or copy files to files

Synopsis

#include <sys/sendfile.h>

ssize_t sendfile(int 
out_fd, int in_fd, 
off_t *off, size_t 
len);

Description

The sendfile() function copies data from in_fd to out_fd, starting at specified offset and of length len bytes.

The in_fd argument should be a file descriptor to a regular file opened for reading. For more information, see the open(2) man page. The out_fd argument should be a file descriptor to a regular file opened for writing or to a connected AF_INET or AF_INET6 socket of SOCK_STREAM type. For more information, see the socket(3C) man page.

If the off argument is not null, the off argument is a pointer to a variable. The variable holds the input file pointer position from which the data is read. After sendfile() has completed, the variable is set to the offset of the byte following the last byte that was read.

If the off argument is null, data is read from in_fd starting at its own file offset, and the file offset of in_fd is updated to the offset of the byte following the last byte that was read.

The sendfile() function modifies the file pointer for out_fd, if it is a regular file.

The sendfile() function can also be used to send buffers by pointing in_fd to SFV_FD_SELF.

Return Values

Upon successful completion, sendfile() returns the total number of bytes written to out_fd and also updates the offset to point to the byte that follows the last byte read. Otherwise, it returns –1, and errno is set to indicate the error.

Errors

The sendfile() function will fail if:

EAFNOSUPPORT

The implementation does not support the specified address family for socket.

EAGAIN

Mandatory file or record locking is set on either the file descriptor or output file descriptor if it points at regular files. O_NDELAY or O_NONBLOCK is set, and there is a blocking record lock. An attempt has been made to write to a stream that cannot accept data with the O_NDELAY or the O_NONBLOCK flag set.

EBADF

The out_fd or in_fd argument is either not a valid file descriptor, out_fd is not opened for writing. or in_fd is not opened for reading.

EINVAL

The offset cannot be represented by the off_t structure, or the length is negative when cast to ssize_t.

EIO

An I/O error occurred while accessing the file system.

ENOMEM

There is insufficient memory available.

ENOTCONN

The socket is not connected.

EOPNOTSUPP

The socket type is not supported.

EPIPE

The out_fd argument is no longer connected to the peer endpoint.

EINTR

A signal was caught during the write operation and no data was transferred.

Usage

The sendfile() function has a transitional interface for 64-bit file offsets. See lf64(7).

Examples

Example 1 Sending a Buffer Over a Socket

The following example demonstrates how to send the buffer buf over a socket. At the end, it prints the number of bytes transferred over the socket from the buffer. It assumes that addr will be filled up appropriately, depending upon where to send the buffer.

int tfd;
off_t baddr;
struct sockaddr_in sin;
char buf[64 * 1024];
in_addr_t addr;
size_t len;
        
tfd = socket(AF_INET, SOCK_STREAM, 0);
if (tfd == -1) {
    perror("socket");
    exit(1);
}

sin.sin_family = AF_INET;
sin.sin_addr.s_addr = addr;    /* Fill in the  appropriate address. */
sin.sin_port = htons(2345);
if (connect(tfd, (struct sockaddr *)&sin, sizeof(sin))<0) {
    perror("connect");
    exit(1);
}

baddr = (off_t)buf;
len = sizeof(buf);
while (len > 0) {
    ssize_t res;
    res = sendfile(tfd, SFV_FD_SELF, &baddr, len);
    if (res == -1)
            if (errno != EINTR) {
                    perror("sendfile");
                    exit(1);
            } else continue;
    len -= res;
}
Example 2 Transferring Files to Sockets

The following program demonstrates a transfer of files to sockets:

int ffd, tfd;
off_t off;
struct sockaddr_in sin;
in_addr_t  addr;
int len;
struct stat stat_buf;
ssize_t len;

ffd = open("file", O_RDONLY);
if (ffd == -1) {
    perror("open");
    exit(1);
}

tfd = socket(AF_INET, SOCK_STREAM, 0);
if (tfd == -1) {
    perror("socket");
    exit(1);
}

sin.sin_family = AF_INET;
sin.sin_addr = addr;    /* Fill in the  appropriate address. */
sin.sin_port = htons(2345);
if (connect(tfd, (struct sockaddr *) &sin, sizeof(sin)) <0) {
    perror("connect");
    exit(1);
}

if (fstat(ffd, &stat_buf) == -1) {
    perror("fstat");
    exit(1);
}

len = stat_buf.st_size;
while (len > 0) {
    ssize_t res;
    res = sendfile(tfd, ffd, &off, len);
    if (res == -1)
            if (errno != EINTR) {
                    perror("sendfile");
                    exit(1);
            } else continue;
    len -= res;
}

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe

See Also

open(2), sendfilev(3C), socket(3C), attributes(7), lf64(7)