| blob | a01d30fa987cbb911148bdcb97c551c0dc2add45 |
1 .\" $NetBSD: write.2,v 1.29 2006/10/13 20:58:50 wiz Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)write.2 8.5 (Berkeley) 4/2/94
31 .\"
32 .Dd December 30, 2002
33 .Dt WRITE 2
34 .Os
35 .Sh NAME
36 .Nm write ,
37 .Nm writev ,
38 .Nm pwrite ,
39 .Nm pwritev
40 .Nd write output
41 .Sh LIBRARY
42 .Lb libc
43 .Sh SYNOPSIS
44 .In unistd.h
45 .Ft ssize_t
46 .Fn write "int d" "const void *buf" "size_t nbytes"
47 .Ft ssize_t
48 .Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
49 .In sys/uio.h
50 .Ft ssize_t
51 .Fn writev "int d" "const struct iovec *iov" "int iovcnt"
52 .Ft ssize_t
53 .Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset"
54 .Sh DESCRIPTION
55 .Fn write
56 attempts to write
57 .Fa nbytes
58 of data to the object referenced by the descriptor
59 .Fa d
60 from the buffer pointed to by
61 .Fa buf .
62 .Fn writev
63 performs the same action, but gathers the output data
64 from the
65 .Fa iovcnt
66 buffers specified by the members of the
67 .Fa iov
68 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
69 .Fn pwrite
70 and
71 .Fn pwritev
72 perform the same functions, but write to the specified position in
73 the file without modifying the file pointer.
74 .Pp
75 For
76 .Fn writev
77 and
78 .Fn pwritev ,
79 the
80 .Fa iovec
81 structure is defined as:
82 .Pp
83 .Bd -literal -offset indent -compact
84 struct iovec {
85 void *iov_base;
86 size_t iov_len;
87 };
88 .Ed
89 .Pp
90 Each
91 .Fa iovec
92 entry specifies the base address and length of an area
93 in memory from which data should be written.
94 .Fn writev
95 and
96 .Fn pwritev
97 will always write a complete area before proceeding
98 to the next.
99 .Pp
100 On objects capable of seeking, the
101 .Fn write
102 starts at a position
103 given by the pointer associated with
104 .Fa d
105 (see
106 .Xr lseek 2 ) .
107 Upon return from
108 .Fn write ,
109 the pointer is incremented by the number of bytes which were written.
110 .Pp
111 Objects that are not capable of seeking always write from the current
112 position.
113 The value of the pointer associated with such an object
114 is undefined.
115 .Pp
116 If the real user is not the super-user, then
117 .Fn write
118 clears the set-user-id bit on a file.
119 This prevents penetration of system security
120 by a user who
121 .Dq captures
122 a writable set-user-id file
123 owned by the super-user.
124 .Pp
125 If
126 .Fn write
127 succeeds it will update the st_ctime and st_mtime fields of the file's
128 meta-data (see
129 .Xr stat 2 ) .
130 .Pp
131 When using non-blocking I/O on objects such as sockets that are subject
132 to flow control,
133 .Fn write
134 and
135 .Fn writev
136 may write fewer bytes than requested;
137 the return value must be noted,
138 and the remainder of the operation should be retried when possible.
139 .Sh RETURN VALUES
140 Upon successful completion the number of bytes which were written
141 is returned.
142 Otherwise a \-1 is returned and the global variable
143 .Va errno
144 is set to indicate the error.
145 .Sh ERRORS
146 .Fn write ,
147 .Fn writev ,
148 .Fn pwrite ,
149 and
150 .Fn pwritev
151 will fail and the file pointer will remain unchanged if:
152 .Bl -tag -width Er
153 .It Bq Er EBADF
154 .Fa d
155 is not a valid descriptor open for writing.
156 .It Bq Er EPIPE
157 An attempt is made to write to a pipe that is not open
158 for reading by any process.
159 .It Bq Er EPIPE
160 An attempt is made to write to a socket of type
161 .Dv SOCK_STREAM
162 that is not connected to a peer socket.
163 .It Bq Er EFBIG
164 An attempt was made to write a file that exceeds the process's
165 file size limit or the maximum file size.
166 .It Bq Er EFAULT
167 Part of
168 .Fa iov
169 or data to be written to the file
170 points outside the process's allocated address space.
171 .It Bq Er EINVAL
172 The pointer associated with
173 .Fa d
174 was negative.
175 .It Bq Er EINVAL
176 The total length of the I/O is more than can be expressed by the ssize_t
177 return value.
178 .It Bq Er ENOSPC
179 There is no free space remaining on the file system
180 containing the file.
181 .It Bq Er EDQUOT
182 The user's quota of disk blocks on the file system
183 containing the file has been exhausted.
184 .It Bq Er EIO
185 An I/O error occurred while reading from or writing to the file system.
186 .It Bq Er EINTR
187 A signal was received before any data could be written to a slow
188 device.
189 See
190 .Xr sigaction 2
191 for more information on the interaction between signals and system
192 calls.
193 .It Bq Er EAGAIN
194 The file was marked for non-blocking I/O,
195 and no data could be written immediately.
196 .El
197 .Pp
198 In addition,
199 .Fn writev
200 and
201 .Fn pwritev
202 may return one of the following errors:
203 .Bl -tag -width Er
204 .It Bq Er EINVAL
205 .Fa iovcnt
206 was less than or equal to 0, or greater than
207 .Dv {IOV_MAX} .
208 .It Bq Er EINVAL
209 One of the
210 .Fa iov_len
211 values in the
212 .Fa iov
213 array was negative.
214 .It Bq Er EINVAL
215 The sum of the
216 .Fa iov_len
217 values in the
218 .Fa iov
219 array overflowed a 32-bit integer.
220 .El
221 .Pp
222 The
223 .Fn pwrite
224 and
225 .Fn pwritev
226 calls may also return the following errors:
227 .Bl -tag -width Er
228 .It Bq Er EINVAL
229 The specified file offset is invalid.
230 .It Bq Er ESPIPE
231 The file descriptor is associated with a pipe, socket, or FIFO.
232 .El
233 .Sh SEE ALSO
234 .Xr fcntl 2 ,
235 .Xr lseek 2 ,
236 .Xr open 2 ,
237 .Xr pipe 2 ,
238 .Xr poll 2 ,
239 .Xr select 2 ,
240 .Xr sigaction 2
241 .Sh STANDARDS
242 The
243 .Fn write
244 function is expected to conform to
245 .St -p1003.1-88 .
246 The
247 .Fn writev
248 and
249 .Fn pwrite
250 functions conform to
251 .St -xpg4.2 .
252 .Sh HISTORY
253 The
254 .Fn pwritev
255 function call
256 appeared in
257 .Nx 1.4 .
258 The
259 .Fn pwrite
260 function call
261 appeared in
262 .At V.4 .
263 The
264 .Fn writev
265 function call
266 appeared in
267 .Bx 4.2 .
268 The
269 .Fn write
270 function call appeared in
271 .At v6 .
272 .Sh CAVEATS
273 Error checks should explicitly test for \-1.
274 Code such as
275 .Bd -literal
276 while ((nr = write(fd, buf, sizeof(buf))) \*[Gt] 0)
277 .Ed
278 .Pp
279 is not maximally portable, as some platforms allow for
280 .Va nbytes
281 to range between
282 .Dv SSIZE_MAX
283 and
284 .Dv SIZE_MAX
285 \- 2, in which case the return value of an error-free
286 .Fn write
287 may appear as a negative number distinct from \-1.
288 Proper loops should use
289 .Bd -literal
290 while ((nr = write(fd, buf, sizeof(buf))) != -1 \*[Am]\*[Am] nr != 0)
291 .Ed