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

FreeBSD Manual Pages

  
 
  

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

NAME
       read, readv, pread - read from file

SYNOPSIS
DESCRIPTION
       The function attempts to	read nbyte bytes from the file associated with
       the open	file descriptor, fildes, into the buffer pointed to by buf.

       If nbyte	is 0, will return 0 and	have no	other results.

       On files	that support seeking (for example, a regular file), the	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.

       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
       requests	is implementation-dependent.

       If the value of nbyte is	greater	than the result	is  implementation-de-
       pendent.

       When attempting to read from an empty pipe or FIFO:

	      o	 If no process has the pipe open for writing, will return 0 to
		 indicate end-of-file.

	      o	 If some process has the pipe open for	writing	 and  is  set,
		 will return -1	and set	to

	      o	 If  some  process has the pipe	open for writing and is	clear,
		 will block until some data is written or the pipe  is	closed
		 by all	processes that had the pipe open for writing.

       When  attempting	 to  read a file (other	than a pipe or FIFO) that sup-
       ports non-blocking reads	and has	no data	currently available:

	      o	 If is set, will return	a -1 and set to

	      o	 If is clear, will block until some data becomes available.

	      o	 The use of the	flag has no  effect  if	 there	is  some  data
		 available.

       The function reads data previously written to a file. If	any portion of
       a regular file prior to the end-of-file has not been  written,  returns
       bytes  with  value 0. For example, allows the file offset to be set be-
       yond 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.

       Upon  successful	 completion,  where nbyte is greater than 0, 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 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 from a file as-
       sociated	with a terminal	may return one typed line of data.

       If a is interrupted by a	signal before it reads any data, it  will  re-
       turn -1 with set	to

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

       A from a	file can read data in three different modes: byte-stream mode,
       message-ondiscard  mode,	 and  message-discard  mode.  The  default  is
       byte-stream mode. This can be changed using the	request,  and  can  be
       tested  with  the In byte-stream	mode, retrieves	data from the 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  message-nondiscard mode, retrieves data until as many bytes as were
       requested are transferred, or until a message boundary is  reached.  If
       does not	retrieve all the data in a message, the	remaining data is left
       on the and can be retrieved by the next 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 returns is discarded, and is	not  available	for  a
       subsequent or call.

       How handles zero-byte messages is determined by the current  read  mode
       setting.	 In  byte-stream  mode,	 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 function then returns the number of
       bytes read, and places the zero-byte message back  on  the  to  be  re-
       trieved	by  the	 next or In message-nondiscard mode or message-discard
       mode, a zero-byte message returns 0 and the message is removed from the
       When  a zero-byte message is read as the	first message on a the message
       is removed from the and 0 is returned, regardless of the	read mode.

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

       By default, are in control-normal mode, in which	a from a file can only
       process messages	that contain a data part but do	not contain a  control
       part.  The  fails if a message containing a control part	is encountered
       at the head. This default action	can be changed by placing the  in  ei-
       ther  control-data  mode	 or  control-discard mode with the command. In
       control-data mode, 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, discards message	control	 parts
       but returns to the process any data part	in the message.

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

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

       Each iovec entry	specifies the base address and length of  an  area  in
       memory  where  data should be placed. The function always fills an area
       completely before proceeding to the next.

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

       The  function  performs	the same action	as except that it reads	from a
       given position in the file without  changing  the  file	pointer.   The
       first  three arguments of are the same as with the addition of a	fourth
       argument	for the	desired	position inside	the file.  An attempt to  per-
       form a on a file	that is	incapable of seeking results in	an error.

RETURN VALUE
       Upon  successful	completion, and	return a non-negative integer indicat-
       ing the number of bytes actually	read. Otherwise, the functions	return
       -1 and set to indicate the error.

