usr/src/man/man3ext/sendfile.3ext

   1 '\" te
   2 .\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SENDFILE 3EXT "Jul 19, 2018"
   7 .SH NAME
   8 sendfile \- send files over sockets or copy files to files
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lsendfile\fR [ \fIlibrary\fR\&.\|.\|. ]
  13 #include <sys/sendfile.h>
  14
  15 \fBssize_t\fR \fBsendfile\fR(\fBint\fR \fIout_fd\fR, \fBint\fR \fIin_fd\fR, \fBoff_t *\fR\fIoff\fR, \fBsize_t\fR \fIlen\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBsendfile()\fR function copies data from \fIin_fd\fR to \fIout_fd\fR
  21 starting at offset \fIoff\fR and of length \fIlen\fR bytes. The \fIin_fd\fR
  22 argument should be a file descriptor to a regular file opened for reading. See
  23 \fBopen\fR(2). The \fIout_fd\fR argument should be a file descriptor to a
  24 regular file opened for writing or to a connected \fBAF_INET\fR or
  25 \fBAF_INET6\fR socket of \fBSOCK_STREAM\fR type. See \fBsocket\fR(3SOCKET). The
  26 \fIoff\fR argument is a pointer to a variable holding the input file pointer
  27 position from which the data will be read. After \fBsendfile()\fR has
  28 completed, the variable will be set to the offset of the byte following the
  29 last byte that was read. The \fBsendfile()\fR function does not modify the
  30 current file pointer of \fIin_fd\fR, but does modify the file pointer for
  31 \fIout_fd\fR if it is a regular file.
  32 .sp
  33 .LP
  34 The \fBsendfile()\fR function can also be used to send buffers by pointing
  35 \fIin_fd\fR to \fBSFV_FD_SELF\fR.
  36 .SH RETURN VALUES
  37 .LP
  38 Upon successful completion, \fBsendfile()\fR returns the total number of bytes
  39 written to \fIout_fd\fR and also updates the offset to point to the byte that
  40 follows the last byte read. Otherwise, it returns \fB-1\fR, and \fBerrno\fR is
  41 set to indicate the error.  In some error cases \fBsendfile()\fR may still
  42 write some data before encountering an error and returning \fB-1\fR.  When that
  43 occurs, \fIoff\fR is updated to point to the byte that follows the last byte
  44 copied and should be compared with its value before calling \fBsendfile()\fR to
  45 determine how much data was sent.
  46 .SH ERRORS
  47 .LP
  48 The \fBsendfile()\fR function will fail if:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBEAFNOSUPPORT\fR\fR
  53 .ad
  54 .RS 16n
  55 The implementation does not support the specified address family for socket.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBEAGAIN\fR\fR
  62 .ad
  63 .RS 16n
  64 Mandatory file or record locking is set on either the file descriptor or output
  65 file descriptor if it points at regular files. \fBO_NDELAY\fR or
  66 \fBO_NONBLOCK\fR is  set, and there is a blocking record lock. An attempt has
  67 been made to write to a stream that cannot accept data with the \fBO_NDELAY\fR
  68 or the \fBO_NONBLOCK\fR flag set.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBEBADF\fR\fR
  75 .ad
  76 .RS 16n
  77 The \fIout_fd\fR or \fIin_fd\fR argument is either not a valid file descriptor,
  78 \fIout_fd\fR is not opened for writing. or \fIin_fd\fR is not opened for
  79 reading.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBEINVAL\fR\fR
  86 .ad
  87 .RS 16n
  88 The offset cannot be represented by the \fBoff_t\fR structure, or the length is
  89 negative when cast to \fBssize_t\fR.
  90 .sp
  91 Fewer bytes were transferred than were requested.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBEIO\fR\fR
  98 .ad
  99 .RS 16n
 100 An I/O error occurred while accessing the file system.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBENOTCONN\fR\fR
 107 .ad
 108 .RS 16n
 109 The socket is not connected.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBEOPNOTSUPP\fR\fR
 116 .ad
 117 .RS 16n
 118 The socket type is not supported.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBEPIPE\fR\fR
 125 .ad
 126 .RS 16n
 127 The \fIout_fd\fR argument is no longer connected to the peer endpoint.
 128 The \fBSIGPIPE\fR signal is generated to the calling thread.
 129 The process dies unless special provisions were taken to catch or ignore
 130 the signal.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBEINTR\fR\fR
 137 .ad
 138 .RS 16n
 139 A signal was caught during the write operation and no data was transferred.
 140 .RE
 141
 142 .SH USAGE
 143 .LP
 144 The \fBsendfile()\fR function has a transitional interface for 64-bit file
 145 offsets. See \fBlf64\fR(5).
 146 .SH EXAMPLES
 147 .LP
 148 \fBExample 1 \fRSending a Buffer Over a Socket
 149 .sp
 150 .LP
 151 The following example demonstrates how to send the buffer \fIbuf\fR over a
 152 socket. At the end, it prints the number of bytes transferred over the socket
 153 from the buffer. It assumes that \fIaddr\fR will be filled up appropriately,
 154 depending upon where to send the buffer.
 155
 156 .sp
 157 .in +2
 158 .nf
 159 int tfd;
 160 off_t baddr;
 161 struct sockaddr_in sin;
 162 char buf[64 * 1024];
 163 in_addr_t addr;
 164 size_t len;
 165
 166 tfd = socket(AF_INET, SOCK_STREAM, 0);
 167 if (tfd == -1) {
 168     perror("socket");
 169     exit(1);
 170 }
 171
 172 sin.sin_family = AF_INET;
 173 sin.sin_addr.s_addr = addr;    /* Fill in the  appropriate address. */
 174 sin.sin_port = htons(2345);
 175 if (connect(tfd, (struct sockaddr *)&sin, sizeof(sin))<0) {
 176     perror("connect");
 177     exit(1);
 178 }
 179
 180 baddr = (off_t)buf;
 181 len = sizeof(buf);
 182 while (len > 0) {
 183     ssize_t res;
 184     res = sendfile(tfd, SFV_FD_SELF, &baddr, len);
 185     if (res == -1)
 186             if (errno != EINTR) {
 187                     perror("sendfile");
 188                     exit(1);
 189             } else continue;
 190     len -= res;
 191 }
 192 .fi
 193 .in -2
 194
 195 .LP
 196 \fBExample 2 \fRTransferring Files to Sockets
 197 .sp
 198 .LP
 199 The following program demonstrates a transfer of files to sockets:
 200
 201 .sp
 202 .in +2
 203 .nf
 204 int ffd, tfd;
 205 off_t off;
 206 struct sockaddr_in sin;
 207 in_addr_t  addr;
 208 int len;
 209 struct stat stat_buf;
 210 ssize_t len;
 211
 212 ffd = open("file", O_RDONLY);
 213 if (ffd == -1) {
 214     perror("open");
 215     exit(1);
 216 }
 217
 218 tfd = socket(AF_INET, SOCK_STREAM, 0);
 219 if (tfd == -1) {
 220     perror("socket");
 221     exit(1);
 222 }
 223
 224 sin.sin_family = AF_INET;
 225 sin.sin_addr = addr;    /* Fill in the  appropriate address. */
 226 sin.sin_port = htons(2345);
 227 if (connect(tfd, (struct sockaddr *) &sin, sizeof(sin)) <0) {
 228     perror("connect");
 229     exit(1);
 230 }
 231
 232 if (fstat(ffd, &stat_buf) == -1) {
 233     perror("fstat");
 234     exit(1);
 235 }
 236
 237 len = stat_buf.st_size;
 238 while (len > 0) {
 239     ssize_t res;
 240     res = sendfile(tfd, ffd, &off, len);
 241     if (res == -1)
 242             if (errno != EINTR) {
 243                     perror("sendfile");
 244                     exit(1);
 245             } else continue;
 246     len -= res;
 247 }
 248 .fi
 249 .in -2
 250
 251 .SH ATTRIBUTES
 252 .LP
 253 See \fBattributes\fR(5)  for descriptions of the following attributes:
 254 .sp
 255
 256 .sp
 257 .TS
 258 box;
 259 c | c
 260 l | l .
 261 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 262 _
 263 Interface Stability     Evolving
 264 _
 265 MT-Level        MT-Safe
 266 .TE
 267
 268 .SH SEE ALSO
 269 .LP
 270 \fBopen\fR(2), \fBlibsendfile\fR(3LIB), \fBsendfilev\fR(3EXT),
 271 \fBsocket\fR(3SOCKET), \fBattributes\fR(5), \fBlf64\fR(5)