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
| 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: head/lib/libc/sys/write.2 50476 1999-08-28 00:22:10Z peter $
| 33.\" $FreeBSD: head/lib/libc/sys/write.2 57686 2000-03-02 09:14:21Z sheldonh $
|
34.\"
35.Dd April 2, 1994
36.Dt WRITE 2
37.Os BSD 4
38.Sh NAME
39.Nm write ,
40.Nm writev ,
41.Nm pwrite
42.Nd write output
43.Sh SYNOPSIS
44.Fd #include <sys/types.h>
45.Fd #include <sys/uio.h>
46.Fd #include <unistd.h>
47.Ft ssize_t
48.Fn write "int d" "const void *buf" "size_t nbytes"
49.Ft ssize_t
50.Fn writev "int d" "const struct iovec *iov" "int iovcnt"
51.Ft ssize_t
52.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
53.Sh DESCRIPTION
54.Fn Write
55attempts to write
56.Fa nbytes
57of data to the object referenced by the descriptor
58.Fa d
59from the buffer pointed to by
60.Fa buf .
61.Fn Writev
62performs the same action, but gathers the output data
63from the
64.Fa iovcnt
65buffers specified by the members of the
66.Fa iov
67array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
68.Fn Pwrite
69performs the same function, but writes to the specified position in
70the file without modifying the file pointer.
71.Pp
72For
73.Fn writev ,
74the
75.Fa iovec
76structure is defined as:
77.Pp
78.Bd -literal -offset indent -compact
79struct iovec {
80 char *iov_base; /* Base address. */
81 size_t iov_len; /* Length. */
82};
83.Ed
84.Pp
85Each
86.Fa iovec
87entry specifies the base address and length of an area
88in memory from which data should be written.
89.Fn Writev
90will always write a complete area before proceeding
91to the next.
92.Pp
93On objects capable of seeking, the
94.Fn write
95starts at a position
96given by the pointer associated with
97.Fa d ,
98see
99.Xr lseek 2 .
100Upon return from
101.Fn write ,
102the pointer is incremented by the number of bytes which were written.
103.Pp
104Objects that are not capable of seeking always write from the current
105position. The value of the pointer associated with such an object
106is undefined.
107.Pp
108If the real user is not the super-user, then
109.Fn write
110clears the set-user-id bit on a file.
111This prevents penetration of system security
112by a user who
113.Dq captures
114a writable set-user-id file
115owned by the super-user.
116.Pp
117When using non-blocking I/O on objects such as sockets that are subject
118to flow control,
119.Fn write
120and
121.Fn writev
122may write fewer bytes than requested;
123the return value must be noted,
124and the remainder of the operation should be retried when possible.
125.Sh IMPLEMENTATION NOTES
126.Pp
127In the non-threaded library
128.Fn write
129is implemented as the
130.Va write
131syscall.
132.Pp
133In the threaded library, the
134.Va write
135syscall is assembled to
136.Fn _thread_sys_write
137and
138.Fn write
139is implemented as a function which locks
140.Va d
141for read and write, then calls
142.Fn _thread_sys_write .
143If the call to
144.Fn _thread_sys_write
| 34.\"
35.Dd April 2, 1994
36.Dt WRITE 2
37.Os BSD 4
38.Sh NAME
39.Nm write ,
40.Nm writev ,
41.Nm pwrite
42.Nd write output
43.Sh SYNOPSIS
44.Fd #include <sys/types.h>
45.Fd #include <sys/uio.h>
46.Fd #include <unistd.h>
47.Ft ssize_t
48.Fn write "int d" "const void *buf" "size_t nbytes"
49.Ft ssize_t
50.Fn writev "int d" "const struct iovec *iov" "int iovcnt"
51.Ft ssize_t
52.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
53.Sh DESCRIPTION
54.Fn Write
55attempts to write
56.Fa nbytes
57of data to the object referenced by the descriptor
58.Fa d
59from the buffer pointed to by
60.Fa buf .
61.Fn Writev
62performs the same action, but gathers the output data
63from the
64.Fa iovcnt
65buffers specified by the members of the
66.Fa iov
67array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
68.Fn Pwrite
69performs the same function, but writes to the specified position in
70the file without modifying the file pointer.
71.Pp
72For
73.Fn writev ,
74the
75.Fa iovec
76structure is defined as:
77.Pp
78.Bd -literal -offset indent -compact
79struct iovec {
80 char *iov_base; /* Base address. */
81 size_t iov_len; /* Length. */
82};
83.Ed
84.Pp
85Each
86.Fa iovec
87entry specifies the base address and length of an area
88in memory from which data should be written.
89.Fn Writev
90will always write a complete area before proceeding
91to the next.
92.Pp
93On objects capable of seeking, the
94.Fn write
95starts at a position
96given by the pointer associated with
97.Fa d ,
98see
99.Xr lseek 2 .
100Upon return from
101.Fn write ,
102the pointer is incremented by the number of bytes which were written.
103.Pp
104Objects that are not capable of seeking always write from the current
105position. The value of the pointer associated with such an object
106is undefined.
107.Pp
108If the real user is not the super-user, then
109.Fn write
110clears the set-user-id bit on a file.
111This prevents penetration of system security
112by a user who
113.Dq captures
114a writable set-user-id file
115owned by the super-user.
116.Pp
117When using non-blocking I/O on objects such as sockets that are subject
118to flow control,
119.Fn write
120and
121.Fn writev
122may write fewer bytes than requested;
123the return value must be noted,
124and the remainder of the operation should be retried when possible.
125.Sh IMPLEMENTATION NOTES
126.Pp
127In the non-threaded library
128.Fn write
129is implemented as the
130.Va write
131syscall.
132.Pp
133In the threaded library, the
134.Va write
135syscall is assembled to
136.Fn _thread_sys_write
137and
138.Fn write
139is implemented as a function which locks
140.Va d
141for read and write, then calls
142.Fn _thread_sys_write .
143If the call to
144.Fn _thread_sys_write
|
145would block, a context switch is performed. Before returning,
| 145would block, a context switch is performed.
146Before returning,
|
146.Fn write
147unlocks
148.Va d .
149.Pp
150In the non-threaded library
151.Fn writev
152is implemented as the
153.Va writev
154syscall.
155.Pp
156In the threaded library, the
157.Va writev
158syscall is assembled to
159.Fn _thread_sys_writev
160and
161.Fn writev
162is implemented as a function which locks
163.Va d
164for read and write, then calls
165.Fn _thread_sys_writev .
166If the call to
167.Fn _thread_sys_writev
| 147.Fn write
148unlocks
149.Va d .
150.Pp
151In the non-threaded library
152.Fn writev
153is implemented as the
154.Va writev
155syscall.
156.Pp
157In the threaded library, the
158.Va writev
159syscall is assembled to
160.Fn _thread_sys_writev
161and
162.Fn writev
163is implemented as a function which locks
164.Va d
165for read and write, then calls
166.Fn _thread_sys_writev .
167If the call to
168.Fn _thread_sys_writev
|
168would block, a context switch is performed. Before returning,
| 169would block, a context switch is performed.
170Before returning,
|
169.Fn writev
170unlocks
171.Va d .
172.Sh RETURN VALUES
173Upon successful completion the number of bytes which were written
174is returned. Otherwise a -1 is returned and the global variable
175.Va errno
176is set to indicate the error.
177.Sh ERRORS
178.Fn Write ,
179.Fn writev ,
180and
181.Fn pwrite
182will fail and the file pointer will remain unchanged if:
183.Bl -tag -width Er
184.It Bq Er EBADF
185.Fa D
186is not a valid descriptor open for writing.
187.It Bq Er EPIPE
188An attempt is made to write to a pipe that is not open
189for reading by any process.
190.It Bq Er EPIPE
191An attempt is made to write to a socket of type
192.Dv SOCK_STREAM
193that is not connected to a peer socket.
194.It Bq Er EFBIG
195An attempt was made to write a file that exceeds the process's
196file size limit or the maximum file size.
197.It Bq Er EFAULT
198Part of
199.Fa iov
200or data to be written to the file
201points outside the process's allocated address space.
202.It Bq Er EINVAL
203The pointer associated with
204.Fa d
205was negative.
206.It Bq Er ENOSPC
207There is no free space remaining on the file system
208containing the file.
209.It Bq Er EDQUOT
210The user's quota of disk blocks on the file system
211containing the file has been exhausted.
212.It Bq Er EIO
213An I/O error occurred while reading from or writing to the file system.
214.It Bq Er EAGAIN
215The file was marked for non-blocking I/O,
216and no data could be written immediately.
217.El
218.Pp
219In addition,
220.Fn writev
221may return one of the following errors:
222.Bl -tag -width Er
223.It Bq Er EDESTADDRREQ
224The destination is no longer available when writing to a
225.Ux
226domain datagram socket on which
227.Xr connect 2
228had been used to set a destination address.
229.It Bq Er EINVAL
230.Fa Iovcnt
231was less than or equal to 0, or greater than
232.Dv UIO_MAXIOV .
233.It Bq Er EINVAL
234One of the
235.Fa iov_len
236values in the
237.Fa iov
238array was negative.
239.It Bq Er EINVAL
240The sum of the
241.Fa iov_len
242values in the
243.Fa iov
244array overflowed a 32-bit integer.
245.It Bq Er ENOBUFS
246The mbuf pool has been completely exhausted when writing to a socket.
247.El
248.Pp
249The
250.Fn pwrite
251call may also return the following errors:
252.Bl -tag -width Er
253.It Bq Er EINVAL
254The specified file offset is invalid.
255.It Bq Er ESPIPE
256The file descriptor is associated with a pipe, socket, or FIFO.
257.El
258.Sh SEE ALSO
259.Xr fcntl 2 ,
260.Xr lseek 2 ,
261.Xr open 2 ,
262.Xr pipe 2 ,
263.Xr select 2
264.Sh STANDARDS
265The
266.Fn write
267function call is expected to conform to
268.St -p1003.1-90 .
269The
270.Fn writev
271and
272.Fn pwrite
273functions are expected to conform to
274.St -xpg4.2 .
275.Sh HISTORY
276The
277.Fn pwrite
278function call
279appeared in
280.At V.4 .
281The
282.Fn writev
283function call
284appeared in
285.Bx 4.2 .
286A
287.Fn write
288function call appeared in
289.At v6 .
| 171.Fn writev
172unlocks
173.Va d .
174.Sh RETURN VALUES
175Upon successful completion the number of bytes which were written
176is returned. Otherwise a -1 is returned and the global variable
177.Va errno
178is set to indicate the error.
179.Sh ERRORS
180.Fn Write ,
181.Fn writev ,
182and
183.Fn pwrite
184will fail and the file pointer will remain unchanged if:
185.Bl -tag -width Er
186.It Bq Er EBADF
187.Fa D
188is not a valid descriptor open for writing.
189.It Bq Er EPIPE
190An attempt is made to write to a pipe that is not open
191for reading by any process.
192.It Bq Er EPIPE
193An attempt is made to write to a socket of type
194.Dv SOCK_STREAM
195that is not connected to a peer socket.
196.It Bq Er EFBIG
197An attempt was made to write a file that exceeds the process's
198file size limit or the maximum file size.
199.It Bq Er EFAULT
200Part of
201.Fa iov
202or data to be written to the file
203points outside the process's allocated address space.
204.It Bq Er EINVAL
205The pointer associated with
206.Fa d
207was negative.
208.It Bq Er ENOSPC
209There is no free space remaining on the file system
210containing the file.
211.It Bq Er EDQUOT
212The user's quota of disk blocks on the file system
213containing the file has been exhausted.
214.It Bq Er EIO
215An I/O error occurred while reading from or writing to the file system.
216.It Bq Er EAGAIN
217The file was marked for non-blocking I/O,
218and no data could be written immediately.
219.El
220.Pp
221In addition,
222.Fn writev
223may return one of the following errors:
224.Bl -tag -width Er
225.It Bq Er EDESTADDRREQ
226The destination is no longer available when writing to a
227.Ux
228domain datagram socket on which
229.Xr connect 2
230had been used to set a destination address.
231.It Bq Er EINVAL
232.Fa Iovcnt
233was less than or equal to 0, or greater than
234.Dv UIO_MAXIOV .
235.It Bq Er EINVAL
236One of the
237.Fa iov_len
238values in the
239.Fa iov
240array was negative.
241.It Bq Er EINVAL
242The sum of the
243.Fa iov_len
244values in the
245.Fa iov
246array overflowed a 32-bit integer.
247.It Bq Er ENOBUFS
248The mbuf pool has been completely exhausted when writing to a socket.
249.El
250.Pp
251The
252.Fn pwrite
253call may also return the following errors:
254.Bl -tag -width Er
255.It Bq Er EINVAL
256The specified file offset is invalid.
257.It Bq Er ESPIPE
258The file descriptor is associated with a pipe, socket, or FIFO.
259.El
260.Sh SEE ALSO
261.Xr fcntl 2 ,
262.Xr lseek 2 ,
263.Xr open 2 ,
264.Xr pipe 2 ,
265.Xr select 2
266.Sh STANDARDS
267The
268.Fn write
269function call is expected to conform to
270.St -p1003.1-90 .
271The
272.Fn writev
273and
274.Fn pwrite
275functions are expected to conform to
276.St -xpg4.2 .
277.Sh HISTORY
278The
279.Fn pwrite
280function call
281appeared in
282.At V.4 .
283The
284.Fn writev
285function call
286appeared in
287.Bx 4.2 .
288A
289.Fn write
290function call appeared in
291.At v6 .
|