unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



read(2)								      read(2)



NAME

  read,	pread, readv - Read from a file.

SYNOPSIS

  #include <&lt;unistd.h>&gt;

  ssize_t read(
	  int filedes,
	  void *buffer,
	  size_t nbytes);

  ssize_t pread(
	  int filedes,
	  void *buffer,
	  size_t nbytes);
	  off_t	offset);

  #include <&lt;sys/uio.h>&gt;

  ssize_t readv(
	  int filedes,
	  const	struct iovec *iov,
	  int iov_count);

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  read():  XSH4.2, XNS5.0

  pread():  POSIX.1c

  readv():  XSH4.2, XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  filedes   Identifies the file	from which data	is read.

  buffer    Points to the buffer to receive data that is being read.

  nbytes    Specifies the number of bytes to read from the file	associated
	    with the filedes parameter.

  offset    Specifies the desired start	position inside	the file associated
	    with the filedes parameter.

  iov	    Points to an array of iovec	structures that	identifies the
	    buffers into which the data	is to be placed. The iovec structure
	    is defined in the sys/uio.h	header file and	contains the follow-
	    ing	members:


		    void *iov_base;
		    size_t iov_len;

  iov_count Specifies the number of iovec structures pointed to	by the iov
	    parameter.

DESCRIPTION

  The read() function attempts to read nbytes of data from the file associ-
  ated with the	filedes	parameter into the buffer pointed to by	the buffer
  parameter.

  If the value of nbytes is 0 (zero), the read() function returns 0 and	has
  no other results.

  [XNS5.0]  If filedes refers to a socket, a read() request is equivalent to
  a recv() request with	no flags set.

  The pread() function performs	the same action	as read(), except that it
  reads	from a given position in the file (specified by	the offset parameter)
  without changing the file pointer.  The first	three arguments	to pread are
  the same as a	read, the fourth argument to pread, offset, specifies the
  desired position inside the file.  An	attempt	to perform a pread() on	a
  file that is incapable of seeking results in an error.

  The readv() function performs	the same action	as the read() function,	but
  scatters the input data into the buffers specified by	the array of iovec
  structures pointed to	by the iov parameter.  The iov_count parameter speci-
  fies the number of buffers pointed to	by the iov parameter.  Each iovec
  entry	specifies the base address and length of an area in memory where data
  should be placed. The	iovcount parameter is valid if greater than 0 (zero)
  and less than	or equal to IOV_MAX, which is defined in the sys/limits.h
  header file.	The readv() function always fills an area completely before
  proceeding to	the next.

  On regular files and devices capable of seeking, the read() function starts
  at a position	in the file given by the file pointer associated with the
  filedes parameter. Upon return from the read() function, the file pointer
  is incremented by the	number of bytes	actually read.

  Devices that are incapable of	seeking	(for example, terminals) always	read
  from the current position. The value of a file pointer 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 (zero) is returned.

  When attempting to read from an empty	pipe (FIFO) the	read() and pread()
  functions behave as follows:

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

    +  If some process has the pipe open for writing and O_NONBLOCK is set,
       the function returns a value of -1 and sets errno to [EAGAIN].

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

    +  [Tru64 UNIX]  If	some process has the pipe open for writing and
       O_NDELAY	is set,	the function returns a value of	-1 and sets errno to
       [EAGAIN].

    +  [Tru64 UNIX]  If	some process has the pipe open for writing and
       O_NDELAY	is clear, the function will block until	some data is written
       or the pipe is closed by	all processes that opened the pipe for
       writing.

  When attempting to read a file (other	than a pipe) that supports nonblock-
  ing reads and	has no data currently available, the read() and	pread()	func-
  tions	behave as follows:

    +  If O_NONBLOCK is	set, the function returns -1 and sets errno to
       [EAGAIN].

    +  If O_NONBLOCK is	clear, the function will block until data becomes
       available.

    +  [Tru64 UNIX]  If	O_NDELAY is set	and the	file is	a serial device, the
       function	returns	-1 and sets errno to [EAGAIN].

    +  [Tru64 UNIX]  If	O_NDELAY is set	and the	file is	a STREAMS device, the
       function	returns	0 and sets errno to 0.

    +  [Tru64 UNIX]  If	O_NDELAY is clear, the function	will block until data
       becomes available.

    +  [Tru64 UNIX]  If	both O_NDELAY and O_NONBLOCK are set and the file is
       a STREAMS device, the function returns -1 and sets errno	to [EAGAIN].
       The behavior of O_NONBLOCK takes	precedence over	the behavior of
       O_NDELAY.

  [Tru64 UNIX]	The use	of the O_NONBLOCK flag has no effect if	there is some
  data available.

  [Tru64 UNIX]	When attempting	to read	from a regular file with enforcement
  mode record locking enabled and all or part of the region to be read is
  currently locked by another process (a write lock or exclusive lock),	the
  read() and pread() functions behave as follows:

    +  If O_NDELAY and O_NONBLOCK are clear, the function blocks the calling
       process until the lock is released, or the function is terminated by a
       signal.

    +  If O_NDELAY or O_NONBLOCK  is set, the function returns -1 and sets
       errno to	[EAGAIN].

  The read() and pread() functions read	data previously	written	to a file.
  If any portion of a regular file prior to the	end-of-file has	not been
  written, the function	returns	bytes with value 0 (zero).

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

  [Tru64 UNIX]	For AdvFS or UFS files that are	mounted	with the mount -o
  flag option noatimes,	file access time changes are made in memory, but are
  not flushed to disk until other file modifications occur.  This behavior
  can improve server response time by decreasing the number of disk I/O
  operations.  However,	the behavior violates POSIX standards and jeopardizes
  the integrity	of file	access times.  See mount(8) for	more information
  about	the mount -o flag option noatimes.

  If a read() or pread() function is interrupted by a signal before it reads
  any data, it returns -1 with errno set to [EINTR].

  If a read() or pread() function is interrupted by a signal after it has
  successfully read some data, it returns the number of	bytes read.

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

  Reading Data From STREAMS Files

  [XSH4.2]  A read() or	pread()	from a STREAMS file can	operate	in three dif-
  ferent 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() request (see the	streamio(7) reference page) and	can
  be tested with the I_GRDOPT ioctl().	In byte-stream mode, read() or
  pread() retrieves data from the STREAM until it has retrieved	nbytes bytes
  or until there is no more data to be retrieved.  Byte-stream mode ignores
  message boundaries.

  [XSH4.2]   In	STREAMS	message-nondiscard mode, read()	or pread() retrieves
  data until it	has read nbytes	bytes or until it reaches a message boundary.
  If the read()	or pread() does	not retrieve all the data in a message,	the
  remaining data are replaced on the STREAM and	can be retrieved by the	next
  read(), pread(), or getmsg() call.  Message-discard mode also	retrieves
  data until it	has retrieved nbytes bytes or until it reaches a message
  boundary.  However, unread data remaining in a message after the read() or
  pread() returns is discarded and is not available for	a subsequent read(),
  pread(), readv(), or getmsg()	call.

  [XSH4.2]   When reading from a STREAMS file, handling	of zero-byte messages
  is determined	by the current read mode setting.  In byte-stream mode,
  read() or pread() accepts data until it has read nbytes bytes, until there
  is no	more data to read, or until a zero-byte	message	block is encountered.
  The read() or	pread()	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(), pread(), or getmsg() call.  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.

  [XSH4.2]  A read() or	pread()	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.

  [XSH4.2]  By default,	STREAMS	are in control-normal mode, in which a read()
  or pread() from a STREAMS file can only process data messages	that contain
  a data part but do not contain a control part.  The read() or	pread()	fails
  if a message containing 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() com-
  mand.	 In control-data mode read() or	pread()	converts any control part to
  data and passes it to	the application	before passing any data	part origi-
  nally	present	in the same message. In	control-discard	mode, read() or
  pread() discards message control parts but returns, to the process, any
  data part in the message.

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

