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

FreeBSD Manual Pages


home | help
read(2)								       read(2)

       read, readv - read from a file

       cc = read(d, buf, nbytes)
       int cc, d;
       char *buf;
       int nbytes;

       #include	<sys/types.h>
       #include	<sys/uio.h>

       cc = readv(d, iov, iovcnt)
       int cc, d;
       struct iovec *iov;
       int iovcnt;

       d	 File descriptor.

       buf	 Character pointer where information is	stored.

       nbytes	 Integer that tells you	how many bytes to read.

       iov	 Pointer to an iovec structure.

       iovcnt	 The number of iovec structures	to be processed.

       The  system call	attempts to read nbytes	of data	from the object	refer-
       enced by	the descriptor d into the buffer pointed to by buf.  The  sys-
       tem call	performs the same action, but scatters the input data into the
       iovcnt buffers specified	by the members of the iovec  following	array:
       iov[0], iov[1], ..., iov[iovcnt-1].

       For the iovec structure is defined as follows:

       struct iovec {	   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	system call fills an area com-
       pletely before proceeding to the	next area.

       On  objects that	are capable of seeking,	the starts at a	position given
       by the pointer associated with d.   See	for  more  information.	  Upon
       return  from the	pointer	is incremented by the number of	bytes actually

       Objects that are	not capable of seeking always read  from  the  current
       position.   The	value of the pointer associated	with such an object is

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

       o    If no process has the pipe open for	writing, returns zero to indi-
	    cate end-of-file.

       o    If	some  process  has  the	 pipe open for writing and O_NDELAY or
	    O_NONBLOCK is set, returns a -1, errno is  to  [EWOULDBLOCK].   If
	    some process has the pipe open for writing and O_NDELAY and	O_NON-
	    BLOCK are clear, blocks until data	is  written  or	 the  pipe  is
	    closed by all processes that opened	the pipe for writing.

       Upon  successful	 completion,  and  return the number of	bytes actually
       read and	placed in the buffer.  The system reads	the  number  of	 bytes
       requested if the	descriptor references a	file which has that many bytes
       left before the end-of-file; this is not	true in	any other instance.

       Unless the SV_INTERRUPT bit has been set	for a signal, the system calls
       are  automatically  restarted  when  a  process receives	a signal while
       waiting for input. See also

Return Values
       If the returned value is	0, then	end-of-file has	been reached.

       If the read is  successful,  the	 number	 of  bytes  actually  read  is
       returned.  Otherwise, a -1 is returned and the global variable errno is
       set to indicate the error.

       The and system calls fail if one	or more	of the following are true:

       [EBADF]	      The d argument is	not a valid file or socket  descriptor
		      open for reading.

       [EFAULT]	      The buf points outside the allocated address space.

       [EINTR]	      A	 read  from  a	slow device was	interrupted before any
		      data arrived by the delivery of a	signal.

       [EIO]	      An I/O error occurred while reading from the  file  sys-

       [ESTALE]	      The  file	 handle	 given in the argument is invalid. The
		      file referred to by that file handle no longer exists or
		      has been revoked.

       [EWOULDBLOCK]  The  O_DELAY  or	O_NONBLOCK  flag  is  set for the file
		      descriptor and the process would be delayed in the  read

       In addition, may	return one of the following errors:

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

       [EINVAL]	      One of the iov_len values	in the iov array was negative.

       [EINVAL]	      The  sum	of  the	 iov_len values	in the iov array over-
		      flowed a 32-bit integer.

       [EFAULT]	      Part of the iov points outside the  process's  allocated
		      address space.

       [ETIMEDOUT]    A	 connect  request  or  remote  file  operation	failed
		      because the connected party  did	not  respond  after  a
		      period  of  time determined by the communications	proto-


       When you	use the	System V environment, note the following:

       o    If your program is compiled	in this	environment, a and system call
	    returns 0 if the file has been set up for non-blocking I/O and the
	    read would block.

       o    In this environment, the parameter nbytes is of type  int  instead
	    of type unsigned.


       In  the	POSIX  environment,  [EAGAIN]  is returned in errno instead of

See Also
       dup(2), open(2),	pipe(2), sigvec(2), socket(2), socketpair(2)


Name | Syntax | Arguments | Description | Return Values | Diagnostics | Environment | See Also

Want to link to this manual page? Use this URL:

home | help