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
       retrieve	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
	  (using 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
	  instance, 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
       determined  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=2&manpath=SunOS+4.1.3>

home | help