diff options
Diffstat (limited to 'man2/write.2')
| -rw-r--r-- | man2/write.2 | 329 |
1 files changed, 0 insertions, 329 deletions
diff --git a/man2/write.2 b/man2/write.2 deleted file mode 100644 index 9cba91d88..000000000 --- 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 (date) "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> -.PP -.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 . -.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. -On error, \-1 is returned, and \fIerrno\fP is set -to indicate the error. -.PP -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). -.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 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.) -.PP -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. -.PP -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. -.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.) -.PP -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"): -.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, 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) |