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