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