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

FreeBSD Manual Pages

  
 
  

home | help
read(2)				 System	Calls			       read(2)

NAME
       read, readv, pread - read from file

SYNOPSIS
       #include	<unistd.h>

       ssize_t read(int	fildes,	void *buf, size_t nbyte);

       ssize_t pread(int fildes, void *buf, size_t nbyte, off_t	offset);

       #include	<sys/uio.h>

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

DESCRIPTION
       The  read() function attempts to	read nbyte bytes from the file associ-
       ated with the open file descriptor, fildes, into	the buffer pointed  to
       by buf.

       If nbyte	is 0, read() returns 0 and has no other	results.

       On files	that support seeking (for example, a regular file), the	read()
       starts at a position in the file	given by the  file  offset  associated
       with  fildes.  The  file	 offset	 is incremented	by the number of bytes
       actually	read.

       Files that do not support seeking (for example, terminals) always  read
       from  the  current position. The	value of a file	offset associated with
       such a file is undefined.

       If fildes refers	to a socket, read()  is	 equivalent  to	 recv(3SOCKET)
       with no flags set.

       No  data	 transfer  will	 occur	past  the current end-of-file.	If the
       starting	position is at or after	the end-of-file, 0 will	 be  returned.
       If  the	file refers to a device	special	file, the result of subsequent
       read() requests is implementation-dependent.

       When attempting to read from a regular file with	mandatory  file/record
       locking	set (see chmod(2)), and	there is a write lock owned by another
       process on the segment of the file to be	read:

	 o  If O_NDELAY	or O_NONBLOCK is set, read() returns -1	and sets errno
	    to EAGAIN.

	 o  If	O_NDELAY  and  O_NONBLOCK  are	clear, read() sleeps until the
	    blocking record lock is removed.

       When attempting to read from an empty pipe (or FIFO):

	 o  If no process has the pipe open for	writing, read()	returns	 0  to
	    indicate end-of-file.

	 o  If some process has	the pipe open for writing and O_NDELAY is set,
	    read() returns 0.

	 o  If some process has	the pipe open for writing  and	O_NONBLOCK  is
	    set, read()	returns	-1 and sets errno to EAGAIN.

	 o  If	O_NDELAY and O_NONBLOCK	are clear, read() blocks until data is
	    written to the pipe	or the pipe is closed by  all  processes  that
	    had	opened the pipe	for writing.

       When  attempting	 to read a file	associated with	a terminal that	has no
       data currently available:

	 o  If O_NDELAY	is set,	read() returns 0.

	 o  If O_NONBLOCK is set, read() returns -1 and	sets errno to EAGAIN.

	 o  If O_NDELAY	and O_NONBLOCK are clear,  read()  blocks  until  data
	    become available.

       When  attempting	 to  read  a file associated with a socket or a	stream
       that is not a pipe, a FIFO, or a	terminal,  and the file	 has  no  data
       currently available:

	 o  If O_NDELAY	or O_NONBLOCK is set, read() returns -1	and sets errno
	    to EAGAIN.

	 o  If O_NDELAY	and O_NONBLOCK are clear,  read()  blocks  until  data
	    becomes available.

       The  read()  function  reads data previously written to a file.	If any
       portion of a regular file prior to the end-of-file has not  been	 writ-
       ten,  read()  returns bytes with	value 0.  For example, lseek(2)	allows
       the file	offset to be set beyond	the end	of existing data in the	 file.
       If  data	 is  later  written at this point, subsequent reads in the gap
       between the previous end	of data	and the	newly written data will	return
       bytes with value	0 until	data is	written	into the gap.

       For  regular files, no data transfer will occur past the	offset maximum
       established in the open file description	associated with	fildes.

       Upon successful completion, where nbyte is greater than 0, read()  will
       mark  for  update the st_atime field of the file, and return the	number
       of bytes	read. This number will never be	greater	than nbyte. The	 value
       returned	may be less than nbyte if the number of	bytes left in the file
       is less than nbyte, if the read() request was interrupted by a  signal,
       or  if  the  file  is a pipe or FIFO or special file and	has fewer than
       nbyte bytes immediately available for reading.  For example,  a	read()
       from  a	file  associated  with a terminal may return one typed line of
       data.

       If a read() is interrupted by a signal before it	 reads	any  data,  it
       will return -1 with errno set to	EINTR.

       If  a  read() is	interrupted by a signal	after it has successfully read
       some data, it will return the number of bytes read.

       A read()	from a STREAMS file can	read data 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, and can be tested with the I_GRDOPT ioctl().
       In byte-stream mode, read() retrieves 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() retrieves data until as many
       bytes as	were requested are transferred,	or until a message boundary is
       reached.	 If read() does	not retrieve all the data in  a	 message,  the
       remaining  data is left on the STREAM, and can be retrieved by the next
       read() call.  Message-discard mode also retrieves data  until  as  many
       bytes  as  were	requested  are	transferred,  or a message boundary is
       reached.	 However, unread data remaining	in a message after the	read()
       returns	is  discarded,	and  is	not available for a subsequent read(),
       readv() or getmsg(2) call.

       How read() handles zero-byte STREAMS messages is	determined by the cur-
       rent read mode setting.	In byte-stream mode, read() accepts data until
       it has read nbyte bytes,	or until there is no more  data	 to  read,  or
       until  a	 zero-byte  message  block is encountered. The read() function
       then returns 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(2). In message-nondiscard	mode or	message-discard	mode, a	 zero-
       byte  message  returns  0  and  the message is removed from the STREAM.
       When a zero-byte	message	is read	as the first message on	a STREAM,  the
       message is removed from the STREAM and 0	is returned, regardless	of the
       read mode.

       A read()	from a STREAMS file returns the	data in	 the  message  at  the
       front of	the STREAM head	read queue, regardless of the priority band of
       the message.

       By default, STREAMs are in control-normal mode, in which	a read()  from
       a  STREAMS  file	can only process messages that contain a data part but
       do not contain a	control	part.  The read() fails	if a message  contain-
       ing  a  control	part  is encountered at	the STREAM head.  This default
       action can be changed by	placing	the STREAM in either control-data mode
       or control-discard mode with the	I_SRDOPT ioctl() command.  In control-
       data mode, read() converts any control part to data and	passes	it  to
       the  application	before passing any data	part originally	present	in the
       same message.  In control-discard mode, read() discards message control
       parts but returns to the	process	any data part in the message.

       In  addition,  read() and readv() will fail if the STREAM head had pro-
       cessed an asynchronous error before the call.  In this case, the	 value
       of  errno does not reflect the result of	read() or readv() but reflects
       the prior error.	If a hangup occurs on the STREAM  being	 read,	read()
       continues  to  operate  normally	 until	the  STREAM head read queue is
       empty. Thereafter, it returns 0.

   readv()
       The readv() function is equivalent to read(), but places	the input data
       into  the  iovcnt  buffers  specified  by the members of	the iov	array:
       iov0, iov1, ...,	iov[iovcnt-1]. The iovcnt argument is valid if greater
       than 0 and less than or equal to	IOV_MAX.

       The iovec structure contains the	following members:

       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.  The	readv()	function always	 fills
       an area completely before proceeding to the next.

       Upon successful completion, readv() marks for update the	st_atime field
       of the file.

   pread()
       The pread() function performs the same action as	read(),	except that it
       reads  from  a  given  position	in  the	file without changing the file
       pointer.	The first three	arguments to pread() are the  same  as	read()
       with  the addition of a fourth argument offset for the desired position
       inside the file.	pread()	will read up to	the maximum offset value  that
       can be represented in an	off_t for regular files. An attempt to perform
       a pread() on a file that	is incapable of	seeking	results	in an error.

