read (翻译 man 3)

 

READ(2)                       Linux Programmer's Manual                       READ(2)

NAME

       read - read from a file descriptor

//从fd中读取数据

SYNOPSIS

       #include <unistd.h>

       ssize_t read(int fd, void *buf, size_t count);

DESCRIPTION

       read() attempts to read up to count bytes from file descriptor fd into the
       buffer starting at buf.
//read()尝试从fd中读出count个字节放在buf的开头
       If count is zero, read() returns zero and has no other results.  If count is
       greater than SSIZE_MAX, the result is unspecified.

//如果count是0,read()返回0并没有其他的结果.如果count比SSIZE_MAX还大,结果是未定义的.

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 read() was interrupted by a signal.  On error, -1 is
       returned, and errno is set appropriately.  In this case it is left unspecified
       whether the file position (if any) changes.

//成功:返回读取的字节数(0代表这文件末尾),文件的位置在返回的字节数之前?.如果返回的数字小于
//要求读出的数字,这不是一个错误.这种情况可能在例如只有少量的字符当前有效(可能是因为是使用
//EOF关闭,或者是从管道读取数据,或者是从一个终端),或者是被一个信号中断.
//错误:返回-1,errno被适当的设置.在这种情况下文件指针的位置是否变化是留下的未特别指出的.

ERRORS

       EAGAIN The file descriptor fd refers to a file other than a socket and has
              been marked nonblocking (O_NONBLOCK), and the read would block.
//fd引用的是一个文件而不是一个socket,而且fd已经标识为非阻塞,读操作将会阻塞.
       EAGAIN or EWOULDBLOCK
              The file descriptor fd refers to a socket and has been marked
              nonblocking (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.
//fd引用的是一个socket,而且fd已经标识为非阻塞,读操作将会阻塞.POSIX.1-2001允许在这种情况下
//返回一个错误.不需要这些常量保持相同的值,所以一个轻便的程序应该检测这2种可能性
       EBADF  fd is not a valid file descriptor or is not open for reading.
//fd不是一个有效的fd,或者还没有打开
       EFAULT buf is outside your accessible address space.
//buf溢出,超过你分配的大小
       EINTR  The call was interrupted by a signal before any data was read; see
              signal(7).
//在读取数据之前被信号中断
       EINVAL fd is attached to an object which is unsuitable for reading; or the
              file was opened with the O_DIRECT flag, and either the address
              specified in buf, the value specified in count, or the current file
              offset is not suitably aligned.
//对象的fd不适合读取,或者是文件打开的时候使用了O_DIRECT,buf,count中的值或者是
//当前文件的偏移量都是没有线性分配的.
       EINVAL fd was created via a call to timerfd_create(2) and the wrong size
              buffer was given to read(); see timerfd_create(2) for further
              information.
//fd通过timerfd_create()的调用创建出来.错误的buffer大小给了read()
       EIO    I/O error.  This will happen for example when the process is in a
              background process group, tries to read from its controlling tty, and
              either it is ignoring or blocking 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.
//IO错误:例如进程在后台进程组,试图从它控制的tty中读取数据,和进程忽略或者被SIGTTIN阻塞
//或者进程的组被孤立.IO错误也可能在低等级的IO错误当从一个磁盘或者是磁带读取数据的时候发生.
       EISDIR fd refers to a directory.
//fd指向的是一个文件夹
       Other errors may occur, depending on the object connected to fd.  POSIX allows
       a read() that is interrupted after reading some data to return -1 (with errno
       set to EINTR) or to return the number of bytes already read.

//其他的错误也会发生,取决于对象关联的fd.POSIX允许被中断的read()在读取一些数据之后返回-1
//(errno为EINTR),或者返回实际读取的的字节数.

CONFORMING TO

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES

       On NFS file systems, reading small amounts of data will only update the
       timestamp 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
       st_atime (last file access time) updates to the server and client side reads
       satisfied from the client's cache will not cause 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.
//在NFS下,读取少量数据仅仅会在最初的时候更新时间戳,接下来的调用就不做这些了.这是由于客户端
//方面的属性导致的,因为并不是所有的NFS客户端将最后访问时间升级到从客户端读取的服务器端和客户端
//的数据,这将不会导致更新st_atime因为服务器端不会读文件.Unix语义可以通过客户端的属性缓存来阻止,
//但是在大多数情况下,这将大幅增加服务器的负担和降低系统性能.
       Many file systems and disks were considered to be fast enough that the
       implementation of O_NONBLOCK was deemed unnecessary.  So, O_NONBLOCK may not
       be available on files and/or disks.

//很多文件系统和磁盘都被认为是足够快的,那样O_NONBLOCK的执行就认为是不必要的.
//所以,O_NONBLOCK在文件和磁盘中就可能无效

SEE ALSO

       close(2), fcntl(2), ioctl(2), lseek(2), open(2), pread(2), readdir(2),
       readlink(2), readv(2), select(2), write(2), fread(3)

COLOPHON

       This page is part of release 3.29 of the Linux man-pages project.  A
       description of the project, and information about reporting bugs, can be found
       at http://www.kernel.org/doc/man-pages/.

Linux                                 2009-02-23                              READ(2)