[apple/xnu.git] / bsd / man / man2 / write.2

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