CONTENTS | INDEX | PREV | NEXT

 read

 NAME
  read  - read data from a file

 SYNOPSIS
  int r = read(fd, buf, bytes);
  int fd;
  void *buf;
  int bytes;

 FUNCTION
  read data from a file starting at the current seek position.  read
  returns the number of bytes read or -1 if a read error occurs.

  With normal files, read will always return the number of bytes
  requested until the end of file is reached, in which case read
  may return fewer than the number of bytes requested.  If at the
  end of a file, read will return 0.

  With devices read may or may not return the number of bytes
  requested depending on the device.

 NOTE
  refer to the file_descriptor manual page for general information

  Unlike file pointers and file handles, the file descriptor is
  checked for validity and will simply return an error if illegal.

 EXAMPLE
  #include <fcntl.h>
  #include <assert.h>

  main()
  {
      int fd;
      int r;
      char buf[32];

      fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
      assert(fd >= 0);
      write(fd, "FuBarn", 6);
      close(fd);

      fd = open("T:xx", O_RDONLY);
      assert(fd >= 0);
      r = read(fd, buf, sizeof(buf));     /*  sizeof(buf) == 32   */
      close(fd);
      assert(r == 6);

      /*
       *  note that the buffer is not terminated with a nul, but since
       *  we are using write() which requires a length it does not matter
       */

      write(1, buf, r);
  }

 INPUTS
  int fd;     file descriptor to read from
  void *buf;  pointer to buffer to read data into
  int len;    maximum number of bytes to read

 RESULTS
  int r;      number of bytes actually read (could be less than
          len or 0), or < 0 if error.