writeblock()

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. If numblks is zero, writeblock() returns zero and has no other results. If numblks is less than zero, or if numblks * blksize is greater than SSIZE_MAX (see <limits.h>), the function returns -1 and sets errno to EINVAL. If numblks * blksize is less than or equal to SSIZE_MAX but greater than SSIZE_MAX - sizeof(io_write_t) - sizeof(io_lseek_t), the function returns -1 and sets errno to EOVERFLOW.

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 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.

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.

EFBIG

One of the following occurred:

• An attempt was made to write a file that exceeds the maximum file size, and there was no room for any bytes to be written.
• The file is a regular file, nbytes is greater than 0, and the starting position is greater than or equal to the offset maximum established in the open file description associated with fd.

EINTR

The write 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 write a negative number of blocks or write 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.

ENOSPC

There's no free space remaining on the device containing the file.

ENOSYS

The lseek() or write() function isn't implemented for the device specified by fd.

ENXIO

A request was made of a nonexistent device, or the request was outside the capabilities of the device.

EOVERFLOW

An attempt was made to write a number of bytes that when added to the sizes of the write and lseek message structures exceeds the allowable limit.

ESPIPE

The file descriptor is associated with a pipe, FIFO, or socket.

Classification:

QNX Neutrino