xnu-6153.121.1.tar.gz
[apple/xnu.git] / bsd / man / man2 / write.2
0 / 334 (  0%)
CommitLineData
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 March 18, 2015
36.Dt WRITE 2
37.Os
38.Sh NAME
39.Nm pwrite ,
40.Nm write ,
41.Nm writev
42.Nd write output
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In unistd.h
47.Ft ssize_t
48.Fo pwrite
49.Fa "int fildes"
50.Fa "const void *buf"
51.Fa "size_t nbyte"
52.Fa "off_t offset"
53.Fc
54.Ft ssize_t
55.Fo write
56.Fa "int fildes"
57.Fa "const void *buf"
58.Fa "size_t nbyte"
59.Fc
60.In sys/uio.h
61.Ft ssize_t
62.Fo writev
63.Fa "int fildes"
64.Fa "const struct iovec *iov"
65.Fa "int iovcnt"
66.Fc
67.Sh DESCRIPTION
68.Fn write
69attempts to write
70.Fa nbyte
71of data to the object referenced by the descriptor
72.Fa fildes
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
111.Fa fildes ,
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
131When using non-blocking I/O on objects, such as sockets,
132that are subject to flow control,
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
140Upon successful completion the number of bytes
141which were written is returned.
142Otherwise, a -1 is returned and the global variable
143.Va errno
144is set to indicate the error.
145.Sh ERRORS
146The
147.Fn write ,
148.Fn writev ,
149and
150.Fn pwrite
151system calls will fail and the file pointer will remain unchanged if:
152.Bl -tag -width Er
153.\" ===========
154.It Bq Er EDQUOT
155The user's quota of disk blocks on the file system
156containing the file is exhausted.
157.\" ===========
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.
163.\" ===========
164.It Bq Er EINVAL
165The pointer associated with
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.\" ===========
177.It Bq Er EAGAIN
178The file is marked for non-blocking I/O,
179and no data could be written immediately.
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.
246.El
247.Pp
248In addition,
249.Fn writev
250may return one of the following errors:
251.Bl -tag -width Er
252.\" ===========
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
258or
259.Xr connectx 2
260had been used to set a destination address.
261.\" ===========
262.It Bq Er EINVAL
263.Fa Iovcnt
264is less than or equal to 0, or greater than
265.Dv UIO_MAXIOV .
266.\" ===========
267.It Bq Er EINVAL
268One of the
269.Fa iov_len
270values in the
271.Fa iov
272array is negative.
273.\" ===========
274.It Bq Er EINVAL
275The sum of the
276.Fa iov_len
277values in the
278.Fa iov
279array overflows a 32-bit integer.
280.\" ===========
281.It Bq Er ENOBUFS
282The mbuf pool has been completely exhausted when writing to a socket.
283.El
284.Pp
285The
286.Fn pwrite
287call may also return the following errors:
288.Bl -tag -width Er
289.\" ===========
290.It Bq Er EINVAL
291The specified file offset is invalid.
292.\" ===========
293.It Bq Er ESPIPE
294The file descriptor is associated with a pipe, socket, or FIFO.
295.El
296.Sh LEGACY SYNOPSIS
297.Fd #include <sys/types.h>
298.Fd #include <sys/uio.h>
299.Fd #include <unistd.h>
300.Pp
301These include files are needed for all three functions.
302.Sh SEE ALSO
303.Xr fcntl 2 ,
304.Xr lseek 2 ,
305.Xr open 2 ,
306.Xr pipe 2 ,
307.Xr select 2 ,
308.Xr compat 5
309.Sh STANDARDS
310The
311.Fn write
312function call is expected to conform to
313.St -p1003.1-90 .
314The
315.Fn writev
316and
317.Fn pwrite
318functions are expected to conform to
319.St -xpg4.2 .
320.Sh HISTORY
321The
322.Fn pwrite
323function call
324appeared in
325.At V.4 .
326The
327.Fn writev
328function call
329appeared in
330.Bx 4.2 .
331A
332.Fn write
333function call appeared in
334.At v6 .