mirror of https://github.com/mkerrisk/man-pages
297 lines
8.8 KiB
Groff
297 lines
8.8 KiB
Groff
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
|
|
.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
|
|
.\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt
|
|
.\" <michael@cantor.informatik.rwth-aachen.de>
|
|
.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" 2001-12-13 added remark by Zack Weinberg
|
|
.\" 2007-06-18 mtk:
|
|
.\" Added details about seekable files and file offset.
|
|
.\" Noted that write() may write less than 'count' bytes, and
|
|
.\" gave some examples of why this might occur.
|
|
.\" Noted what happens if write() is interrupted by a signal.
|
|
.\"
|
|
.TH WRITE 2 2017-03-13 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
write \- write to a file descriptor
|
|
.SH SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.PP
|
|
.BI "ssize_t write(int " fd ", const void *" buf ", size_t " count );
|
|
.SH DESCRIPTION
|
|
.BR write ()
|
|
writes up to
|
|
.I count
|
|
bytes from the buffer pointed
|
|
.I buf
|
|
to the file referred to by the file descriptor
|
|
.IR fd .
|
|
.PP
|
|
The number of bytes written may be less than
|
|
.I count
|
|
if, for example,
|
|
there is insufficient space on the underlying physical medium, or the
|
|
.B RLIMIT_FSIZE
|
|
resource limit is encountered (see
|
|
.BR setrlimit (2)),
|
|
or the call was interrupted by a signal
|
|
handler after having written less than
|
|
.I count
|
|
bytes.
|
|
(See also
|
|
.BR pipe (7).)
|
|
.PP
|
|
For a seekable file (i.e., one to which
|
|
.BR lseek (2)
|
|
may be applied, for example, a regular file)
|
|
writing takes place at the file offset,
|
|
and the file offset is incremented by
|
|
the number of bytes actually written.
|
|
If the file was
|
|
.BR open (2)ed
|
|
with
|
|
.BR O_APPEND ,
|
|
the file offset is first set to the end of the file before writing.
|
|
The adjustment of the file offset and the write operation
|
|
are performed as an atomic step.
|
|
.PP
|
|
POSIX requires that a
|
|
.BR read (2)
|
|
that can be proved to occur after a
|
|
.BR write ()
|
|
has returned will return the new data.
|
|
Note that not all filesystems are POSIX conforming.
|
|
.PP
|
|
According to POSIX.1, if
|
|
.I count
|
|
is greater than
|
|
.BR SSIZE_MAX ,
|
|
the result is implementation-defined;
|
|
see NOTES for the upper limit on Linux.
|
|
.SH RETURN VALUE
|
|
On success, the number of bytes written is returned (zero indicates
|
|
nothing was written).
|
|
It is not an error if this number is smaller than the number of bytes
|
|
requested; this may happen for example because the disk device was filled.
|
|
See also NOTES.
|
|
.PP
|
|
On error, \-1 is returned, and \fIerrno\fP is set
|
|
appropriately.
|
|
.PP
|
|
If \fIcount\fP is zero and
|
|
.I fd
|
|
refers to a regular file, then
|
|
.BR write ()
|
|
may return a failure status if one of the errors below is detected.
|
|
If no errors are detected, or error detection is not performed,
|
|
0 will be returned without causing any other effect.
|
|
If
|
|
\fIcount\fP is zero and
|
|
.I fd
|
|
refers to a file other than a regular file,
|
|
the results are not specified.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EAGAIN
|
|
The file descriptor
|
|
.I fd
|
|
refers to a file other than a socket and has been marked nonblocking
|
|
.RB ( O_NONBLOCK ),
|
|
and the write would block.
|
|
See
|
|
.BR open (2)
|
|
for further details on the
|
|
.BR O_NONBLOCK
|
|
flag.
|
|
.TP
|
|
.BR EAGAIN " or " EWOULDBLOCK
|
|
.\" Actually EAGAIN on Linux
|
|
The file descriptor
|
|
.I fd
|
|
refers to a socket and has been marked nonblocking
|
|
.RB ( O_NONBLOCK ),
|
|
and the write would block.
|
|
POSIX.1-2001 allows either error to be returned for this case,
|
|
and does not require these constants to have the same value,
|
|
so a portable application should check for both possibilities.
|
|
.TP
|
|
.B EBADF
|
|
.I fd
|
|
is not a valid file descriptor or is not open for writing.
|
|
.TP
|
|
.B EDESTADDRREQ
|
|
.I fd
|
|
refers to a datagram socket for which a peer address has not been set using
|
|
.BR connect (2).
|
|
.TP
|
|
.B EDQUOT
|
|
The user's quota of disk blocks on the filesystem containing the file
|
|
referred to by
|
|
.I fd
|
|
has been exhausted.
|
|
.TP
|
|
.B EFAULT
|
|
.I buf
|
|
is outside your accessible address space.
|
|
.TP
|
|
.B EFBIG
|
|
An attempt was made to write a file that exceeds the implementation-defined
|
|
maximum file size or the process's file size limit,
|
|
or to write at a position past the maximum allowed offset.
|
|
.TP
|
|
.B EINTR
|
|
The call was interrupted by a signal before any data was written; see
|
|
.BR signal (7).
|
|
.TP
|
|
.B EINVAL
|
|
.I fd
|
|
is attached to an object which is unsuitable for writing;
|
|
or the file was opened with the
|
|
.B O_DIRECT
|
|
flag, and either the address specified in
|
|
.IR buf ,
|
|
the value specified in
|
|
.IR count ,
|
|
or the file offset is not suitably aligned.
|
|
.TP
|
|
.B EIO
|
|
A low-level I/O error occurred while modifying the inode.
|
|
.TP
|
|
.B ENOSPC
|
|
The device containing the file referred to by
|
|
.I fd
|
|
has no room for the data.
|
|
.TP
|
|
.B EPERM
|
|
The operation was prevented by a file seal; see
|
|
.BR fcntl (2).
|
|
.TP
|
|
.B EPIPE
|
|
.I fd
|
|
is connected to a pipe or socket whose reading end is closed.
|
|
When this happens the writing process will also receive a
|
|
.B SIGPIPE
|
|
signal.
|
|
(Thus, the write return value is seen only if the program
|
|
catches, blocks or ignores this signal.)
|
|
.PP
|
|
Other errors may occur, depending on the object connected to
|
|
.IR fd .
|
|
.SH CONFORMING TO
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
|
.\" SVr4 documents additional error
|
|
.\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE.
|
|
.PP
|
|
Under SVr4 a write may be interrupted and return
|
|
.B EINTR
|
|
at any point,
|
|
not just before any data is written.
|
|
.SH NOTES
|
|
The types
|
|
.I size_t
|
|
and
|
|
.I ssize_t
|
|
are, respectively,
|
|
unsigned and signed integer data types specified by POSIX.1.
|
|
.PP
|
|
A successful return from
|
|
.BR write ()
|
|
does not make any guarantee that data has been committed to disk.
|
|
In fact, on some buggy implementations, it does not even guarantee
|
|
that space has successfully been reserved for the data.
|
|
The only way to be sure is to call
|
|
.BR fsync (2)
|
|
after you are done writing all your data.
|
|
.PP
|
|
If a
|
|
.BR write ()
|
|
is interrupted by a signal handler before any bytes are written,
|
|
then the call fails with the error
|
|
.BR EINTR ;
|
|
if it is interrupted after at least one byte has been written,
|
|
the call succeeds, and returns the number of bytes written.
|
|
.PP
|
|
On Linux,
|
|
.BR write ()
|
|
(and similar system calls) will transfer at most
|
|
0x7ffff000 (2,147,479,552) bytes,
|
|
returning the number of bytes actually transferred.
|
|
.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
|
|
(This is true on both 32-bit and 64-bit systems.)
|
|
.SH BUGS
|
|
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
|
|
("Thread Interactions with Regular File Operations"):
|
|
.PP
|
|
.RS 4
|
|
All of the following functions shall be atomic with respect to
|
|
each other in the effects specified in POSIX.1-2008 when they
|
|
operate on regular files or symbolic links: ...
|
|
.RE
|
|
.PP
|
|
Among the APIs subsequently listed are
|
|
.BR write ()
|
|
and
|
|
.BR writev (2).
|
|
And among the effects that should be atomic across threads (and processes)
|
|
are updates of the file offset.
|
|
However, on Linux before version 3.14,
|
|
this was not the case: if two processes that share
|
|
an open file description (see
|
|
.BR open (2))
|
|
perform a
|
|
.BR write ()
|
|
(or
|
|
.BR writev (2))
|
|
at the same time, then the I/O operations were not atomic
|
|
with respect updating the file offset,
|
|
with the result that the blocks of data output by the two processes
|
|
might (incorrectly) overlap.
|
|
This problem was fixed in Linux 3.14.
|
|
.\" http://thread.gmane.org/gmane.linux.kernel/1649458
|
|
.\" From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
|
|
.\" Subject: Update of file offset on write() etc. is non-atomic with I/O
|
|
.\" Date: 2014-02-17 15:41:37 GMT
|
|
.\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
|
|
.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
|
|
.\" Author: Linus Torvalds <torvalds@linux-foundation.org>
|
|
.\" Date: Mon Mar 3 09:36:58 2014 -0800
|
|
.\"
|
|
.\" vfs: atomic f_pos accesses as per POSIX
|
|
.SH SEE ALSO
|
|
.BR close (2),
|
|
.BR fcntl (2),
|
|
.BR fsync (2),
|
|
.BR ioctl (2),
|
|
.BR lseek (2),
|
|
.BR open (2),
|
|
.BR pwrite (2),
|
|
.BR read (2),
|
|
.BR select (2),
|
|
.BR writev (2),
|
|
.BR fwrite (3)
|