RETURN VALUES
       Upon successful completion, read() and readv()  return  a  non-negative
       integer	indicating  the	 number	of bytes actually read.	Otherwise, the
       functions return	-1 and set errno to indicate the error.

ERRORS
       The read(), readv(), and	pread()	functions will fail if:

       EAGAIN	       Mandatory file/record  locking  was  set,  O_NDELAY  or
		       O_NONBLOCK  was	set,  and  there was a blocking	record
		       lock; total amount  of  system  memory  available  when
		       reading	using  raw I/O is temporarily insufficient; no
		       data is waiting to be read on a file associated with  a
		       tty  device  and	 O_NONBLOCK  was set; or no message is
		       waiting to be read on a stream and O_NDELAY  or	O_NON-
		       BLOCK was set.

       EBADF	       The fildes argument is not a valid file descriptor open
		       for reading.

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

       EDEADLK	       The  read was going to go to sleep and cause a deadlock
		       to occur.

       EINTR	       A signal	was caught during the read  operation  and  no
		       data was	transferred.

       EINVAL	       An  attempt  was	made to	read from a stream linked to a
		       multiplexor.

       EIO	       A physical I/O error has	occurred, or the process is in
		       a  background  process  group and is attempting to read
		       from its	controlling terminal, and either  the  process
		       is  ignoring  or	 blocking  the	SIGTTIN	 signal	or the
		       process group of	the process is orphaned.

       EISDIR	       The fildes argument refers to a	directory  on  a  file
		       system  type  that  does	not support read operations on
		       directories.

       ENOLCK	       The system record lock table was	full, so the read() or
		       readv() could not go to sleep until the blocking	record
		       lock was	removed.

       ENOLINK	       The fildes argument is on a remote machine and the link
		       to that machine is no longer active.

       ENXIO	       The device associated with fildes is a block special or
		       character special  file	and  the  value	 of  the  file
		       pointer is out of range.

       The read() and pread() functions	will fail if:

       EFAULT	       The buf argument	points to an illegal address.

       EINVAL	       The nbyte argument overflowed an	ssize_t.

       The read() and readv() functions	will fail if:

       EOVERFLOW       The  file  is  a	regular	file, nbyte is greater than 0,
		       the starting position is	before	the  end-of-file,  and
		       the  starting  position is greater than or equal	to the
		       offset maximum established in the open file description
		       associated with fildes.

       The readv() function may	fail if:

       EFAULT	       The  iov	 argument points outside the allocated address
		       space.

       EINVAL	       The iovcnt argument was less than  or  equal  to	 0  or
		       greater	than IOV_MAX. See intro(2) for a definition of
		       IOV_MAX).

		       One of the iov_len values in the	iov  array  was	 nega-
		       tive, or	the sum	of the iov_len values in the iov array
		       overflowed an ssize_t.

       The pread() function will fail and the file  pointer  remain  unchanged
       if:

       ESPIPE	       The fildes argument is associated with a	pipe or	FIFO.

USAGE
       The  pread() function has a transitional	interface for 64-bit file off-
       sets.  See lf64(5).

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |read() is	Async-Signal-Safe  |
       +-----------------------------+-----------------------------+

SEE ALSO
       intro(2), chmod(2), creat(2), dup(2),  fcntl(2),	 getmsg(2),  ioctl(2),
       lseek(2),  open(2),  pipe(2),  recv(3SOCKET),  attributes(5),  lf64(5),
       standards(5), streamio(7I), termio(7I)

SunOS 5.10			  7 May	2001			       read(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | 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+5.10>

home | help