sendfile(3ext)

1sendfile(3EXT)            Extended Library Functions            sendfile(3EXT)
2
3
4

NAME

6       sendfile - send files over sockets or copy files to files
7

SYNOPSIS

9       cc [ flag... ] file... -lsendfile [ library... ]
10       #include <sys/sendfile.h>
11
12       ssize_t sendfile(int out_fd, int in_fd, off_t *off, size_t len);
13
14

DESCRIPTION

16       The  sendfile()  function  copies data from in_fd to out_fd starting at
17       offset off and of length len bytes. The in_fd argument should be a file
18       descriptor  to  a  regular  file  opened  for reading. See open(2). The
19       out_fd argument should be a file descriptor to a  regular  file  opened
20       for writing or to a connected AF_INET or AF_INET6 socket of SOCK_STREAM
21       type. See socket(3SOCKET). The off argument is a pointer to a  variable
22       holding  the  input  file  pointer position from which the data will be
23       read. After sendfile() has completed, the variable will be set  to  the
24       offset  of  the  byte  following the last byte that was read. The send‐
25       file() function does not modify the current file pointer of in_fd,  but
26       does modify the file pointer for out_fd if it is a regular file.
27
28
29       The  sendfile()  function  can also be used to send buffers by pointing
30       in_fd to SFV_FD_SELF.
31

RETURN VALUES

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

ERRORS

39       The sendfile() function will fail if:
40
41       EAFNOSUPPORT    The  implementation  does  not  support  the  specified
42                       address family for socket.
43
44
45       EAGAIN          Mandatory file or record locking is set on  either  the
46                       file  descriptor or output file descriptor if it points
47                       at regular files. O_NDELAY or O_NONBLOCK is   set,  and
48                       there  is  a  blocking record lock. An attempt has been
49                       made to write to a stream that cannot accept data  with
50                       the O_NDELAY or the O_NONBLOCK flag set.
51
52
53       EBADF           The out_fd or in_fd argument is either not a valid file
54                       descriptor, out_fd is not opened for writing. or  in_fd
55                       is not opened for reading.
56
57
58       EINVAL          The  offset  cannot  be represented by the off_t struc‐
59                       ture, or the length is negative when cast to ssize_t.
60
61
62       EIO             An I/O error occurred while accessing the file system.
63
64
65       ENOTCONN        The socket is not connected.
66
67
68       EOPNOTSUPP      The socket type is not supported.
69
70
71       EPIPE           The out_fd argument is no longer connected to the  peer
72                       endpoint.
73
74
75       EINTR           A  signal  was caught during the write operation and no
76                       data was transferred.
77
78

USAGE

80       The sendfile() function has a transitional interface  for  64-bit  file
81       offsets. See lf64(5).
82

EXAMPLES

84       Example 1 Sending a Buffer Over a Socket
85
86
87       The  following  example  demonstrates how to send the buffer buf over a
88       socket. At the end, it prints the number of bytes transferred over  the
89       socket  from  the buffer. It assumes that addr will be filled up appro‐
90       priately, depending upon where to send the buffer.
91
92
93         int tfd;
94         off_t baddr;
95         struct sockaddr_in sin;
96         char buf[64 * 1024];
97         in_addr_t addr;
98         size_t len;
99
100         tfd = socket(AF_INET, SOCK_STREAM, 0);
101         if (tfd == -1) {
102             perror("socket");
103             exit(1);
104         }
105
106         sin.sin_family = AF_INET;
107         sin.sin_addr.s_addr = addr;    /* Fill in the  appropriate address. */
108         sin.sin_port = htons(2345);
109         if (connect(tfd, (struct sockaddr *)&sin, sizeof(sin))<0) {
110             perror("connect");
111             exit(1);
112         }
113
114         baddr = (off_t)buf;
115         len = sizeof(buf);
116         while (len > 0) {
117             ssize_t res;
118             res = sendfile(tfd, SFV_FD_SELF, &baddr, len);
119             if (res == -1)
120                     if (errno != EINTR) {
121                             perror("sendfile");
122                             exit(1);
123                     } else continue;
124             len -= res;
125         }
126
127
128       Example 2 Transferring Files to Sockets
129
130
131       The following program demonstrates a transfer of files to sockets:
132
133
134         int ffd, tfd;
135         off_t off;
136         struct sockaddr_in sin;
137         in_addr_t  addr;
138         int len;
139         struct stat stat_buf;
140         ssize_t len;
141
142         ffd = open("file", O_RDONLY);
143         if (ffd == -1) {
144             perror("open");
145             exit(1);
146         }
147
148         tfd = socket(AF_INET, SOCK_STREAM, 0);
149         if (tfd == -1) {
150             perror("socket");
151             exit(1);
152         }
153
154         sin.sin_family = AF_INET;
155         sin.sin_addr = addr;    /* Fill in the  appropriate address. */
156         sin.sin_port = htons(2345);
157         if (connect(tfd, (struct sockaddr *) &sin, sizeof(sin)) <0) {
158             perror("connect");
159             exit(1);
160         }
161
162         if (fstat(ffd, &stat_buf) == -1) {
163             perror("fstat");
164             exit(1);
165         }
166
167         len = stat_buf.st_size;
168         while (len > 0) {
169             ssize_t res;
170             res = sendfile(tfd, ffd, &off, len);
171             if (res == -1)
172                     if (errno != EINTR) {
173                             perror("sendfile");
174                             exit(1);
175                     } else continue;
176             len -= res;
177         }
178
179

ATTRIBUTES

181       See attributes(5)  for descriptions of the following attributes:
182
183
184
185
186       ┌─────────────────────────────┬─────────────────────────────┐
187       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
188       ├─────────────────────────────┼─────────────────────────────┤
189       │Interface Stability          │Evolving                     │
190       ├─────────────────────────────┼─────────────────────────────┤
191       │MT-Level                     │MT-Safe                      │
192       └─────────────────────────────┴─────────────────────────────┘
193