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