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 ac-
       tually 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 be-
	    come 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 be-
	    comes 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 be-
       tween 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_SR-
       DOPT  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 un-
       til  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  re-
       moved 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 ac-
       tion  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=readv&sektion=2&manpath=SunOS+5.10>

home | help