diff options
Diffstat (limited to 'man/man2/read.2')
| -rw-r--r-- | man/man2/read.2 | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/man/man2/read.2 b/man/man2/read.2 new file mode 100644 index 000000000..c74f62a0b --- /dev/null +++ b/man/man2/read.2 @@ -0,0 +1,245 @@ +.\" 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 (date) "Linux man-pages (unreleased)" +.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) |