read man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

read(2)								       read(2)

NAME
       read, pread, readv - read from a file

SYNOPSIS
       #include <unistd.h>

       ssize_t read(
	       int filedes,
	       void *buffer,
	       size_t nbytes ); ssize_t pread(
	       int filedes,
	       void *buffer,
	       size_t nbytes,
	       off_t offset) ); #include <sys/uio.h>

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

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       read():	XSH4.0, XSH4.2, XNS5.0

       pread():	 POSIX.1, XSH5.0

       readv():	 XSH4.2, XNS5.0

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

PARAMETERS
       Identifies  the	file from which data is read.  Points to the buffer to
       receive data that is being read.	 Specifies the number of bytes to read
       from  the  file	associated  with the filedes parameter.	 Specifies the
       desired start position inside the file associated with the

       filedes parameter.  Points to an array of iovec structures that identi‐
       fies  the buffers into which the data is to be placed. The iovec struc‐
       ture is defined in the <sys/uio.h> header file and contains the follow‐
       ing members:

	      void  *iov_base;	size_t	iov_len; 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 asso‐
       ciated  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 param‐
       eter) without changing the file pointer. The first three	 arguments  to
       pread()	are  the  same	as for 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 parame‐
       ter  specifies  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 iov_count 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 start‐
       ing 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  non‐
       blocking	 reads	and  has  no  data currently available, the read() and
       pread() functions 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 enforce‐
       ment 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 inter‐
       rupted 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 associated with a terminal may return one
       typed line of data.

       [Tru64 UNIX]  For AdvFS or UFS files that are mounted with the -o noat‐
       imes option of the mount command, 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 -o noatimes option.

       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
       Function behavior discussed in this section is defined for  compilation
       environments that support XSH4.2 and higher revisions of the XSH speci‐
       fication.

       A read() or pread() from a STREAMS file 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()  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.

       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.

       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.

       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.

       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()	request.  In  control-data mode read() or pread() 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-dis‐
       card mode,  read()  or  pread()	discards  message  control  parts  but
       returns, to the process, any data part in the message.

       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() func‐
       tion, 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],  depend‐
       ing 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
       indicator  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 indicator is enabled.

       Refer to mtio(7) for information on enabling and disabling “early warn‐
       ing” 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.	 Note  that  conditions marked
       [XSH4.2]	  apply to compilation environments that  support  XSH4.2  and
       higher versions of the XSH specification.

       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.  The filedes parame‐
	      ter   is	 not   a  valid	 file  descriptor  open	 for  reading.
	      [XSH4.2]	The file is a STREAM file that is set to  control-nor‐
	      mal  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.  [Tru64 UNIX]  Enforcement mode  file  locking  is
	      enabled,	O_NDELAY and O_NONBLOCK are clear, and a deadlock con‐
	      dition is detected.  [Tru64 UNIX]	 The buffer or part of the iov
	      value  points  to a location outside the allocated address space
	      of the process.  A read on a pipe (FIFO)	is  interrupted	 by  a
	      signal  and  no  bytes  have  been transferred through the pipe.
	      [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 buffer.

	      [XSH4.2]	The value of the iov_count 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.  [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.
	      [Tru64 UNIX]  The file has enforcement mode file locking set and
	      allocating  another  locked region would exceed the configurable
	      system limit of NLOCK_RECORD.  [Tru64 UNIX]  An attempt was made
	      to  read	past  the “early warning” EOT while this indicator was
	      enabled.	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: 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: [Tru64 UNIX]  Indicates
       that the client has requested more data than the server agreed to  pro‐
       vide.   [Tru64 UNIX]  For file systems mounted with the mount command's
       -o nfsv2 option, the process attempted to read beyond  the  2  gigabyte
       boundary.  For an NFS client,

       fildes  identifies  a directory that resides on an NFS server.  In this
       case, the application must use readdir() or getdirentries() to read the
       directory.   [Tru64  UNIX]  Indicates either that the system file table
       is full or that too many	 files	are  currently	open  in  the  system.
       [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.	[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	direc‐
       tory that contains an opened file was either unmounted or unexported by
       the server.

SEE ALSO
       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)

								       read(2)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net