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

FreeBSD Manual Pages

  
 
  

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

NAME
     read, readv, pread, preadv	-- read	input

SYNOPSIS
     #include <unistd.h>

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

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

     #include <sys/uio.h>

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

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

     ssize_t
     preadv(int	d, const struct	iovec *iov, int	iovcnt,	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() and preadv() perform the same functions, but read from the	speci-
     fied position offset in the file without modifying	the file pointer.

     For readv() and preadv(), the iovec structure is defined as:

	   struct iovec	{
		   void	*iov_base;
		   size_t iov_len;
	   };

     Each iovec	entry specifies	the base address and length of an area in mem-
     ory where data should be placed.  readv() and preadv() will always	fill
     an	area completely	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(), pread(), and preadv()	return
     the number	of bytes actually read and placed in the buffer.  The system
     guarantees	to read	the number of bytes requested if the descriptor	refer-
     ences a normal file that has that many bytes left before the end-of-file,
     but in no other case.

     Note that readv() and preadv() will fail if the value of iovcnt exceeds
     the constant IOV_MAX.

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(), pread(), and preadv() will fail if:

     [EBADF]		d is not a valid file or socket	descriptor open	for
			reading.

     [EFAULT]		Part of	buf points outside the process's allocated ad-
			dress space.

     [EINTR]		A read from a slow device (i.e.	one that might block
			for an arbitrary amount	of time) was interrupted by
			the delivery of	a signal before	any data arrived.

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

     [EISDIR]		The underlying file is a directory.

     In	addition, read() and readv() may return	the following errors:

     [EAGAIN]		The file was marked for	non-blocking I/O, and no data
			were ready to be read.

     [ENOTCONN]		The file is a socket associated	with a connection-ori-
			ented protocol and has not been	connected.

     [EIO]		The process is a member	of a background	process	at-
			tempting to read from its controlling terminal,	the
			process	is ignoring or blocking	the SIGTTIN signal or
			the process group is orphaned.

     read() and	pread()	may return the following error:

     [EINVAL]		nbytes was larger than SSIZE_MAX.

     pread() and preadv() may return the following errors:

     [EINVAL]		offset was negative.

     [ESPIPE]		d is associated	with a pipe, socket, FIFO, or tty.

     readv() and preadv() may return the following errors:

     [EINVAL]		iovcnt was less	than or	equal to 0, or greater than
			IOV_MAX.

     [EINVAL]		The sum	of the iov_len values in the iov array over-
			flowed an ssize_t.

     [EFAULT]		Part of	iov points outside the process's allocated ad-
			dress space.

SEE ALSO
     dup(2), fcntl(2), open(2),	pipe(2), poll(2), select(2), socket(2),
     socketpair(2)

STANDARDS
     The read(), readv(), and pread() functions	conform	to IEEE	Std
     1003.1-2008 ("POSIX.1").

HISTORY
     A read() system call first	appeared in Version 1 AT&T UNIX; readv() in
     4.1cBSD; pread() in AT&T System V Release 4 UNIX; and preadv() in
     OpenBSD 2.7.

CAVEATS
     Error checks should explicitly test for -1.  Code such as

	   while ((nr =	read(fd, buf, sizeof(buf))) > 0)

     is	not maximally portable,	as some	platforms allow	for nbytes to range
     between SSIZE_MAX and SIZE_MAX - 2, in which case the return value	of an
     error-free	read() may appear as a negative	number distinct	from -1.
     Proper loops should use

	   while ((nr =	read(fd, buf, sizeof(buf))) != -1 && nr	!= 0)

FreeBSD	13.0		       February	11, 2020		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=read&sektion=2&manpath=OpenBSD+6.9>

home | help