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

FreeBSD Manual Pages

  
 
  

home | help
READ(2V)							      READ(2V)

NAME
       read, readv - read input

SYNOPSIS
       int read(fd, buf, nbyte)
       int fd;
       char *buf;
       int nbyte;

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

       int readv(fd, iov, iovcnt)
       int fd;
       struct iovec *iov;
       int iovcnt;

DESCRIPTION
       read()  attempts	to read	nbyte bytes of data from the object referenced
       by the descriptor fd into the buffer pointed to by buf.	 readv()  per-
       forms  the  same	action as read(), but scatters the input data into the
       iovcnt  buffers	specified  by  the   members   of   the	  iov	array:
       iov[0],iov[1], ..., iov[iovcnt-1].

       If  nbyte is zero, read() takes no action and returns 0.	 readv(), how-
       ever, returns -1	and sets the global variable errno (see	ERRORS below).

       For readv(), the	iovec structure	is defined as

	      struct iovec {
		   caddr_t   iov_base;
		   int	iov_len;
	      };

       Each iovec entry	specifies the base address and length of  an  area  in
       memory  where  data should be placed.  readv() 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  fd  (see	 lseek(2V)).  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
       position.  The value of the pointer associated with such	an  object  is
       undefined.

       Upon  successful	 completion,  read()  and readv() 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 references	a nor-
       mal file	which has that many bytes left before the EOF (end  of	file),
       but in no other case.

       If  the	process	calling	read() or readv() receives a signal before any
       data are	read, the system call is restarted unless the process  explic-
       itly set	the signal to interrupt	the call using sigvec()	or sigaction()
       (see the	discussions of SV_INTERRUPT on sigvec(2) and  SA_INTERRUPT  on
       sigaction(3V)).	 If read() or readv() is interrupted by	a signal after
       successfully reading some data, it returns the number of	bytes read.

       If nbyte	is not zero and	read() returns 0, then EOF has	been  reached.
       If readv() returns 0, then EOF has been reached.

       A  read()  or readv() from a STREAMS file (see intro(2))	can operate in
       three different modes: "byte-stream" mode,  "message-nondiscard"	 mode,
       and "message-discard" mode.  The	default	is byte-stream mode.  This can
       be changed using	the I_SRDOPT ioctl(2) request (see  streamio(4)),  and
       can  be tested with the I_GRDOPT	ioctl()	request.  In byte-stream mode,
       read() and readv() will retrieve	data from the  stream  until  as  many
       bytes as	were requested are transferred,	or until there is no more data
       to be retrieved.	 Byte-stream mode ignores message boundaries.

       In STREAMS message-nondiscard mode, read() and  readv()	will  retrieve
       data  until as many bytes as were requested are transferred, or until a
       message boundary	is reached.  If	the read() or  readv()	does  not  re-
       trieve  all  the	 data in a message, the	remaining data are left	on the
       stream, and can be retrieved by the next	read(),	readv(), or  getmsg(2)
       call.   Message-discard mode also retrieves data	until as many bytes as
       were requested are transferred, or a message boundary is	reached.  How-
       ever,  unread  data  remaining in a message after the read() or readv()
       returns are discarded, and are not available for	a  subsequent  read(),
       readv(),	or getmsg().

       When  attempting	 to  read  from	 a descriptor associated with an empty
       pipe, socket, FIFO, or stream:

       o  If the object	the  descriptor	 is  associated	 with  is  marked  for
	  4.2BSD-style non-blocking I/O	(with the FIONBIO ioctl() request or a
	  call to fcntl(2V) using the FNDELAY flag from	 <sys/file.h>  or  the
	  O_NDELAY  flag  from	<fcntl.h> in the 4.2BSD	environment), the read
	  will return -1 and errno will	be set to EWOULDBLOCK.

       o  If the descriptor is marked for System V-style non-blocking I/O (us-
	  ing  fcntl()	with  the FNBIO	flag from <sys/file.h> or the O_NDELAY
	  flag from <fcntl.h> in the System V environment), and	does not refer
	  to  a	 stream, the read will return 0.  Note:	this is	indistinguish-
	  able from EOF.

       o  If the descriptor is marked for POSIX-style non-blocking I/O	(using
	  fcntl()  with	 the  O_NONBLOCK  flag from <fcntl.h>) and refers to a
	  stream, the read will	return -1 and errno will be set	to EAGAIN.

       o  If neither the descriptor nor	the object it refers to	are marked for
	  non-blocking	I/O, the read will block until data is available to be
	  read or the object has been "disconnected".  A pipe or FIFO is "dis-
	  connected" when no process has the object open for writing; a	socket
	  that was connected is	"disconnected" when the	connection is  broken;
	  a  stream  is	"disconnected" when a hangup condition occurs (for in-
	  stance, when carrier drops on	a terminal).

       If the descriptor or the	object is marked  for  non-blocking  I/O,  and
       less  data  are	available than are requested by	the read() or readv(),
       only the	data that are available	are returned, and the count  indicates
       how many	bytes of data were actually read.

       When reading from a STREAMS file, handling of zero-byte messages	is de-
       termined	by the current read mode setting.  In byte-stream mode,	read()
       and  readv()  accept  data  until  as  many bytes as were requested are
       transferred, or until there is no more data to read, or until  a	 zero-
       byte  message block is encountered.  read() and readv() then return the
       number of bytes read, and places	the  zero-byte	message	 back  on  the
       stream  to  be  retrieved by the	next read(), readv(), or getmsg().  In
       the two other modes, a zero-byte	message	returns	a value	of 0  and  the
       message	is  removed from the stream.  When a zero-byte message is read
       as the first message on a stream, a value of 0 is  returned  regardless
       of the read mode.

       A read()	or readv() from	a STREAMS file can only	process	data messages.
       It cannot process any type of protocol message and will fail if a  pro-
       tocol message is	encountered at the streamhead.

       Upon  successful	 completion,  read()  and  readv() mark	for update the
       st_atime	field of the file.

