gtpc2m5mC/C++ Language Support User's Guide

read-Read from a File

This function reads from a file.

Note

This description applies only to files. See TPF Transmission Control Protocol/Internet Protocol for more information about the read function for sockets.

TPF deviation from POSIX

The TPF system does not support the atime (access time) time stamp.

Format

#include <unistd.h>
ssize_t read(int fildes, void *buf, size_t N);

fildes
The file descriptor.

buf
The buffer or memory area.

N
The number of bytes of data to be read.

From the file indicated by file descriptor fildes, the read function reads N bytes of input into the memory area indicated by buf.

If fildes refers to a regular file or any other type of file on which the process can seek, the read function begins reading at the file offset associated with fildes. If successful, the read function changes the file offset by the number of bytes read. N should not be greater than INT_MAX (defined in the limits.h header file).

If fildes refers to a file on which the process cannot seek, read begins reading at the current position. There is no file offset associated with such a file.

Normal Return

If successful, read returns the number of bytes that are actually read and placed in buf, equal to the number of bytes requested (N).

The return value is less than N only if:

If the starting position for the read operation is at the end of the file or beyond, read returns a 0 value.

If the read function is reading a regular file and finds a part of the file that has not been written (but before the end of the file), read places 0 bytes into buf in place of the unwritten bytes.

If a read function is attempted on an empty FIFO special file and no process has opened the file for writing, the read function returns a value of 0 to indicate the end of the file. When the buffer for a FIFO special file becomes full, the writer is blocked until enough data is removed from the file with a read function to allow the write function to be completed.

If the number of bytes of input that you want to read is 0, the read function simply returns a value of 0 without attempting any other action.

Error Return

If the read function fails, it returns a value of -1 and sets errno to one of the following:

EAGAIN
O_NONBLOCK is set to 1 but data was not available for reading.

EBADF
fildes is not a valid open file descriptor.

EINTR
A signal interrupted read function processing before any data was available.

EINVAL
N contains a value that is less than 0, or the request is not valid or not supported.

Programming Considerations

None.

Examples

The following example opens a file and reads input.

#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
 
main() {
  int ret, fd;
  char buf[1024];
 
  if ((fd = open("my.data", O_RDONLY)) < 0)
    perror("open() error");
  else {
    while ((ret = read(fd, buf, sizeof(buf)-1)) > 0) {
      buf[ret] = 0x00;
      printf("block read: \n<%s>\n", buf);
    }
    close(fd);
  }
}

Output

block read:
<ask dad;
sad lad ask dad fad daf lak;
jasf dasd fall slaj fask slak flak;
flask skald salsa slkja dsalk fjakl;
fadjak lakkad skalla aladja kfslsa;
>

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.