FreeBSD Manual Pages
READ(2) BSD System Calls Manual READ(2) NAME read, readv, pread -- read input LIBRARY Standard C Library (libc, -lc) SYNOPSIS #include <sys/types.h> #include <sys/uio.h> #include <unistd.h> ssize_t read(int d, void *buf, size_t nbytes); ssize_t readv(int d, const struct iovec *iov, int iovcnt); ssize_t pread(int d, void *buf, size_t nbytes, off_t offset); DESCRIPTION Read() attempts to read nbytes of data from the object referenced by the descriptor d into the buffer pointed to by buf. Readv() performs the same action, but scatters the input data into the iovcnt buffers speci- fied by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1]. Pread() performs the same function, but reads from the specified position in the file without modifying the file pointer. For readv(), the iovec structure is defined as: struct iovec { char *iov_base; /* Base address. */ size_t iov_len; /* Length. */ }; Each iovec entry specifies the base address and length of an area in mem- ory where data should be placed. Readv() will always fill an area com- pletely before proceeding to the next. On objects capable of seeking, the read() starts at a position given by the pointer associated with d (see lseek(2)). Upon return from read(), the pointer is incremented by the number of bytes actually read. Objects that are not capable of seeking always read from the current po- sition. The value of the pointer associated with such an object is unde- fined. Upon successful completion, read(), readv(), and pread() return the num- ber of bytes actually read and placed in the buffer. The system guaran- tees to read the number of bytes requested if the descriptor references a normal file that has that many bytes left before the end-of-file, but in no other case. RETURN VALUES If successful, the number of bytes actually read is returned. Upon read- ing end-of-file, zero is returned. Otherwise, a -1 is returned and the global variable errno is set to indicate the error. ERRORS Read(), readv(), and pread() will succeed unless: [EBADF] D is not a valid file or socket descriptor open for reading. [EFAULT] Buf points outside the allocated address space. [EIO] An I/O error occurred while reading from the file sys- tem. [EINTR] A read from a slow device was interrupted before any data arrived by the delivery of a signal. [EINVAL] The pointer associated with d was negative. [EAGAIN] The file was marked for non-blocking I/O, and no data were ready to be read. In addition, readv() may return one of the following errors: [EINVAL] Iovcnt was less than or equal to 0, or greater than 16. [EINVAL] One of the iov_len values in the iov array was nega- tive. [EINVAL] The sum of the iov_len values in the iov array over- flowed a 32-bit integer. [EFAULT] Part of the iov points outside the process's allocated address space. The pread() call may also return the following errors: [EINVAL] The specified file offset is invalid. [ESPIPE] The file descriptor is associated with a pipe, socket, or FIFO. SEE ALSO dup(2), fcntl(2), open(2), pipe(2), select(2), socket(2), socketpair(2) STANDARDS The read() function call is expected to conform to ISO/IEC 9945-1:1990 ("POSIX.1"). The readv() and pread() functions are expected to conform to X/Open Portability Guide Issue 4, Version 2 ("XPG4.2"). HISTORY The pread() function call appeared in AT&T System V Release 4 UNIX. The readv() function call appeared in 4.2BSD. A read() function call ap- peared in Version 6 AT&T UNIX. BSD February 26, 1994 BSD
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=read&sektion=2&manpath=FreeBSD+4.5-RELEASE>