readblock()

Read blocks of data from a file

Synopsis:

#include <unistd.h>

int readblock( int fd,
               size_t blksize,
               unsigned block,
               int numblks,
               void *buff );

Arguments:

fd
The file descriptor for the file you want to read from.
blksize
The number of bytes in each block of data.
block
The block number from which to start reading. Blocks are numbered starting at 0.
numblks
The number of blocks to read. If numblks is zero, readblock() returns zero and has no other results. If numblks is less than zero, or if numblks * blksize is greater than INT_MAX (see <limits.h>), the function returns -1 and sets errno to EINVAL.
buff
A pointer to a buffer where the function can store the data that it reads.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The readblock() function reads numblks blocks of data from the file associated with the open file descriptor fd, into the buffer pointed to by buff, starting at block number block. The blksize argument specifies the size of a block, in bytes.

This function is useful for direct access to raw blocks on a block special device (for example, raw disk blocks) but may also be used for high-speed access to database files, for example. The speed gain is through the combined seek/read implicit in this call.

On successful completion, readblock() returns the number of blocks actually read and placed in the buffer. This number is never greater than numblks. The value returned may be less than numblks if one of the following occurs:

If a read error occurs on the first block, readblock() returns -1 and sets errno to EIO.

Returns:

The number of blocks actually read. If an error occurs, -1 is returned, errno is set to indicate the error, and the contents of the buffer pointed to by buff are left unchanged.

Errors:

EBADF
The fd argument isn't a valid file descriptor open for reading.
EINTR
The read operation was interrupted by a signal, and either no data was transferred, or the resource manager responsible for that file doesn't report partial transfers.
EINVAL
An attempt was made to read a negative number of blocks or read a number of bytes that exceeds the allowable limit.
EIO
One of the following:
  • A physical I/O error occurred (for example, a bad block on a disk). The precise meaning is device-dependent.
  • The filesystem resides on a removable media device, and the media has been forcibly removed.
ENOSYS
The lseek() or read() function isn't implemented for the filesystem specified by the file descriptor.
ESPIPE
The file descriptor is associated with a pipe or FIFO.

Classification:

QNX Neutrino

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes