pread(), pread64(), read() read from file	Function
	SYNOPSIS DESCRIPTION PARAMETERS RETURN VALUES CONFORMANCE MULTITHREAD SAFETY LEVEL PORTING ISSUES AVAILABILITY SEE ALSO

---

SYNOPSIS

#include <sys/types.h>

#include <unistd.h>

ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset);

ssize_t pread64(int fildes, void *buf, size_t nbyte, off64_t offset);

ssize_t read(int fildes, void *buf, size_t nbyte);

---

DESCRIPTION

The read() function attempts to read the specified amount of data from the specified file descriptor, into the specified buffer.

If the number of bytes is 0, then read() returns 0 and has no other results.

On file that support seeking, such as regular files, the read() starts at a position in the file given by the offset associated with the file descriptor. The file offset is incremented by the number of bytes actually read.

On files that do not support seeking, such as terminals, reads always occur from the current position. The value of a file offset associated with such a file is undefined.

No data transfer occurs past the current end-of-file. If the starting position is at or after the end-of-file, 0 is returned. If the file refers to a device or special file, the result of subsequent read() requests is unspecified.

Reads larger than SSIZE_MAX are unsupported.

When attempting to read from an empty pipe or FIFO:

• If no process has the pipe open for writing, read() returns 0 and indicates end-of-file.
• If some process has the pipe open for writing, and O_NONBLOCK is set, read() returns -1 and sets errno to EAGAIN.
• If some process has the pipe open for writing, and O_NONBLOCK is clear, read() blocks the calling thread until some data is written or the pipe is closed by all processes that had the pipe open for writing.

When attempting to read a file (other than a pipe or FIFO) that supports non-blocking reads and has no data currently available:

• If O_NONBLOCK is set, read() returns -1 and sets errno to EWOULDBLOCK.
• If O_NONBLOCK is clear, read() blocks the calling thread until some data becomes available.
• The use of the O_NONBLOCK flag has no effect if there is some data available.

The read() function reads data previously written to a file. If any portion of a regular file prior to the end-of-file has not been written, read() returns bytes with value 0. For example, lseek() allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data return bytes with value 0 until data is written into the gap.

Upon successful completion, if the number of bytes requested is greater than 0, read() marks for update the st_atime field of the file, and return the number of bytes read.

The pread() function is identical to the read() function except that it starts reading at a point in the file indicated by the offset parameter. On the NuTCRACKER Platform, trying to use this function on a file that in incapable of seeking results in the offset parameter being ignored, making pread() identical to read() in such situations.

The pread64() function is identical to the pread() function except that it uses the larger off64_t in order to manipulate the file position of files that are larger than 2 gigabytes.

---

PARAMETERS

fildes 

Is the file descriptor that references an open file.

buf 

Points to the buffer to place the read information into.

nbyte 

Specifies the maximum number of bytes to attempt to read.

offset 

Specifies the point in the file at which pread() or pread64() begins reading.

---

RETURN VALUES

If successful, these functions return a non-negative integer that indicates the number of bytes read. The number of bytes read may be less than the number of bytes requested in any of the following conditions:

• The number of bytes left in the file is less than the requested length.
• The read() was interrupted by a signal.
• The file is a pipe or FIFO or special device and has fewer bytes than requested immediately available for reading.

On error, these functions return -1, and set errno to one of the following values:

EAGAIN 

The O_NONBLOCK flag is set for the file descriptor and the process would be delayed.

EBADF 

The fildes parameter is not a valid file descriptor open for reading.

EFAULT 

The buf parameter is not a valid pointer, or the buffer was overrun during the read() request.

EINTR 

The read(), pread(), or pread64() request was interrupted by a signal.

EIO 

A physical I/O error occurred.

EISDIR 

The fildes parameter refers to a directory. Use readdir() to read from directories.

ENXIO 

A request was made of a non-existent device, or the request was outside the capabilities of the device.

EOVERFLOW 

For all functions, the file is a regular file, nbyte is greater than 0, the starting position is before the end-of-file, and the starting position is greater than or equal to the offset maximum established in the open file description associated with fildes.

For pread() and pread64(), the specified offset would cause a read beyond the 2 GB boundary.

EWOULDBLOCK 

The O_NONBLOCK flag is set for the file descriptor and the process would be delayed.

---

CONFORMANCE

POSIX.1 (1996), with exceptions. UNIX 03, with exceptions.

---

MULTITHREAD SAFETY LEVEL

Async-signal-safe.

---

PORTING ISSUES

Refer to File Management in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide for a detailed discussion of file handling, including a discussion of text mode and binary mode for files.

The test which causes the EOVERFLOW error condition to be returned can be disabled by using the _NutConf() function to turn off the _NC_SET_FULL_LFS_SEMANTICS flag.

While the UNIX 03 specification states that pread() does not change the file pointer, the underlying Win32 APIs used to implement the function on the NuTCRACKER Platform do adjust the file pointer. As a result it is recommended that you not mix pread() (or pread64()) and read() in the same application.

Additionally, although the UNIX 03 specification states that using pread() on a file descriptor for a non-regular file fails with an error, the NuTCRACKER Platform implementations (modelling many common implementations) of pread() and pread64() just silently succeed on non-seekable devices and ignore the offset parameter.

---

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

---

SEE ALSO

Functions:

creat(), dup(), dup2(), fcntl(), ioctl(), lseek(), open(), pipe(), readdir(), readv(), socket(), write(), writev()

Miscellaneous:

lf64

---

PTC MKS Toolkit 10.5 Documentation Build 40.