486 lines
11 KiB
HTML
486 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of WRITE</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>WRITE</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-10-10<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
write - write to a file descriptor
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>#include <<A HREF="file:///usr/include/unistd.h">unistd.h</A>></B>
|
|
|
|
<P>
|
|
|
|
<B>ssize_t write(int </B><I>fd</I><B>, const void *</B><I>buf</I><B>, size_t </B><I>count</I><B>);</B>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>write</B>()
|
|
|
|
writes up to
|
|
<I>count</I>
|
|
|
|
bytes from the buffer starting at
|
|
<I>buf</I>
|
|
|
|
to the file referred to by the file descriptor
|
|
<I>fd</I>.
|
|
|
|
<P>
|
|
|
|
The number of bytes written may be less than
|
|
<I>count</I>
|
|
|
|
if, for example,
|
|
there is insufficient space on the underlying physical medium, or the
|
|
<B>RLIMIT_FSIZE</B>
|
|
|
|
resource limit is encountered (see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+setrlimit">setrlimit</A></B>(2)),
|
|
|
|
or the call was interrupted by a signal
|
|
handler after having written less than
|
|
<I>count</I>
|
|
|
|
bytes.
|
|
(See also
|
|
<B><A HREF="/cgi-bin/man/man2html?7+pipe">pipe</A></B>(7).)
|
|
|
|
<P>
|
|
|
|
For a seekable file (i.e., one to which
|
|
<B><A HREF="/cgi-bin/man/man2html?2+lseek">lseek</A></B>(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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2)ed
|
|
|
|
with
|
|
<B>O_APPEND</B>,
|
|
|
|
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.
|
|
<P>
|
|
|
|
POSIX requires that a
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
that can be proved to occur after a
|
|
<B>write</B>()
|
|
|
|
has returned will return the new data.
|
|
Note that not all filesystems are POSIX conforming.
|
|
<P>
|
|
|
|
According to POSIX.1, if
|
|
<I>count</I>
|
|
|
|
is greater than
|
|
<B>SSIZE_MAX</B>,
|
|
|
|
the result is implementation-defined;
|
|
see NOTES for the upper limit on Linux.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success, the number of bytes written is returned.
|
|
On error, -1 is returned, and <I>errno</I> is set
|
|
to indicate the cause of the error.
|
|
<P>
|
|
|
|
Note that a successful
|
|
<B>write</B>()
|
|
|
|
may transfer fewer than
|
|
<I>count</I>
|
|
|
|
bytes.
|
|
Such partial writes can occur for various reasons;
|
|
for example, because there was insufficient space on the disk device
|
|
to write all of the requested bytes, or because a blocked
|
|
<B>write</B>()
|
|
|
|
to a socket, pipe, or similar was interrupted by a signal handler
|
|
after it had transferred some, but before it had transferred all
|
|
of the requested bytes.
|
|
In the event of a partial write, the caller can make another
|
|
<B>write</B>()
|
|
|
|
call to transfer the remaining bytes.
|
|
The subsequent call will either transfer further bytes or
|
|
may result in an error (e.g., if the disk is now full).
|
|
<P>
|
|
|
|
If <I>count</I> is zero and
|
|
<I>fd</I>
|
|
|
|
refers to a regular file, then
|
|
<B>write</B>()
|
|
|
|
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
|
|
<I>count</I> is zero and
|
|
<I>fd</I>
|
|
|
|
refers to a file other than a regular file,
|
|
the results are not specified.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>EAGAIN</B>
|
|
|
|
<DD>
|
|
The file descriptor
|
|
<I>fd</I>
|
|
|
|
refers to a file other than a socket and has been marked nonblocking
|
|
(<B>O_NONBLOCK</B>),
|
|
|
|
and the write would block.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2)
|
|
|
|
for further details on the
|
|
<B>O_NONBLOCK</B>
|
|
|
|
flag.
|
|
<DT id="2"><B>EAGAIN</B> or <B>EWOULDBLOCK</B>
|
|
|
|
<DD>
|
|
|
|
The file descriptor
|
|
<I>fd</I>
|
|
|
|
refers to a socket and has been marked nonblocking
|
|
(<B>O_NONBLOCK</B>),
|
|
|
|
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.
|
|
<DT id="3"><B>EBADF</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is not a valid file descriptor or is not open for writing.
|
|
<DT id="4"><B>EDESTADDRREQ</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
refers to a datagram socket for which a peer address has not been set using
|
|
<B><A HREF="/cgi-bin/man/man2html?2+connect">connect</A></B>(2).
|
|
|
|
<DT id="5"><B>EDQUOT</B>
|
|
|
|
<DD>
|
|
The user's quota of disk blocks on the filesystem containing the file
|
|
referred to by
|
|
<I>fd</I>
|
|
|
|
has been exhausted.
|
|
<DT id="6"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
<I>buf</I>
|
|
|
|
is outside your accessible address space.
|
|
<DT id="7"><B>EFBIG</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="8"><B>EINTR</B>
|
|
|
|
<DD>
|
|
The call was interrupted by a signal before any data was written; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+signal">signal</A></B>(7).
|
|
|
|
<DT id="9"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is attached to an object which is unsuitable for writing;
|
|
or the file was opened with the
|
|
<B>O_DIRECT</B>
|
|
|
|
flag, and either the address specified in
|
|
<I>buf</I>,
|
|
|
|
the value specified in
|
|
<I>count</I>,
|
|
|
|
or the file offset is not suitably aligned.
|
|
<DT id="10"><B>EIO</B>
|
|
|
|
<DD>
|
|
A low-level I/O error occurred while modifying the inode.
|
|
This error may relate to the write-back of data written by an earlier
|
|
<B>write</B>(),
|
|
|
|
which may have been issued to a different file descriptor on
|
|
the same file.
|
|
Since Linux 4.13, errors from write-back come
|
|
with a promise that they
|
|
<I>may</I>
|
|
|
|
be reported by subsequent.
|
|
<B>write</B>()
|
|
|
|
requests, and
|
|
<I>will</I>
|
|
|
|
be reported by a subsequent
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fsync">fsync</A></B>(2)
|
|
|
|
(whether or not they were also reported by
|
|
<B>write</B>()).
|
|
|
|
|
|
An alternate cause of
|
|
<B>EIO</B>
|
|
|
|
on networked filesystems is when an advisory lock had been taken out
|
|
on the file descriptor and this lock has been lost.
|
|
See the
|
|
<I>Lost locks</I>
|
|
|
|
section of
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
for further details.
|
|
<DT id="11"><B>ENOSPC</B>
|
|
|
|
<DD>
|
|
The device containing the file referred to by
|
|
<I>fd</I>
|
|
|
|
has no room for the data.
|
|
<DT id="12"><B>EPERM</B>
|
|
|
|
<DD>
|
|
The operation was prevented by a file seal; see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2).
|
|
|
|
<DT id="13"><B>EPIPE</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is connected to a pipe or socket whose reading end is closed.
|
|
When this happens the writing process will also receive a
|
|
<B>SIGPIPE</B>
|
|
|
|
signal.
|
|
(Thus, the write return value is seen only if the program
|
|
catches, blocks or ignores this signal.)
|
|
</DL>
|
|
<P>
|
|
|
|
Other errors may occur, depending on the object connected to
|
|
<I>fd</I>.
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
|
|
|
|
|
<P>
|
|
|
|
Under SVr4 a write may be interrupted and return
|
|
<B>EINTR</B>
|
|
|
|
at any point,
|
|
not just before any data is written.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The types
|
|
<I>size_t</I>
|
|
|
|
and
|
|
<I>ssize_t</I>
|
|
|
|
are, respectively,
|
|
unsigned and signed integer data types specified by POSIX.1.
|
|
<P>
|
|
|
|
A successful return from
|
|
<B>write</B>()
|
|
|
|
does not make any guarantee that data has been committed to disk.
|
|
On some filesystems, including NFS, it does not even guarantee
|
|
that space has successfully been reserved for the data.
|
|
In this case,
|
|
some errors might be delayed until a future
|
|
<B>write</B>(),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fsync">fsync</A></B>(2),
|
|
|
|
or even
|
|
<B><A HREF="/cgi-bin/man/man2html?2+close">close</A></B>(2).
|
|
|
|
The only way to be sure is to call
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fsync">fsync</A></B>(2)
|
|
|
|
after you are done writing all your data.
|
|
<P>
|
|
|
|
If a
|
|
<B>write</B>()
|
|
|
|
is interrupted by a signal handler before any bytes are written,
|
|
then the call fails with the error
|
|
<B>EINTR</B>;
|
|
|
|
if it is interrupted after at least one byte has been written,
|
|
the call succeeds, and returns the number of bytes written.
|
|
<P>
|
|
|
|
On Linux,
|
|
<B>write</B>()
|
|
|
|
(and similar system calls) will transfer at most
|
|
0x7ffff000 (2,147,479,552) bytes,
|
|
returning the number of bytes actually transferred.
|
|
|
|
(This is true on both 32-bit and 64-bit systems.)
|
|
<P>
|
|
|
|
An error return value while performing
|
|
<B>write</B>()
|
|
|
|
using direct I/O does not mean the
|
|
entire write has failed. Partial data may be written
|
|
and the data at the file offset on which the
|
|
<B>write</B>()
|
|
|
|
was attempted should be considered inconsistent.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
|
|
("Thread Interactions with Regular File Operations"):
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="14"><DD>
|
|
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: ...
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
Among the APIs subsequently listed are
|
|
<B>write</B>()
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+writev">writev</A></B>(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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2))
|
|
|
|
perform a
|
|
<B>write</B>()
|
|
|
|
(or
|
|
<B><A HREF="/cgi-bin/man/man2html?2+writev">writev</A></B>(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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+close">close</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fsync">fsync</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+lseek">lseek</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pwrite">pwrite</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+writev">writev</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+fwrite">fwrite</A></B>(3)
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="15"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="16"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="17"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="18"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="19"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="20"><A HREF="#lbAG">CONFORMING TO</A><DD>
|
|
<DT id="21"><A HREF="#lbAH">NOTES</A><DD>
|
|
<DT id="22"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="23"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="24"><A HREF="#lbAK">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:35 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|