This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

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. Blocks are numbered starting at 0.

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

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

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.

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 (for example, of database files). The speed gain is through the combined seek/write implicit in this call.

If numblks is zero, writeblock() returns zero, and has no other results.

If successful, writeblock() returns the number of blocks actually written to the disk associated with fd. This number is never greater than numblks, but could be less than numblks if one of the following occurs:

• 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 you set one of the sync flags (O_SYNC or O_DSYNC — see open()) when you opened the file.

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() places the blocks in the cache and schedules them for writing as soon as possible, but returns before the writing 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, writeblock() 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 that's 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 Neutrino

See also:

open(), readblock(), write()