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

FreeBSD Manual Pages

  
 
  

home | help
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://www.freebsd.org/cgi/man.cgi?query=read&sektion=2&manpath=FreeBSD+4.9-RELEASE>

home | help