block_read()

read blocks of data from a file

Synopsis:

#include <sys/types.h>
#include <sys/disk.h>
int block_read( int fildes,
                long block,
                unsigned nblock,
                void *buf );

Description:

The block_read() function reads nblock blocks of data from the file associated with the open file descriptor fildes, into the buffer pointed to by buf, starting at block number block (blocks are numbered starting at 1). A block is 512 bytes long, as defined by _BLOCK_SIZE.

This function is not only 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, and the ability to transfer more than the read() functions limit of INT_MAX bytes at a time.)

If nblock is zero, block_read() returns zero and has no other results.

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

• the number of blocks left before the end-of-file is less than nblock
• the process requests more blocks than implementation limits allow to be read in a single atomic operation
• a read error occurs after reading at least one block

The implementation limit is specified by the macro _MAX_BLOCK_OPS in the file <sys/disk.h>.

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

Returns:

Upon successful completion, block_read() returns an integer indicating the number of blocks actually read. Otherwise, it returns -1, sets errno to indicate the error, and the contents of the buffer pointer to by buf are left unchanged.

Errors:

If any of the following conditions occurs, the block_read() function returns -1, and sets errno to the corresponding value:

EBADF

The fildes argument is not a valid file descriptor open for reading a block-oriented device.

EIO

A physical read error occurred on the first block.

EINVAL

The starting position is invalid (0 or negative) or beyond the end of the disk.

Examples:

#include <stdio.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <sys/disk.h>
#include <limits.h>
#include <sys/types.h>
#include <sys/fsys.h>

unsigned char buf[_BLOCK_SIZE];

int main( void )
  {
    int fd;
    int num_blocks;

    /* open a disk for reading */
    fd = open( "/dev/hd0", O_RDONLY );

    /* read the partition block */
    num_blocks = block_read( fd, 1L, 1, buf );

    if( num_blocks == -1 )
      perror( "block_read failed" );
    else
      printf( "First 2 bytes of Block 1:%x %x\n",
          buf[0], buf[1] );
    return (EXIT_SUCCESS);
  }

Classification:

QNX

See also:

block_write(), errno