| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| write \- write to a file descriptor |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .PP |
| .BI "ssize_t write(int " fd ", const void *" buf ", 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 |
| .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. |
| 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 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. |
| 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, 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) |