writeblock()

Write blocks of data to a file

Synopsis:

#include <unistd.h>

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

Arguments:

fd

The file descriptor for the file you want to write in.

blksize

The number of bytes in each block of data.

block

The block number from which to start writing.

numblks

The number of blocks to write.

buff

A pointer to a buffer that contains the blocks of data that you want to write.

Library:

libc

Description:

The writeblock() function writes numblks blocks of data to the file associated with the open file descriptor fd, from the buffer pointed to by buff, starting at block number block (blocks are numbered starting at 0). The blksize argument defines the size of a block, in bytes.

This function is useful for direct updating of raw blocks on a block special device (for example, raw disk blocks) but you can also use it 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 numblks is zero, writeblock() returns zero, and has no other results.

Upon successful completion, the writeblock() function returns the number of blocks actually written to the disk associated with fd. This number is never greater than numblks. The value returned may be less than numblks if one of the following occurs:

• The number of blocks left before the end-of-file is less than numblks.
• The process attempts to write more blocks than implementation limits allow to be written in a single atomic operation.
• A write error occurred after writing at least one block, and one of the sync flags (O_SYNC or O_DSYNC) is set.

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

If one of the sync flags is set, writeblock() doesn't return until the blocks are actually transferred to the disk. If neither of the flags is set, writeblock() 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's 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 writeblock(), but guarantees that the data can be recovered.

Returns:

The number of blocks actually written. If an error occurred, it returns -1, sets errno to indicate the error, and doesn't change the contents of the buffer pointed to by buff.

Errors:

EBADF

The fd argument isn't 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.

Classification:

QNX 6

See also:

readblock()