ERRORS
       The and functions will fail if:

	      [EAGAIN]	     The  flag	is set for the file descriptor and the
			     process would be delayed in or

	      [EBADF]	     The fildes	argument is not	a valid	file  descrip-
			     tor open for reading.

	      [EBADMSG]	     The  file is a file that is set to	control-normal
			     mode and the message waiting to be	read  includes
			     a control part.

	      [EINTR]	     The  read operation was terminated	due to the re-
			     ceipt of a	signal,	and no data was	transferred.

	      [EINVAL]	     The starting file offset associated  with	fildes
			     is	greater	than the maximum supported file	size.

	      [EINVAL]	     The or multiplexer	referenced by fildes is	linked
			     (directly or indirectly) downstream from a	multi-
			     plexer.

	      [EIO]	     A physical	I/O error has occurred.

	      [EIO]	     The  process  is a	member of a background process
			     attempting	to read	from its  controlling	termi-
			     nal, the process is ignoring or blocking the sig-
			     nal or the	process	group is orphaned. This	 error
			     may  also	be generated for implementation-depen-
			     dent reasons.

	      [EISDIR]	     The fildes	argument refers	to a directory and the
			     implementation does not allow the directory to be
			     read using	or The function	 should	 be  used  in-
			     stead.

       The function will fail if:

	      [EINVAL]	     The  sum  of  the iov_len values in the iov array
			     overflowed	an ssize_t.

       The and functions may fail if:

	      [ENXIO]	     A request was made	of a non-existent  device,  or
			     the  request  was outside the capabilities	of the
			     device.

       The function may	fail if:

	      [EINVAL]	     The argument was less than	 or  equal  to	0,  or
			     greater than

       The function will fail and the file pointer remains unchanged if:

	      [EINVAL]	     The  offset  argument  is	invalid.  The value is
			     negative.

	      [EOVERFLOW]    The file is a regular file	 and  an  attempt  was
			     made  to read at or beyond	the offset maximum as-
			     sociated with the file.

	      [ESPIPE]	     fildes is associated with a pipe or FIFO.

SEE ALSO
       fcntl(2),   ioctl(2),   lseek(2),   open(2),   pipe(2),	  <stropts.h>,
       <sys/uio.h>, <unistd.h>,	XBD Specification, Chapter 9, General Terminal
       Interface.

CHANGE HISTORY
       First released in Issue 1.  Derived from	Issue 1	of the SVID.

Issue 4
       The following changes are  incorporated	for  alignment	with  the  ISO
       POSIX-1 standard:

	      o	 The type of the argument buf is changed from char * to	void*,
		 and the type of the argument nbyte is changed	from  unsigned
		 to size_t.

	      o	 The  DESCRIPTION section now states that the result is	imple-
		 mentation-dependent if	nbyte is greater than This  limit  was
		 defined by the	constant in Issue 3.

       The  following  change  is incorporated for alignment with the FIPS re-
       quirements:

	      o	 The last paragraph of the DESCRIPTION section now states that
		 if  is	interrupted by a signal	after it has successfully read
		 some data, it will return the number of bytes read.  In Issue
		 3  it was optional whether returned the number	of bytes read,
		 or whether it returned	-1 with	set to

       Other changes are incorporated as follows:

	      o	 The header is added to	the SYNOPSIS section.

	      o	 The section is	rearranged  for	 clarity  and  to  align  more
		 closely  with the ISO POSIX-1 standard. No functional changes
		 are  made other than as noted elsewhere in this section.

	      o	 In the	ERRORS section in previous issues, generation  of  the
		 error	depended on whether or not an implementation supported
		 Job Control. This functionality is now	defined	as mandatory.

	      o	 The error is marked as	an extension.

	      o	 The APPLICATION USAGE section is removed.

	      o	 The description of is amended.

