sendfilev(3ext)

1sendfilev(3EXT)           Extended Library Functions           sendfilev(3EXT)
2
3
4

NAME

6       sendfilev - send a file
7

SYNOPSIS

9       cc [ flag... ] file... -lsendfile  [ library... ]
10       #include <sys/sendfile.h>
11
12       ssize_t sendfilev(int fildes, const struct sendfilevec *vec,
13            int sfvcnt, size_t *xferred);
14
15

PARAMETERS

17       The sendfilev() function supports the following parameters:
18
19       fildes     A file descriptor to a regular file or to a AF_NCA, AF_INET,
20                  or AF_INET6 family type SOCK_STREAM socket that is open  for
21                  writing. For AF_NCA, the protocol type should be zero.
22
23
24       vec        An  array  of  SENDFILEVEC_T,  as defined in the sendfilevec
25                  structure above.
26
27
28       sfvcnt     The number of members in vec.
29
30
31       xferred    The total number of bytes written to out_fd.
32
33

DESCRIPTION

35       The sendfilev() function attempts to write data from the sfvcnt buffers
36       specified   by  the  members  of  vec  array:  vec[0],  vec[1],  ...  ,
37       vec[sfvcnt-1]. The fildes argument is a file descriptor  to  a  regular
38       file  or  to  an  AF_NCA,  AF_INET, or AF_INET6 family type SOCK_STREAM
39       socket that is open for writing.
40
41
42       This function is analogous to writev(2), but can read from both buffers
43       and  file descriptors. Unlike writev(), in the case of multiple writers
44       to a file the effect of sendfilev()  is  not  necessarily  atomic;  the
45       writes may be interleaved. Application-specific synchronization methods
46       must be employed if this causes problems.
47
48
49       The following is the sendfilevec structure:
50
51         typedef struct sendfilevec {
52                 int     sfv_fd;         /* input fd */
53                 uint_t  sfv_flag;       /* Flags. see below */
54                 off_t   sfv_off;        /* offset to start reading from */
55                 size_t  sfv_len;        /* amount of data */
56         } sendfilevec_t;
57
58         #define SFV_FD_SELF     (-2)
59
60
61
62       To send a file, open the file for reading and point sfv_fd to the  file
63       descriptor  returned  as  a result. See open(2). sfv_off should contain
64       the offset within the file. sfv_len should have the length of the  file
65       to be transferred.
66
67
68       The  xferred  argument  is  updated to record the total number of bytes
69       written to out_fd.
70
71
72       The sfv_flag field is reserved and should be set to zero.
73
74
75       To send data directly from the address space of the process, set sfv_fd
76       to SFV_FD_SELF. sfv_off should point to the data, with sfv_len contain‐
77       ing the length of the buffer.
78

RETURN VALUES

80       Upon successful completion, the sendfilev() function returns total num‐
81       ber  of bytes written to out_fd. Otherwise, it returns -1, and errno is
82       set to indicate the error. The xferred argument contains the amount  of
83       data  successfuly  transferred, which can be used to discover the error
84       vector.
85

ERRORS

87       EACCES          The process does not have appropriate privileges or one
88                       of the files pointed by sfv_fd does not  have appropri‐
89                       ate permissions.
90
91
92       EAFNOSUPPORT    The  implementation  does  not  support  the  specified
93                       address family for socket.
94
95
96       EAGAIN          Mandatory  file  or record locking is set on either the
97                       file descriptor or output file descriptor if it  points
98                       at  regular  files.  O_NDELAY or O_NONBLOCK is set, and
99                       there is a blocking record lock. An  attempt  has  been
100                       made  to write to a stream that cannot accept data with
101                       the O_NDELAY or the O_NONBLOCK flag set.
102
103
104       EBADF           The fildes argument is not a valid descriptor open  for
105                       writing  or  an sfv_fd is invalid or not open for read‐
106                       ing.
107
108
109       EFAULT          The vec argument points to an illegal address.
110
111                       The xferred argument points to an illegal address.
112
113
114       EINTR           A signal was caught during the write operation  and  no
115                       data was transferred.
116
117
118       EINVAL          The sfvcnt argument was less than or equal to 0. One of
119                       the sfv_len values in vec array was less than or  equal
120                       to  0,  or greater than the file size. An sfv_fd is not
121                       seekable.
122
123                       Fewer bytes were transferred than were requested.
124
125
126       EIO             An I/O error occurred while accessing the file system.
127
128
129       EPIPE           The fildes argument is a socket that has been shut down
130                       for writing.
131
132
133       EPROTOTYPE      The socket type is not supported.
134
135

USAGE

137       The  sendfilev()  function has a transitional interface for 64-bit file
138       offsets. See lf64(5).
139

EXAMPLES

141       The following example sends 2 vectors, one of HEADER data and a file of
142       length  100  over  sockfd.  sockfd  is  in  a connected state, that is,
143       socket(), accept(), and bind() operation are complete.
144
145         #include <sys/sendfile.h>
146         .
147         .
148         .
149         int
150         main (int argc, char *argv[]){
151           int sockfd;
152           ssize_t ret;
153           size_t xfer;
154           struct sendfilevec vec[2];
155             .
156             .
157             .
158           vec[0].sfv_fd = SFV_FD_SELF;
159           vec[0].sfv_flag = 0;
160           vec[0].sfv_off = "HEADER_DATA";
161           vec[0].sfv_len = strlen("HEADER_DATA");
162           vec[1].sfv_fd = open("input_file",.... );
163           vec[1].sfv_flag = 0;
164           vec[1].sfv_off = 0;
165           vec[1].sfv_len = 100;
166
167           ret = sendfilev(sockfd, vec, 2, &xfer);
168         .
169         .
170         .
171         }
172
173

ATTRIBUTES

175       See attributes(5) for descriptions of the following attributes:
176
177
178
179
180       ┌─────────────────────────────┬─────────────────────────────┐
181       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
182       ├─────────────────────────────┼─────────────────────────────┤
183       │Interface Stability          │Committed                    │
184       ├─────────────────────────────┼─────────────────────────────┤
185       │MT-Level                     │MT-Safe                      │
186       └─────────────────────────────┴─────────────────────────────┘
187