| .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
| .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
| .\" |
| .\" %%%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 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 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| read \- read from a file descriptor |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .sp |
| .BI "ssize_t read(int " fd ", void *" buf ", 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 . |
| |
| 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. |
| |
| 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. |
| |
| If |
| .I count |
| is greater than |
| .BR SSIZE_MAX , |
| the result is unspecified. |
| .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. |
| |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| 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 |
| .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 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. |
| .TP |
| .B EISDIR |
| .I fd |
| refers to a directory. |
| .PP |
| Other errors may occur, depending on the object connected to |
| .IR fd . |
| POSIX allows a |
| .BR read () |
| that is interrupted after reading some data |
| to return \-1 (with |
| .I errno |
| set to |
| .BR EINTR ) |
| or to return the number of bytes already read. |
| .SH CONFORMING TO |
| SVr4, 4.3BSD, POSIX.1-2001. |
| .SH NOTES |
| The types |
| .I size_t |
| and |
| .I ssize_t |
| are, respectively, |
| unsigned and signed integer data types specified by POSIX.1. |
| |
| 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.) |
| |
| 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"): |
| |
| .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 |
| |
| 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, 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 read () |
| (or |
| .BR readv (2)) |
| at the same time, then the I/O operations were not atomic |
| with respect 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) |