share/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 "Nov 3, 2017"
   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.
  42 .SH ERRORS
  43 .LP
  44 The \fBsendfile()\fR function will fail if:
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBEAFNOSUPPORT\fR\fR
  49 .ad
  50 .RS 16n
  51 The implementation does not support the specified address family for socket.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBEAGAIN\fR\fR
  58 .ad
  59 .RS 16n
  60 Mandatory file or record locking is set on either the file descriptor or output
  61 file descriptor if it points at regular files. \fBO_NDELAY\fR or
  62 \fBO_NONBLOCK\fR is  set, and there is a blocking record lock. An attempt has
  63 been made to write to a stream that cannot accept data with the \fBO_NDELAY\fR
  64 or the \fBO_NONBLOCK\fR flag set.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBEBADF\fR\fR
  71 .ad
  72 .RS 16n
  73 The \fIout_fd\fR or \fIin_fd\fR argument is either not a valid file descriptor,
  74 \fIout_fd\fR is not opened for writing. or \fIin_fd\fR is not opened for
  75 reading.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBEINVAL\fR\fR
  82 .ad
  83 .RS 16n
  84 The offset cannot be represented by the \fBoff_t\fR structure, or the length is
  85 negative when cast to \fBssize_t\fR.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBEIO\fR\fR
  92 .ad
  93 .RS 16n
  94 An I/O error occurred while accessing the file system.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBENOTCONN\fR\fR
 101 .ad
 102 .RS 16n
 103 The socket is not connected.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBEOPNOTSUPP\fR\fR
 110 .ad
 111 .RS 16n
 112 The socket type is not supported.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBEPIPE\fR\fR
 119 .ad
 120 .RS 16n
 121 The \fIout_fd\fR argument is no longer connected to the peer endpoint.
 122 The \fBSIGPIPE\fR signal is generated to the calling thread.
 123 The process dies unless special provisions were taken to catch or ignore
 124 the signal.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBEINTR\fR\fR
 131 .ad
 132 .RS 16n
 133 A signal was caught during the write operation and no data was transferred.
 134 .RE
 135
 136 .SH USAGE
 137 .LP
 138 The \fBsendfile()\fR function has a transitional interface for 64-bit file
 139 offsets. See \fBlf64\fR(5).
 140 .SH EXAMPLES
 141 .LP
 142 \fBExample 1 \fRSending a Buffer Over a Socket
 143 .sp
 144 .LP
 145 The following example demonstrates how to send the buffer \fIbuf\fR over a
 146 socket. At the end, it prints the number of bytes transferred over the socket
 147 from the buffer. It assumes that \fIaddr\fR will be filled up appropriately,
 148 depending upon where to send the buffer.
 149
 150 .sp
 151 .in +2
 152 .nf
 153 int tfd;
 154 off_t baddr;
 155 struct sockaddr_in sin;
 156 char buf[64 * 1024];
 157 in_addr_t addr;
 158 size_t len;
 159
 160 tfd = socket(AF_INET, SOCK_STREAM, 0);
 161 if (tfd == -1) {
 162     perror("socket");
 163     exit(1);
 164 }
 165
 166 sin.sin_family = AF_INET;
 167 sin.sin_addr.s_addr = addr;    /* Fill in the  appropriate address. */
 168 sin.sin_port = htons(2345);
 169 if (connect(tfd, (struct sockaddr *)&sin, sizeof(sin))<0) {
 170     perror("connect");
 171     exit(1);
 172 }
 173
 174 baddr = (off_t)buf;
 175 len = sizeof(buf);
 176 while (len > 0) {
 177     ssize_t res;
 178     res = sendfile(tfd, SFV_FD_SELF, &baddr, len);
 179     if (res == -1)
 180             if (errno != EINTR) {
 181                     perror("sendfile");
 182                     exit(1);
 183             } else continue;
 184     len -= res;
 185 }
 186 .fi
 187 .in -2
 188
 189 .LP
 190 \fBExample 2 \fRTransferring Files to Sockets
 191 .sp
 192 .LP
 193 The following program demonstrates a transfer of files to sockets:
 194
 195 .sp
 196 .in +2
 197 .nf
 198 int ffd, tfd;
 199 off_t off;
 200 struct sockaddr_in sin;
 201 in_addr_t  addr;
 202 int len;
 203 struct stat stat_buf;
 204 ssize_t len;
 205
 206 ffd = open("file", O_RDONLY);
 207 if (ffd == -1) {
 208     perror("open");
 209     exit(1);
 210 }
 211
 212 tfd = socket(AF_INET, SOCK_STREAM, 0);
 213 if (tfd == -1) {
 214     perror("socket");
 215     exit(1);
 216 }
 217
 218 sin.sin_family = AF_INET;
 219 sin.sin_addr = addr;    /* Fill in the  appropriate address. */
 220 sin.sin_port = htons(2345);
 221 if (connect(tfd, (struct sockaddr *) &sin, sizeof(sin)) <0) {
 222     perror("connect");
 223     exit(1);
 224 }
 225
 226 if (fstat(ffd, &stat_buf) == -1) {
 227     perror("fstat");
 228     exit(1);
 229 }
 230
 231 len = stat_buf.st_size;
 232 while (len > 0) {
 233     ssize_t res;
 234     res = sendfile(tfd, ffd, &off, len);
 235     if (res == -1)
 236             if (errno != EINTR) {
 237                     perror("sendfile");
 238                     exit(1);
 239             } else continue;
 240     len -= res;
 241 }
 242 .fi
 243 .in -2
 244
 245 .SH ATTRIBUTES
 246 .LP
 247 See \fBattributes\fR(5)  for descriptions of the following attributes:
 248 .sp
 249
 250 .sp
 251 .TS
 252 box;
 253 c | c
 254 l | l .
 255 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 256 _
 257 Interface Stability     Evolving
 258 _
 259 MT-Level        MT-Safe
 260 .TE
 261
 262 .SH SEE ALSO
 263 .LP
 264 \fBopen\fR(2), \fBlibsendfile\fR(3LIB), \fBsendfilev\fR(3EXT),
 265 \fBsocket\fR(3SOCKET), \fBattributes\fR(5), \fBlf64\fR(5)