NOTES

  [Tru64 UNIX]	For compatibility with earlier releases, values	for iov_len
  that are greater than	or equal to 2^63 will be treated as zero.

  [Tru64 UNIX]	The read(), pread(), and readv() functions, which suspend the
  calling process until	the request is completed, are redefined	so that	only
  the calling thread is	suspended.

  [Tru64 UNIX]	When debugging a module	that includes the readv() function,
  use _Ereadv to refer to the readv() call.

  When a read(), pread(), write(), or pwrite() system call on a	pipe is
  interrupted by a signal and no bytes have been transferred through the
  pipe,	a value	of -1 is returned and errno is set to [EINTR].	This behavior
  is different from previous releases in which both read() and write() either
  restarted the	transfer or set	errno to [EINTR], depending on the setting of
  the SA_RESTART flag for the interrupting signal.

  As a result of this change, applications must	now either handle the [EINTR]
  return or block any expected signals for the duration	of the read(),
  pread(), write(), or pwrite()	operation.

RETURN VALUES

  Upon successful completion, the read(), pread(), and readv() functions
  return the number of bytes actually read and placed into buffers.

  The system guarantees	to read	the number of bytes requested only if the
  descriptor references	a regular file that has	the same number	of bytes left
  before the end-of-file.

  If the read(), pread(), and readv() functions	fail, a	value of -1 is
  returned, errno is set to indicate the error,	and the	content	of the buffer
  pointed to by	the buffer parameter is	indeterminate.

  End-of-Media Handling	for Tapes

  If reading goes beyond the "early warning" EOT indicator while this indica-
  tor is disabled, the read(), pread(),	and readv() functions will return the
  number of bytes actually read	and placed into	the buffer.  The read(),
  pread(), and readv() functions return	a value	of -1, if:

    +  Attempting to read past the "real" EOT.

    +  Attempting to read past "early warning" EOT indicator while this	indi-
       cator is	enabled.

  Refer	to mtio(7) for information on enabling and disabling "early warning"
  EOT.

  End-of-Media Handling	for Disks

  Disk end-of-media handling is	POSIX-conformant.  Attempting to read at or
  beyond the end of a partition	returns	a value	of 0.  A partial read returns
  the number of	bytes actually read.

  Note:	 A partial read	is a request that spans	the end	of a partition.

