summaryrefslogtreecommitdiffstats
path: root/man2/write.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/write.2')
-rw-r--r--man2/write.2329
1 files changed, 0 insertions, 329 deletions
diff --git a/man2/write.2 b/man2/write.2
deleted file mode 100644
index fc22ae3..0000000
--- a/man2/write.2
+++ /dev/null
@@ -1,329 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)