Issue 4, Version 2
       The following changes are incorporated for X/OPEN UNIX conformance:

	      o	 The function is added to the SYNOPSIS.

	      o	 The DESCRIPTION is updated to describe	the  reading  of  data
		 from  files.  An  operational	description of the function is
		 also added.

	      o	 References to the function are	added to the RETURN VALUE  and
		 ERRORS	sections in appropriate	places.

	      o	 The  ERRORS  section has been restructured to describe	errors
		 that apply generally (that is,	to both	and  and  to  describe
		 those	that  apply  to	 specifically. The and errors are also
		 added.

read(2)			      System Calls Manual		       read(2)

				  HP-UX	EXTENSIONS

DESCRIPTION
       For the structure is defined in

       For ordinary files, if the file status flag is set, the calling process
       blocks  until  the  data	being read and all file	attributes required to
       retrieve	the data are the same as their image on	disk.  Writes  pending
       on  the	data  to  be read are executed before returning	to the calling
       process.	 If the	file status flag is set, the behavior is identical  to
       that  for  with	this addition: all file	attributes changed by the read
       operation (including access time, modification time and	status	change
       time)  must also	be the same as their image on disk.  For block special
       files, if either	the or status flag is set, the calling process	blocks
       until  the data being read is an	image of the data on the disk.	Writes
       pending on the data to be read are executed  before  returning  to  the
       calling process.

       When  attempting	to read	from a regular file with enforcement-mode file
       and record locking set (see chmod(2)), and the segment of the  file  to
       be read is blocked by a write lock owned	by another process, the	behav-
       ior is determined by the	and file status	flags:

	      o	 If or is set, returns -1 and is set to	[EAGAIN].

	      o	 If and	are clear, does	not return until  the  blocking	 write
		 lock is removed.

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

	      o	 If no process has the pipe open for writing, the read returns
		 a 0.

	      o	 If some process has the pipe open for writing and is set, the
		 read returns -1 and is	set to [EAGAIN].

	      o	 If is set, the	read returns a 0.

	      o	 If  some  process  has	 the pipe open for writing and and are
		 clear,	the read blocks	until data is written to the  file  or
		 the file is no	longer open for	writing.

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

	      o	 If is set, the	read returns 0.

	      o	 If and	are clear, the read blocks until data  becomes	avail-
		 able.

RETURN VALUE
       Upon  successful	 completion, returns the number	of bytes actually read
       and placed in the buffer; this number may be less than nbyte if:

	      o	 The  file  is	associated  with  a  communication  line  (see
		 ioctl(2) and termio(7)), or

	      o	 The  number  of  bytes	 left  in  the file is less than nbyte
		 bytes.

	      o	 was interrupted by a signal after it  had  successfully  read
		 some, but not all of the data requested.

       When an end-of-file is reached, a value of 0 is returned.  Otherwise, a
       -1 is returned and is set to indicate the error.

ERRORS
       fails if	any of the following conditions	are encountered:

	      [EBADF]	     fildes is not a valid file	 descriptor  open  for
			     reading.

	      [EINTR]	     A	signal	was  caught before any data was	trans-
			     ferred (see sigvector(2)).

	      [EAGAIN]	     Enforcement-mode file and record locking is  set,
			     or	is set,	and there is a blocking	write lock.

	      [EDEADLK]	     A	resource  deadlock  would occur	as a result of
			     this operation (see lockf(2) and fcntl(2)).

	      [EFAULT]	     buf points	outside	the allocated  address	space.
			     Reliable  detection  of this error	is implementa-
			     tion dependent.

	      [ENOLCK]	     The system	record lock table is full,  preventing
			     the  read	from sleeping until the	blocking write
			     lock is removed.

       In addition, can	return one of the following errors:

	      [EFAULT]	     iov_base or iov points outside of	the  allocated
			     address  space.   The  reliable detection of this
			     error is implementation-dependent.

EXAMPLES
       Assuming	a process opened a file	for reading,  the  following  call  to
       read(2) reads bytes from	the file into the buffer pointed to by mybuf:

WARNINGS
       Record  locking	might  not be enforced by the system, depending	on the
       setting of the file's mode bits (see lockf(2)).

       Character-special devices, and raw  disks  in  particular,  apply  con-
       straints	 on how	can be used.  See the specific Section (7) entries for
       details on particular devices.

       Check all references to signal(5) for appropriateness on	 systems  that
       support sigvector(2).  can affect the behavior described	on this	page.

       In general, avoid using to get the contents of a	directory; use the li-
       brary routine (see directory(3C)).

DEPENDENCIES
   NFS
       When obtaining the contents of a	directory on an	NFS file  system,  the
       library	routine	must be	used (see directory(3C)).  returns with	an er-
       ror if used to read a directory using NFS.

AUTHOR
       was developed by	HP, AT&T, and the University of	California, Berkeley.

SEE ALSO
       creat(2), dup(2), fcntl(2), ioctl(2), lockf(2), open(2),	 pipe(2),  se-
       lect(2),	ustat(2), directory(3C), tty(7).

STANDARDS CONFORMANCE
								       read(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | SEE ALSO | CHANGE HISTORY | Issue 4 | Issue 4, Version 2 | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | WARNINGS | DEPENDENCIES | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

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

home | help