zkWrite - write on a file
#include "zkUnistd.h"
ssize_t zkWrite(int fildes, const void *buf, size_t nbyte);
The zkWrite() function attempts to write nbyte bytes from the buffer pointed to by buf to the regular file associated with the open file descriptor, fildes.
If nbyte is 0, zkWrite() will return 0 and have no other results.
The actual writing of data proceeds from the position in the file indicated by the file offset associated with fildes. Before successful return from zkWrite(), the file offset is incremented by the number of bytes actually written. If this incremented file offset is greater than the length of the file, the length of the file will be set to this file offset.
If a zkWrite() requests that more bytes be written than there is room for (for example, the physical end of a medium), only as many bytes as there is room for will be written.
If zkWrite() is interrupted by a signal before it writes any data, it will return -1 with errno set to [EINTR].
If zkWrite() is interrupted by a signal after it successfully writes some data, it will return the number of bytes written.
If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-dependent.
After a zkWrite() to a regular file has successfully returned:
- Any successful zkRead() from each byte position in the file that was modified by that write will return the data specified by the zkWrite() for that position until such byte positions are again modified.
- Any subsequent successful zkWrite() to the same byte position in the file will overwrite that file data.
Upon successful completion, zkWrite() will return the number of bytes actually written to the file associated with fildes. This number will never be greater than nbyte. Otherwise, -1 is returned and errno is set to indicate the error.
The zkWrite() function will fail if:
- [EAGAIN]
- The O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the zkWrite() operation.
- [EBADF]
- The fildes argument is not a valid file descriptor open for writing.
- [EFBIG]
- An attempt was made to write a file that exceeds the implementation-dependent maximum file size or the process' file size limit.
- [EFBIG]
- The file is a regular file, nbyte 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 fildes.
- [EINTR]
- The write operation was terminated due to the receipt of a signal, and no data was transferred.
- [EIO]
- A physical I/O error has occurred.
- [EIO]
- The process is a member of a background process group attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU and the process group of the process is orphaned. This error may also be returned under implementation-dependent conditions.
- [ENOSPC]
- There was no free space remaining on the device containing the file.
- [EPIPE]
- An attempt is made to write to a pipe or FIFO that is not open for reading by any process, or that only has one end open. A SIGPIPE signal will also be sent to the thread.
- [ERANGE]
- The transfer request size was outside the range supported by the STREAMS file associated with fildes.
The zkWrite() function may fail if:
- [EINVAL]
- The STREAM or multiplexer referenced by fildes is linked (directly or indirectly) downstream from a multiplexer.
- [ENXIO]
- A request was made of a non-existent device, or the request was outside the capabilities of the device.
- [ENXIO]
- A hangup occurred on the STREAM being written to.
The zkWrite() function may portably be used only with file descriptors representing regular files. Any attempt to use it on a socket, directory, FIFO, STREAMS file, terminal device file, character special file, or block special file is non-portable.