diff options
Diffstat (limited to 'man2/read.2')
| -rw-r--r-- | man2/read.2 | 245 |
1 files changed, 0 insertions, 245 deletions
diff --git a/man2/read.2 b/man2/read.2 deleted file mode 100644 index 973993e..0000000 --- a/man2/read.2 +++ /dev/null @@ -1,245 +0,0 @@ -.\" This manpage is Copyright (C) 1992 Drew Eckhardt; -.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. -.\" and Copyright (C) 2009-2015 Michael Kerrisk, <mtk.manpages.gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith <faith@cs.unc.edu> -.\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt -.\" <michael@cantor.informatik.rwth-aachen.de> -.\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer <aeb@cwi.nl> -.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl> -.\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond <esr@thyrsus.com> -.\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt -.\" <michael@cantor.informatik.rwth-aachen.de> -.\" -.TH read 2 2024-03-12 "Linux man-pages 6.7" -.SH NAME -read \- read from a file descriptor -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <unistd.h> -.P -.BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count ); -.fi -.SH DESCRIPTION -.BR read () -attempts to read up to -.I count -bytes from file descriptor -.I fd -into the buffer starting at -.IR buf . -.P -On files that support seeking, -the read operation commences at the file offset, -and the file offset is incremented by the number of bytes read. -If the file offset is at or past the end of file, -no bytes are read, and -.BR read () -returns zero. -.P -If -.I count -is zero, -.BR read () -.I may -detect the errors described below. -In the absence of any errors, -or if -.BR read () -does not check for errors, a -.BR read () -with a -.I count -of 0 returns zero and has no other effects. -.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 read is returned (zero indicates end of -file), and the file position is advanced by this number. -It is not an error if this number is smaller than the number of bytes -requested; this may happen for example because fewer bytes are actually -available right now (maybe because we were close to end-of-file, or -because we are reading from a pipe, or from a terminal), or because -.BR read () -was interrupted by a signal. -See also NOTES. -.P -On error, \-1 is returned, and -.I errno -is set to indicate the error. -In this case, it is left unspecified whether -the file position (if any) changes. -.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 read 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 read 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 reading. -.TP -.B EFAULT -.I buf -is outside your accessible address space. -.TP -.B EINTR -The call was interrupted by a signal before any data was read; see -.BR signal (7). -.TP -.B EINVAL -.I fd -is attached to an object which is unsuitable for reading; -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 EINVAL -.I fd -was created via a call to -.BR timerfd_create (2) -and the wrong size buffer was given to -.BR read (); -see -.BR timerfd_create (2) -for further information. -.TP -.B EIO -I/O error. -This will happen for example when the process is in a -background process group, tries to read from its controlling terminal, -and either it is ignoring or blocking -.B SIGTTIN -or its process group -is orphaned. -It may also occur when there is a low-level I/O error -while reading from a disk or tape. -A further possible 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 EISDIR -.I fd -refers to a directory. -.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. -.SH NOTES -On Linux, -.BR read () -(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 -On NFS filesystems, reading small amounts of data will update the -timestamp only the first time, subsequent calls may not do so. -This is caused -by client side attribute caching, because most if not all NFS clients -leave -.I st_atime -(last file access time) -updates to the server, and client side reads satisfied from the -client's cache will not cause -.I st_atime -updates on the server as there are no -server-side reads. -UNIX semantics can be obtained by disabling client-side attribute caching, -but in most situations this will substantially -increase server load and decrease performance. -.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 read () -and -.BR readv (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 read () -(or -.BR readv (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 reads in the two processes -might (incorrectly) overlap in the blocks of data that they obtained. -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 ioctl (2), -.BR lseek (2), -.BR open (2), -.BR pread (2), -.BR readdir (2), -.BR readlink (2), -.BR readv (2), -.BR select (2), -.BR write (2), -.BR fread (3) |