RETURN VALUES
       read() and readv() return the number of bytes actually read on success.
       On failure, they	return -1 and set errno	to indicate the	error.

ERRORS
       EAGAIN		   The descriptor referred to a	stream,	was marked for
			   System V-style non-blocking I/O, and	no  data  were
			   ready to be read.

       EBADF		   d is	not a valid file descriptor open for reading.

       EBADMSG		   The message waiting to be read on a stream is not a
			   data	message.

       EFAULT		   buf points outside the allocated address space.

       EINTR		   The process performing a read from  a  slow	device
			   received  a signal before any data arrived, and the
			   signal was set to interrupt the system call.

       EINVAL		   The stream is linked	below a	multiplexor.

			   The pointer associated with fd was negative.

       EIO		   An I/O error	occurred while reading from or writing
			   to the file system.

			   The	calling	 process  is  in  a background process
			   group and is	attempting to read from	 its  control-
			   ling	terminal and the process is ignoring or	block-
			   ing SIGTTIN.

			   The calling process	is  in	a  background  process
			   group  and  is attempting to	read from its control-
			   ling	terminal and the process is orphaned.

       EISDIR		   fd refers to	a directory which is on	a file	system
			   mounted using the NFS.

       EWOULDBLOCK	   The	file  was marked for 4.2BSD-style non-blocking
			   I/O,	and no data were ready to be read.

       In addition to the above, readv() may set errno to:

       EFAULT		   Part	of iov points outside the process's  allocated
			   address space.

       EINVAL		   iovcnt was less than	or equal to 0, or greater than
			   16.

			   One of the iov_len values in	the iov	array was neg-
			   ative.

			   The	sum  of	 the  iov_len  values in the iov array
			   overflowed a	32-bit integer.

       A read()	or readv() from	a STREAMS file will also fail if an error mes-
       sage is received	at the stream head.  In	this case, errno is set	to the
       value returned in the error message.  If	a hangup occurs	on the	stream
       being  read,  read() will continue to operate normally until the	stream
       head read queue is empty.  Thereafter, it will return 0.

SEE ALSO
       dup(2V),	fcntl(2V), getmsg(2), intro(2),	ioctl(2), lseek(2V), open(2V),
       pipe(2V), select(2), socket(2), socketpair(2), streamio(4), termio(4)

				21 January 1990			      READ(2V)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO

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

home | help