gtpc2m5m | C/C++ Language Support User's Guide |
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);
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:
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.