share/man/man3ext/sendfilev.3ext

   1 '\" te
   2 .\" Copyright (c) 2009, 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 SENDFILEV 3EXT "Feb 25, 2009"
   7 .SH NAME
   8 sendfilev \- send a file
   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 \fBsendfilev\fR(\fBint\fR \fIfildes\fR, \fBconst struct sendfilevec *\fR\fIvec\fR,
  16      \fBint\fR \fIsfvcnt\fR, \fBsize_t *\fR\fIxferred\fR);
  17 .fi
  18
  19 .SH PARAMETERS
  20 .sp
  21 .LP
  22 The \fBsendfilev()\fR function supports the following parameters:
  23 .sp
  24 .ne 2
  25 .na
  26 \fB\fIfildes\fR\fR
  27 .ad
  28 .RS 11n
  29 A file descriptor to a regular file or to a \fBAF_INET\fR or
  30 \fBAF_INET6\fR family type \fBSOCK_STREAM\fR socket that is open for writing.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIvec\fR\fR
  37 .ad
  38 .RS 11n
  39 An array of \fBSENDFILEVEC_T\fR, as defined in the \fBsendfilevec\fR structure
  40 above.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIsfvcnt\fR\fR
  47 .ad
  48 .RS 11n
  49 The number of members in \fIvec\fR.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIxferred\fR\fR
  56 .ad
  57 .RS 11n
  58 The total number of bytes written to \fBout_fd\fR.
  59 .RE
  60
  61 .SH DESCRIPTION
  62 .sp
  63 .LP
  64 The \fBsendfilev()\fR function attempts to write data from the \fIsfvcnt\fR
  65 buffers specified by the members of \fIvec\fR array: \fBvec[0], vec[1], ... ,
  66 vec[sfvcnt-1]\fR. The \fIfildes\fR argument is a file descriptor to a regular
  67 file or to an \fBAF_INET\fR or \fBAF_INET6\fR family type
  68 \fBSOCK_STREAM\fR socket that is open for writing.
  69 .sp
  70 .LP
  71 This function is analogous to \fBwritev\fR(2), but can read from both buffers
  72 and file descriptors. Unlike \fBwritev()\fR, in the case of multiple writers to
  73 a file the effect of \fBsendfilev()\fR is not necessarily atomic; the writes
  74 may be interleaved. Application-specific synchronization methods must be
  75 employed if this causes problems.
  76 .sp
  77 .LP
  78 The following is the \fBsendfilevec\fR structure:
  79 .sp
  80 .in +2
  81 .nf
  82 typedef struct sendfilevec {
  83         int     sfv_fd;         /* input fd */
  84         uint_t  sfv_flag;       /* Flags. see below */
  85         off_t   sfv_off;        /* offset to start reading from */
  86         size_t  sfv_len;        /* amount of data */
  87 } sendfilevec_t;
  88
  89 #define SFV_FD_SELF     (-2)
  90 .fi
  91 .in -2
  92
  93 .sp
  94 .LP
  95 To send a file, open the file for reading and point \fBsfv_fd\fR to the file
  96 descriptor returned as a result. See \fBopen\fR(2). \fBsfv_off\fR should
  97 contain the offset within the file. \fBsfv_len\fR should have the length of the
  98 file to be transferred.
  99 .sp
 100 .LP
 101 The \fIxferred\fR argument is updated to record the total number of bytes
 102 written to \fBout_fd\fR.
 103 .sp
 104 .LP
 105 The \fBsfv_flag\fR field is reserved and should be set to zero.
 106 .sp
 107 .LP
 108 To send data directly from the address space of the process, set \fBsfv_fd\fR
 109 to \fBSFV_FD_SELF\fR. \fBsfv_off\fR should point to the data, with
 110 \fBsfv_len\fR containing the length of the buffer.
 111 .SH RETURN VALUES
 112 .sp
 113 .LP
 114 Upon successful completion, the \fBsendfilev()\fR function returns total number
 115 of bytes written to \fBout_fd\fR. Otherwise, it returns \fB-1\fR, and
 116 \fBerrno\fR is set to indicate the error. The \fIxferred\fR argument contains
 117 the amount of data successfuly transferred, which can be used to discover the
 118 error vector.
 119 .SH ERRORS
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBEACCES\fR\fR
 124 .ad
 125 .RS 16n
 126 The process does not have appropriate privileges or one of the files pointed by
 127 \fBsfv_fd\fR does not  have appropriate permissions.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBEAFNOSUPPORT\fR\fR
 134 .ad
 135 .RS 16n
 136 The implementation does not support the specified address family for socket.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBEAGAIN\fR\fR
 143 .ad
 144 .RS 16n
 145 Mandatory file or record locking is set on either the file descriptor or output
 146 file descriptor if it points at regular files. \fBO_NDELAY\fR or
 147 \fBO_NONBLOCK\fR is set, and there is a blocking record lock. An attempt has
 148 been made to write to a stream that cannot accept data with the \fBO_NDELAY\fR
 149 or the \fBO_NONBLOCK\fR flag set.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBEBADF\fR\fR
 156 .ad
 157 .RS 16n
 158 The \fIfildes\fR argument is not a valid descriptor open for writing or an
 159 \fBsfv_fd\fR is invalid or not open for reading.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBEFAULT\fR\fR
 166 .ad
 167 .RS 16n
 168 The \fIvec\fR argument points to an illegal address.
 169 .sp
 170 The \fIxferred\fR argument points to an illegal address.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBEINTR\fR\fR
 177 .ad
 178 .RS 16n
 179 A signal was caught during the write operation and no data was transferred.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fBEINVAL\fR\fR
 186 .ad
 187 .RS 16n
 188 The \fIsfvcnt\fR argument was less than or equal to \fB0\fR. One of the
 189 \fBsfv_len\fR values in \fIvec\fR array was less than or equal to \fB0\fR, or
 190 greater than the file size. An \fBsfv_fd\fR is not seekable.
 191 .sp
 192 Fewer bytes were transferred than were requested.
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBEIO\fR\fR
 199 .ad
 200 .RS 16n
 201 An I/O error occurred while accessing the file system.
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBEPIPE\fR\fR
 208 .ad
 209 .RS 16n
 210 The \fIfildes\fR argument is a socket that has been shut down for writing.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBEPROTOTYPE\fR\fR
 217 .ad
 218 .RS 16n
 219 The socket type is not supported.
 220 .RE
 221
 222 .SH USAGE
 223 .sp
 224 .LP
 225 The \fBsendfilev()\fR function has a transitional interface for 64-bit file
 226 offsets. See \fBlf64\fR(5).
 227 .SH EXAMPLES
 228 .sp
 229 .LP
 230 The following example sends 2 vectors, one of HEADER data and a file of length
 231 100 over \fBsockfd\fR. \fBsockfd\fR is in a connected state, that is,
 232 \fBsocket()\fR, \fBaccept()\fR, and \fBbind()\fR operation are complete.
 233 .sp
 234 .in +2
 235 .nf
 236 #include <sys/sendfile.h>
 237 \&.
 238 \&.
 239 \&.
 240 int
 241 main (int argc, char *argv[]){
 242   int sockfd;
 243   ssize_t ret;
 244   size_t xfer;
 245   struct sendfilevec vec[2];
 246     .
 247     .
 248     .
 249   vec[0].sfv_fd = SFV_FD_SELF;
 250   vec[0].sfv_flag = 0;
 251   vec[0].sfv_off = "HEADER_DATA";
 252   vec[0].sfv_len = strlen("HEADER_DATA");
 253   vec[1].sfv_fd = open("input_file",.... );
 254   vec[1].sfv_flag = 0;
 255   vec[1].sfv_off = 0;
 256   vec[1].sfv_len = 100;
 257
 258   ret = sendfilev(sockfd, vec, 2, &xfer);
 259 \&.
 260 \&.
 261 \&.
 262 }
 263 .fi
 264 .in -2
 265
 266 .SH ATTRIBUTES
 267 .sp
 268 .LP
 269 See \fBattributes\fR(5) for descriptions of the following attributes:
 270 .sp
 271
 272 .sp
 273 .TS
 274 box;
 275 c | c
 276 l | l .
 277 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 278 _
 279 Interface Stability     Committed
 280 _
 281 MT-Level        MT-Safe
 282 .TE
 283
 284 .SH SEE ALSO
 285 .sp
 286 .LP
 287 \fBopen\fR(2), \fBwritev\fR(2), \fBlibsendfile\fR(3LIB), \fBsendfile\fR(3EXT),
 288 \fBsocket\fR(3SOCKET), \fBattributes\fR(5)