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

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

     In	the non-threaded library read()	is implemented as the read syscall.

     In	the threaded library, the read syscall is assembled to
     _thread_sys_read()	and read() is implemented as a function	which locks d
     for read, then calls _thread_sys_read().  If the call to
     _thread_sys_read()	would block, a context switch is performed.  Before
     returning,	read() unlocks d.

     In	the non-threaded library readv() is implemented	as the readv syscall.

     In	the threaded library, the readv	syscall	is assembled to
     _thread_sys_readv() and readv() is	implemented as a function which	locks
     d for read, then calls _thread_sys_readv().  If the call to
     _thread_sys_readv() would block, a	context	switch is performed.  Before
     returning,	readv()	unlocks	d.

     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.

     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.

4th Berkeley Distribution      February	26, 1994     4th Berkeley Distribution


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

home | help