]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/write.2
xnu-2782.40.9.tar.gz
[apple/xnu.git] / bsd / man / man2 / write.2
CommitLineData
9bccf70c
A
1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)write.2 8.5 (Berkeley) 4/2/94
33.\" $FreeBSD: src/lib/libc/sys/write.2,v 1.12.2.7 2001/12/14 18:34:02 ru Exp $
34.\"
35.Dd April 2, 1994
36.Dt WRITE 2
37.Os
38.Sh NAME
2d21ac55 39.Nm pwrite ,
9bccf70c 40.Nm write ,
2d21ac55 41.Nm writev
9bccf70c
A
42.Nd write output
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
9bccf70c
A
46.In unistd.h
47.Ft ssize_t
2d21ac55
A
48.Fo pwrite
49.Fa "int fildes"
50.Fa "const void *buf"
51.Fa "size_t nbyte"
52.Fa "off_t offset"
53.Fc
9bccf70c 54.Ft ssize_t
2d21ac55
A
55.Fo write
56.Fa "int fildes"
57.Fa "const void *buf"
58.Fa "size_t nbyte"
59.Fc
60.In sys/uio.h
9bccf70c 61.Ft ssize_t
2d21ac55
A
62.Fo writev
63.Fa "int fildes"
64.Fa "const struct iovec *iov"
65.Fa "int iovcnt"
66.Fc
9bccf70c
A
67.Sh DESCRIPTION
68.Fn Write
69attempts to write
2d21ac55 70.Fa nbyte
9bccf70c 71of data to the object referenced by the descriptor
2d21ac55 72.Fa fildes
9bccf70c
A
73from the buffer pointed to by
74.Fa buf .
75.Fn Writev
76performs the same action, but gathers the output data
77from the
78.Fa iovcnt
79buffers specified by the members of the
80.Fa iov
81array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
82.Fn Pwrite
83performs the same function, but writes to the specified position in
84the file without modifying the file pointer.
85.Pp
86For
87.Fn writev ,
88the
89.Fa iovec
90structure is defined as:
91.Pp
92.Bd -literal -offset indent -compact
93struct iovec {
94 char *iov_base; /* Base address. */
95 size_t iov_len; /* Length. */
96};
97.Ed
98.Pp
99Each
100.Fa iovec
101entry specifies the base address and length of an area
102in memory from which data should be written.
103.Fn Writev
104will always write a complete area before proceeding
105to the next.
106.Pp
107On objects capable of seeking, the
108.Fn write
109starts at a position
110given by the pointer associated with
2d21ac55 111.Fa fildes ,
9bccf70c
A
112see
113.Xr lseek 2 .
114Upon return from
115.Fn write ,
116the pointer is incremented by the number of bytes which were written.
117.Pp
118Objects that are not capable of seeking always write from the current
119position. The value of the pointer associated with such an object
120is undefined.
121.Pp
122If the real user is not the super-user, then
123.Fn write
124clears the set-user-id bit on a file.
125This prevents penetration of system security
126by a user who
127.Dq captures
128a writable set-user-id file
129owned by the super-user.
130.Pp
2d21ac55
A
131When using non-blocking I/O on objects, such as sockets,
132that are subject to flow control,
9bccf70c
A
133.Fn write
134and
135.Fn writev
136may write fewer bytes than requested;
137the return value must be noted,
138and the remainder of the operation should be retried when possible.
139.Sh RETURN VALUES
2d21ac55
A
140Upon successful completion the number of bytes
141which were written is returned.
142Otherwise, a -1 is returned and the global variable
9bccf70c
A
143.Va errno
144is set to indicate the error.
145.Sh ERRORS
2d21ac55
A
146The
147.Fn write ,
9bccf70c
A
148.Fn writev ,
149and
150.Fn pwrite
2d21ac55 151system calls will fail and the file pointer will remain unchanged if:
9bccf70c 152.Bl -tag -width Er
2d21ac55
A
153.\" ===========
154.It Bq Er EDQUOT
155The user's quota of disk blocks on the file system
156containing the file is exhausted.
157.\" ===========
9bccf70c
A
158.It Bq Er EFAULT
159Part of
160.Fa iov
161or data to be written to the file
162points outside the process's allocated address space.
2d21ac55 163.\" ===========
9bccf70c
A
164.It Bq Er EINVAL
165The pointer associated with
2d21ac55
A
166.Fa fildes
167is negative.
168.El
169.Pp
170The
171.Fn write
172and
173.Fn pwrite
174system calls will fail and the file pointer will remain unchanged if:
175.Bl -tag -width Er
176.\" ===========
9bccf70c 177.It Bq Er EAGAIN
2d21ac55 178The file is marked for non-blocking I/O,
9bccf70c 179and no data could be written immediately.
2d21ac55
A
180.\" ===========
181.It Bq Er EBADF
182.Fa fildes
183is not a valid file descriptor open for writing.
184.\" ===========
185.It Bq Er ECONNRESET
186A write is attempted on a socket that is not connected.
187.\" ===========
188.It Bq Er EFBIG
189An attempt is made to write a file that exceeds the process's
190file size limit or the maximum file size.
191.\" ===========
192.It Bq Er EFBIG
193The file is a regular file,
194.Fa nbyte
195is greater than 0,
196and the starting position is greater than or equal
197to the offset maximum established in the open file description
198associated with
199.Fa fildes .
200.\" ===========
201.It Bq Er EINTR
202A signal interrupts the write before it could be completed.
203.\" ===========
204.It Bq Er EIO
205An I/O error occurs while reading from or writing to the file system.
206.\" ===========
207.It Bq Er ENETDOWN
208A write is attempted on a socket
209and the local network interface used to reach the destination is down.
210.\" ===========
211.It Bq Er ENETUNREACH
212A write is attempted on a socket and no route to the network is present.
213.\" ===========
214.It Bq Er ENOSPC
215There is no free space remaining on the file system containing the file.
216.\" ===========
217.It Bq Er ENXIO
218A request is made of a nonexistent device,
219or the request is outside the capabilities of the device.
220.\" ===========
221.It Bq Er EPIPE
222An attempt is made to write to a pipe that is not open
223for reading by any process.
224.\" ===========
225.It Bq Er EPIPE
226An attempt is made to write to a socket of type
227.Dv SOCK_STREAM
228that is not connected to a peer socket.
229.El
230.Pp
231The
232.Fn write
233and
234.Fn writev
235calls may also return the following errors:
236.Bl -tag -width Er
237.\" ===========
238.It Bq Er EAGAIN
239See EWOULDBLOCK, below.
240.\" ===========
241.It Bq Er EWOULDBLOCK
242The file descriptor is for a socket, is marked O_NONBLOCK,
243and write would block.
244The exact error code depends on the protocol,
245but EWOULDBLOCK is more common.
9bccf70c
A
246.El
247.Pp
248In addition,
249.Fn writev
250may return one of the following errors:
251.Bl -tag -width Er
2d21ac55 252.\" ===========
9bccf70c
A
253.It Bq Er EDESTADDRREQ
254The destination is no longer available when writing to a
255.Ux
256domain datagram socket on which
257.Xr connect 2
258had been used to set a destination address.
2d21ac55 259.\" ===========
9bccf70c
A
260.It Bq Er EINVAL
261.Fa Iovcnt
2d21ac55 262is less than or equal to 0, or greater than
9bccf70c 263.Dv UIO_MAXIOV .
2d21ac55 264.\" ===========
9bccf70c
A
265.It Bq Er EINVAL
266One of the
267.Fa iov_len
268values in the
269.Fa iov
2d21ac55
A
270array is negative.
271.\" ===========
9bccf70c
A
272.It Bq Er EINVAL
273The sum of the
274.Fa iov_len
275values in the
276.Fa iov
2d21ac55
A
277array overflows a 32-bit integer.
278.\" ===========
9bccf70c
A
279.It Bq Er ENOBUFS
280The mbuf pool has been completely exhausted when writing to a socket.
281.El
282.Pp
283The
284.Fn pwrite
285call may also return the following errors:
286.Bl -tag -width Er
2d21ac55 287.\" ===========
9bccf70c
A
288.It Bq Er EINVAL
289The specified file offset is invalid.
2d21ac55 290.\" ===========
9bccf70c
A
291.It Bq Er ESPIPE
292The file descriptor is associated with a pipe, socket, or FIFO.
293.El
2d21ac55
A
294.Sh LEGACY SYNOPSIS
295.Fd #include <sys/types.h>
296.Fd #include <sys/uio.h>
297.Fd #include <unistd.h>
298.Pp
299These include files are needed for all three functions.
9bccf70c
A
300.Sh SEE ALSO
301.Xr fcntl 2 ,
302.Xr lseek 2 ,
303.Xr open 2 ,
304.Xr pipe 2 ,
2d21ac55
A
305.Xr select 2 ,
306.Xr compat 5
9bccf70c
A
307.Sh STANDARDS
308The
309.Fn write
310function call is expected to conform to
311.St -p1003.1-90 .
312The
313.Fn writev
314and
315.Fn pwrite
316functions are expected to conform to
317.St -xpg4.2 .
318.Sh HISTORY
319The
320.Fn pwrite
321function call
322appeared in
323.At V.4 .
324The
325.Fn writev
326function call
327appeared in
328.Bx 4.2 .
329A
330.Fn write
331function call appeared in
332.At v6 .