ERRORS

  The read(), pread(), and readv() functions set errno to the specified
  values for the following conditions:


  [EAGAIN]  The	O_NONBLOCK flag	is set on this file and	the process would be
	    delayed in the read(), pread(), or readv() operation.

	    [Tru64 UNIX]  No message is	waiting	to be read on a	STREAM and
	    the	O_NDELAY or O_NONBLOCK flag is set.

	    [Tru64 UNIX]  An enforcement mode record lock is outstanding in
	    the	portion	of the file that is to be read.

  [EBADF]   The	filedes	parameter is not a valid file descriptor open for
	    reading.

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

	    [Tru64 UNIX]  The message waiting to be read on a STREAM is	not a
	    data message system	call.

	    [Tru64 UNIX]  The message that is waiting to be read is not	a
	    data message.

  [EDEADLK] [Tru64 UNIX]  Enforcement mode file	locking	is enabled, O_NDELAY
	    and	O_NONBLOCK are clear, and a deadlock condition is detected.

  [EFAULT]  [Tru64 UNIX]  The buffer or	part of	 the iov points	to a location
	    outside the	allocated address space	of the process.

  [EINTR]   A read on a	pipe (FIFO) is interrupted by a	signal and no bytes
	    have been transferred through the pipe.

  [EINVAL]  [XSH4.2]  The STREAM or multiplexer	referenced by filedes is
	    linked (directly or	indirectly) downstream from a multiplexer.

	    [XSH4.2]  The sum of the iov_len values in the iov array over-
	    flowed an ssize_t.

	    [XSH4.2]  The value	of the iovcount	parameter was less than	or
	    equal to 0,	or greater than	IOV_MAX.

	    [Tru64 UNIX]  The file position pointer associated with the
	    filedes parameter was negative.

	    [Tru64 UNIX]  The sum of the iov_len values	in the iov array was
	    negative or	overflowed a 32-bit integer.

	    [Tru64 UNIX]  The requested	operation attempted to read from a
	    STREAM linked to a multiplexer.

  [EIO]	    [XSH4.2]  A	physical I/O error occurred.

	    The	process	is a member of a background process attempting to
	    read from its controlling terminal,	the process is ignoring	or
	    blocking the SIGTTIN signal, or the	process	group is orphaned.

  [ENOLCK]  [Tru64 UNIX]  The file has enforcement mode	file locking set and
	    allocating another locked region would exceed the configurable
	    system limit of NLOCK_RECORD.

  [ENOSPC]  [Tru64 UNIX]  An attempt was made to read past the "early warn-
	    ing" EOT while this	indicator was enabled.

  [ENXIO]   The	device specified by the	file descriptor	parameter filedes is
	    a block special character or a character special file, and the
	    file pointer value is out of range.


  In addition, the pread() function fails and the file pointer remains
  unchanged if the following is	true:

  [ESPIPE]  The	file specified by filedes is associated	with a pipe (FIFO).


  For NFS file access, if the read() or	pread()	function fails,	errno may
  also be set to one of	the following values:

  [EBADRPC] [Tru64 UNIX]  Indicates that the client has	requested more data
	    than the server agreed to provide.

  [EFBIG]   [Tru64 UNIX]  For filesystems mounted with the nfsv2 option, the
	    process attempted to read beyond the 2 gigabyte boundary.

  [EISDIR]  [Tru64 UNIX]  Indicates either that	the request for	write access
	    to a file specified	a directory name instead of a filename,	or
	    that the function was trying to rename a directory as a file.

  [ENFILE]  [Tru64 UNIX]  Indicates either that	the system file	table is full
	    or that too	many files are currently open in the system.

  [ENOBUFS] [Tru64 UNIX]  Indicates insufficient resources, such as buffers,
	    to complete	the call. Typically, a call used with sockets has
	    failed due to a shortage of	message	or send/receive	buffer space.

  [ESTALE]  [Tru64 UNIX]  Indicates a stale NFS	file handle. An	opened file
	    was	deleted	by the server or another client, a client cannot open
	    a file because the server has unmounted or unexported the remote
	    directory, or the directory	that contains an opened	file was
	    either unmounted or	unexported by the server.

RELATED	INFORMATION

  Functions: fcntl(2), creat(2), dup(2), ioctl(2), mtio(7), open(2), pipe(2),
  poll(2), socket(2), socketpair(2), termios(4), streamio(7), opendir(3)
  lockf(3)

  Standards: standards(5)