Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
READ(2)			    BSD	System Calls Manual		       READ(2)

     read, readv, pread	-- read	input

     Standard C	Library	(libc, -lc)

     #include <sys/types.h>
     #include <sys/uio.h>
     #include <unistd.h>

     read(int d, void *buf, size_t nbytes);

     readv(int d, const	struct iovec *iov, int iovcnt);

     pread(int d, void *buf, size_t nbytes, off_t offset);

     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-

     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.

     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.

     Read(), readv(), and pread() will succeed unless:

     [EBADF]		D is not a valid file or socket	descriptor open	for

     [EFAULT]		Buf points outside the allocated address space.

     [EIO]		An I/O error occurred while reading from the file sys-

     [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.

     [EISDIR]		The file descriptor is associated with a directory re-
			siding on a filesystem that does not allow regular
			read operations	on directories (e.g. NFS).

     [EOPNOTSUPP]	The file descriptor is associated with a filesystem
			and file type that do not allow	regular	read opera-
			tions on it.

     In	addition, readv() may return one of the	following errors:

     [EINVAL]		Iovcnt was less	than or	equal to 0, or greater than

     [EINVAL]		One of the iov_len values in the iov array was nega-

     [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.

     dup(2), fcntl(2), open(2),	pipe(2), select(2), socket(2), socketpair(2)

     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").

     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


Want to link to this manual page? Use this URL:

home | help