block_write()

write blocks of data to a file

Synopsis:

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

Description:

The block_write() function writes nblock blocks of data to the file associated with the open file descriptor fildes, from 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 updating of raw blocks on a block special device (for example, raw disk blocks) but may also be used for high-speed updating of database files (for example). (The speed gain is through the combined seek/write implicit in this call, and the ability to transfer more than the write() function's limit of INT_MAX bytes at a time.)

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

Upon successful completion, the block_write() function returns the number of blocks actually written to the disk associated with fildes. This number will never be 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 attempts to write more blocks than implementation limits allow to be written in a single atomic operation
• a write error occurs after writing at least one block, and one of the sync flags (O_SYNC or O_DSYNC) is set.

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

If a write error occurs on the first block and one of the sync flags is set, block_write() returns -1, and sets errno to EIO.

If one of the sync flags is set, block_write() doesn't return until the blocks are actually transferred to the disk. If neither of the flags is set, block_write() causes the blocks to be placed in the cache and scheduled for writing as soon as possible, but returns before the write takes place.

In the latter instance, it is impossible for the application to know if the write succeeded or not (due to system failures or bad disk blocks). Using the sync flags significantly impacts the performance of block_write(), but guarantees that the data can be recovered.

Returns:

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

Errors:

EBADF

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

EIO

A physical write error occurred on the first block, and either O_DSYNC or O_SYNC is set.

EINVAL

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

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>

/*
 *  NOTE: This will modify data on the disk, so you 
 *    might wish to consider the effects before 
 *    running this sample code.
 */
char buf[_BLOCK_SIZE];

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

    /* open a disk for writing */
    fd = open( "/dev/fd0", O_WRONLY );

    num_blocks = block_write( fd, 1L, 1, buf );

    if( num_blocks == -1 )
    {
      perror( "block_write failed" );
      return (EXIT_FAILURE);
    }
    return (EXIT_SUCCESS);
  }

Classification:

QNX

See also:

block_read(), errno