summaryrefslogtreecommitdiffstats
path: root/man/man2/write.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/write.2')
-rw-r--r--man/man2/write.2329
1 files changed, 329 insertions, 0 deletions
diff --git a/man/man2/write.2 b/man/man2/write.2
new file mode 100644
index 0000000..3e87069
--- /dev/null
+++ b/man/man2/write.2
@@ -0,0 +1,329 @@
+.\" 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>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+write \- write to a file descriptor
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "ssize_t write(int " fd ", const void " buf [. count "], size_t " count );
+.fi
+.SH DESCRIPTION
+.BR write ()
+writes up to
+.I count
+bytes from the buffer starting at
+.I buf
+to the file referred to by the file descriptor
+.IR fd .
+.P
+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).)
+.P
+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.
+.P
+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.
+.P
+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.
+On error, \-1 is returned, and \fIerrno\fP is set
+to indicate the error.
+.P
+Note that a successful
+.BR write ()
+may transfer fewer than
+.I count
+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
+.BR write ()
+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
+.BR write ()
+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 \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 is 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
+.B 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.
+This error may relate to the write-back of data written by an earlier
+.BR write (),
+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
+be reported by subsequent.
+.BR write ()
+requests, and
+.I will
+be reported by a subsequent
+.BR fsync (2)
+(whether or not they were also reported by
+.BR write ()).
+.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750
+An alternate cause of
+.B EIO
+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"
+section of
+.BR fcntl (2)
+for further details.
+.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.)
+.P
+Other errors may occur, depending on the object connected to
+.IR fd .
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+SVr4, 4.3BSD, POSIX.1-2001.
+.\" SVr4 documents additional error
+.\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE.
+.P
+Under SVr4 a write may be interrupted and return
+.B EINTR
+at any point,
+not just before any data is written.
+.SH NOTES
+A successful return from
+.BR write ()
+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
+.BR write (),
+.BR fsync (2),
+or even
+.BR close (2).
+The only way to be sure is to call
+.BR fsync (2)
+after you are done writing all your data.
+.P
+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.
+.P
+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.)
+.P
+An error return value while performing
+.BR write ()
+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
+.BR write ()
+was attempted should be considered inconsistent.
+.SH BUGS
+According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
+("Thread Interactions with Regular File Operations"):
+.P
+.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
+.P
+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, before Linux 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 to 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)