diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/write.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/write.2 | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/write.2 b/upstream/debian-bookworm/man2/write.2 new file mode 100644 index 00000000..f4061b50 --- /dev/null +++ b/upstream/debian-bookworm/man2/write.2 @@ -0,0 +1,334 @@ +.\" 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 2022-12-04 "Linux man-pages 6.03" +.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 +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, 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) |