1.\" Copyright (c) 1998, David Greenman
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice unmodified, this list of conditions, and the following
9.\" disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
| 1.\" Copyright (c) 1998, David Greenman
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice unmodified, this list of conditions, and the following
9.\" disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
|
26.\" $FreeBSD: head/lib/libc/sys/sendfile.2 50476 1999-08-28 00:22:10Z peter $
| 26.\" $FreeBSD: head/lib/libc/sys/sendfile.2 57686 2000-03-02 09:14:21Z sheldonh $
|
27.\"
28.Dd November 5, 1998
29.Dt SENDFILE 2
30.Os
31.Sh NAME
32.Nm sendfile
33.Nd send a file to a socket
34.Sh SYNOPSIS
35.Fd #include <sys/types.h>
36.Fd #include <sys/socket.h>
37.Fd #include <sys/uio.h>
38.Ft int
39.Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags"
40.Sh DESCRIPTION
41.Fn Sendfile
42sends a regular file specified by descriptor
43.Fa fd
44out a stream socket specified by descriptor
45.Fa s .
46.Pp
47The
48.Fa offset
| 27.\"
28.Dd November 5, 1998
29.Dt SENDFILE 2
30.Os
31.Sh NAME
32.Nm sendfile
33.Nd send a file to a socket
34.Sh SYNOPSIS
35.Fd #include <sys/types.h>
36.Fd #include <sys/socket.h>
37.Fd #include <sys/uio.h>
38.Ft int
39.Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags"
40.Sh DESCRIPTION
41.Fn Sendfile
42sends a regular file specified by descriptor
43.Fa fd
44out a stream socket specified by descriptor
45.Fa s .
46.Pp
47The
48.Fa offset
|
49argument specifies where to begin in the file. The
| 49argument specifies where to begin in the file.
50The
|
50.Fa nbytes
51argument specifies how many bytes of the file should be sent, with 0 having the special
52meaning of send until the end of file has been reached.
53.Pp
54An optional header and/or trailer can be sent before and after the file data by specifying
55a pointer to a struct sf_hdtr, which has the following structure:
56.Pp
57.Bd -literal -offset indent -compact
58struct sf_hdtr {
59 struct iovec *headers; /* pointer to header iovecs */
60 int hdr_cnt; /* number of header iovecs */
61 struct iovec *trailers; /* pointer to trailer iovecs */
62 int trl_cnt; /* number of trailer iovecs */
63};
64.Ed
65.Pp
66The
67.Fa headers
68and
69.Fa tailers
| 51.Fa nbytes
52argument specifies how many bytes of the file should be sent, with 0 having the special
53meaning of send until the end of file has been reached.
54.Pp
55An optional header and/or trailer can be sent before and after the file data by specifying
56a pointer to a struct sf_hdtr, which has the following structure:
57.Pp
58.Bd -literal -offset indent -compact
59struct sf_hdtr {
60 struct iovec *headers; /* pointer to header iovecs */
61 int hdr_cnt; /* number of header iovecs */
62 struct iovec *trailers; /* pointer to trailer iovecs */
63 int trl_cnt; /* number of trailer iovecs */
64};
65.Ed
66.Pp
67The
68.Fa headers
69and
70.Fa tailers
|
70pointers, if non-NULL, point to arrays of struct iovec structures. See the
| 71pointers, if non-NULL, point to arrays of struct iovec structures.
72See the
|
71.Fn writev
| 73.Fn writev
|
72system call for information on the iovec structure. The number of iovecs in these
| 74system call for information on the iovec structure.
75The number of iovecs in these
|
73arrays is specified by
74.Fa hdr_cnt
75and
76.Fa trl_cnt .
77.Pp
78If non-NULL, the system will write the total number of bytes sent on the socket to the
79variable pointed to by
80.Fa sbytes .
81.Pp
82The
83.Fa flags
84argument is currently undefined and should be specified as 0.
85.Pp
86When using a socket marked for non-blocking I/O,
87.Fn sendfile
| 76arrays is specified by
77.Fa hdr_cnt
78and
79.Fa trl_cnt .
80.Pp
81If non-NULL, the system will write the total number of bytes sent on the socket to the
82variable pointed to by
83.Fa sbytes .
84.Pp
85The
86.Fa flags
87argument is currently undefined and should be specified as 0.
88.Pp
89When using a socket marked for non-blocking I/O,
90.Fn sendfile
|
88may send fewer bytes than requested. In this case, the number of bytes successfully
| 91may send fewer bytes than requested.
92In this case, the number of bytes successfully
|
89written is returned in
90.Fa *sbytes
91(if specified),
92and the error
93.Er EAGAIN
94is returned.
95.Sh IMPLEMENTATION NOTES
96.Pp
97The FreeBSD implementation of
98.Fn sendfile
99is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided.
100.Sh RETURN VALUES
101Upon successful completion,
102.Fn sendfile
103returns 0. Otherwise a -1 is returned and the global variable
104.Va errno
105is set to indicate the error.
106.Sh ERRORS
107.Bl -tag -width Er
108.It Bq Er EBADF
109.Fa fd
110is not a valid file descriptor.
111.It Bq Er EBADF
112.Fa s
113is not a valid socket descriptor.
114.It Bq Er ENOTSOCK
115.Fa s
116is not a socket.
117.It Bq Er EINVAL
118.Fa fd
119is not a regular file.
120.It Bq Er EINVAL
121.Fa s
122is not a SOCK_STREAM type socket.
123.It Bq Er EINVAL
124.Fa offset
125is negative or out of range.
126.It Bq Er ENOTCONN
127.Fa s
128points to an unconnected socket.
129.It Bq Er EPIPE
130The socket peer has closed the connection.
131.It Bq Er EIO
132An error occurred while reading from
133.Fa fd .
134.It Bq Er EFAULT
135An invalid address was specified for a parameter.
136.It Bq Er EAGAIN
137The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled.
138If specified, the number of bytes successfully sent will be returned in
139.Fa *sbytes .
140.El
141.Sh SEE ALSO
142.Xr open 2 ,
143.Xr send 2 ,
144.Xr socket 2 ,
145.Xr writev 2
146.Sh HISTORY
147.Fn sendfile
148first appeared in
149.Fx 3.0 .
150This manual page first appeared in
151.Fx 3.1 .
152.Sh AUTHORS
153.Fn sendfile
154and this manual page were written by
155.An David Greenman Aq dg@root.com .
| 93written is returned in
94.Fa *sbytes
95(if specified),
96and the error
97.Er EAGAIN
98is returned.
99.Sh IMPLEMENTATION NOTES
100.Pp
101The FreeBSD implementation of
102.Fn sendfile
103is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided.
104.Sh RETURN VALUES
105Upon successful completion,
106.Fn sendfile
107returns 0. Otherwise a -1 is returned and the global variable
108.Va errno
109is set to indicate the error.
110.Sh ERRORS
111.Bl -tag -width Er
112.It Bq Er EBADF
113.Fa fd
114is not a valid file descriptor.
115.It Bq Er EBADF
116.Fa s
117is not a valid socket descriptor.
118.It Bq Er ENOTSOCK
119.Fa s
120is not a socket.
121.It Bq Er EINVAL
122.Fa fd
123is not a regular file.
124.It Bq Er EINVAL
125.Fa s
126is not a SOCK_STREAM type socket.
127.It Bq Er EINVAL
128.Fa offset
129is negative or out of range.
130.It Bq Er ENOTCONN
131.Fa s
132points to an unconnected socket.
133.It Bq Er EPIPE
134The socket peer has closed the connection.
135.It Bq Er EIO
136An error occurred while reading from
137.Fa fd .
138.It Bq Er EFAULT
139An invalid address was specified for a parameter.
140.It Bq Er EAGAIN
141The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled.
142If specified, the number of bytes successfully sent will be returned in
143.Fa *sbytes .
144.El
145.Sh SEE ALSO
146.Xr open 2 ,
147.Xr send 2 ,
148.Xr socket 2 ,
149.Xr writev 2
150.Sh HISTORY
151.Fn sendfile
152first appeared in
153.Fx 3.0 .
154This manual page first appeared in
155.Fx 3.1 .
156.Sh AUTHORS
157.Fn sendfile
158and this manual page were written by
159.An David Greenman Aq dg@root.com .
|