read

read

Read Data from a File or a Socket

Portability: POSIX.1 conforming, UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <fcntl.h>

int read(int fn, void *buf, unsigned size);

The synopsis for the POSIX implementation is

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

ssize_t read(int fn, void *buf, size_t size);

DESCRIPTION

read reads data from the file or socket with file descriptor fn into the buffer addressed by buf . At most, size bytes are read. If size is 0, read returns a value of 0 and does not attempt any other operation. If fn is associated with a socket, it must either be connected or have been assigned an associated remote address by the connect function.

RETURN VALUE

read returns the number of bytes read if it is successful. A returned 0 indicates that the end of file has been reached, and a returned- 1 indicates a failure. Note that for sockets, terminal files, and USS special files, it is not an error if fewer bytes are read than requested. Also, for HFS files or sockets that have been defined as nonblocking by the fcntl function, a return value of 0 indicates that no data were immediately available and does not necessarily indicate end of file.

The remaining information in this section applies when you use read to read an USS HFS file. If read is interrupted by a signal, it returns a -1 if it has not read any data; otherwise, it returns the number of bytes read before the interruption. read returns 0 if the starting position is at or beyond the end of the file.

If read attempts to operate on an empty regular file or FIFO special file, it returns 0 if no process has the pipe open for writing. read returns -1 if a process has the pipe open for writing and O_NONBLOCK is set to 1. read does not return until data are written or until the pipe is closed by all other processes if a process has the pipe open for writing and O_NONBLOCK is set to 0.

CAUTION

read is an atomic operation. When using User Datagram Protocol (UDP), no more than one datagram can be read per call. If you are using datagram sockets, make sure there is enough buffer space to contain an incoming datagram.

EXAMPLE

This example appends a copy of an OS/390 file to itself. Because it accesses the file as binary, the appended data may not have the same record structure as the original data, depending on the file's record format.

#include <fcntl.h>
#include <lclib.h>

main()
{
   char fname[80];
   char buffer[80];
   int fd, len;
   /* position of original end of file */
   long endpos;
   /* read and write positions         */
   long rdpos, wtpos;

   puts("Enter the full name of the file to be appended to itself.");
   memcpy(fname, "//dsn:", 6);
   gets(fname+4);
   fd = open(fname, O_RDWR);
   if (fd < 0){
      puts("The file failed to open.");
      exit(EXIT_FAILURE);
   }

   /* Find end of file position. */
   endpos = lseek(fd, 0, SEEK_END);
   rdpos = 0;
   wtpos = endpos;
   for (;;) {
      /* Go to current read position. */
      lseek(fd, rdpos, SEEK_SET);
      /* Read up to 80 bytes.       */
      len = read(fd, buffer, endpos - rdpos > 80?
                 80: endpos - rdpos);

      if (len <= 0){
         puts("Input error - program terminated.");
         exit(EXIT_FAILURE);
      }
      /* Get current position.    */
      rdpos = lseek(fd, 0, SEEK_CUR);
      /* Seek to write position.  */
      lseek(fd, wtpos, SEEK_SET);
      write(fd, buffer, len);
      /* Stop when we've read     */
      /*  to end.                 */
      if (rdpos == endpos) break;
      /* Save current position.   */
      wtpos = lseek(fd, 0, SEEK_CUR);
    }
    close(fd);
    exit(EXIT_SUCCESS);
}

RELATED FUNCTIONS

fread , readv