Function pwrite [src]
Write to a file descriptor, with a position offset.
Retries when interrupted by a signal.
Returns the number of bytes written. If nonzero bytes were supplied, this will be nonzero.
Note that a successful write() may transfer fewer bytes than supplied. Such partial writes can
occur for various reasons; for example, because there was insufficient space on the disk
device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or
similar was interrupted by a signal handler after it had transferred some, but before it had
transferred all of the requested bytes. In the event of a partial write, the caller can make
another write() call to transfer the remaining bytes. The subsequent call will either
transfer further bytes or may result in an error (e.g., if the disk is now full).
For POSIX systems, if fd is opened in non blocking mode, the function will
return error.WouldBlock when EAGAIN is received.
On Windows, if the application has a global event loop enabled, I/O Completion Ports are
used to perform the I/O. error.WouldBlock is not possible on Windows.
Linux has a limit on how many bytes may be transferred in one pwrite call, which is 0x7ffff000
on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as
well as stuffing the errno codes into the last 4096 values. This is noted on the write man page.
The limit on Darwin is 0x7fffffff, trying to write more than that returns EINVAL.
The corresponding POSIX limit is maxInt(isize).
Prototype
pub fn pwrite(fd: fd_t, bytes: []const u8, offset: u64) PWriteError!usize Parameters
fd: fd_tbytes: []const u8offset: u64 Possible Errors
File descriptor does not hold the required rights to write to it.
Connection reset by peer.
The process cannot access the file because another process has locked a portion of the file. Windows-only.
The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message is not transmitted.
This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.
This error occurs in Linux if the process being written to no longer exists.
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
This error occurs when no global event loop is configured, and reading from the file descriptor would block.
Source
pub fn pwrite(fd: fd_t, bytes: []const u8, offset: u64) PWriteError!usize {
if (bytes.len == 0) return 0;
if (native_os == .windows) {
return windows.WriteFile(fd, bytes, offset);
}
if (native_os == .wasi and !builtin.link_libc) {
const ciovs = [1]iovec_const{iovec_const{
.base = bytes.ptr,
.len = bytes.len,
}};
var nwritten: usize = undefined;
switch (wasi.fd_pwrite(fd, &ciovs, ciovs.len, offset, &nwritten)) {
.SUCCESS => return nwritten,
.INTR => unreachable,
.INVAL => unreachable,
.FAULT => unreachable,
.AGAIN => unreachable,
.BADF => return error.NotOpenForWriting, // can be a race condition.
.DESTADDRREQ => unreachable, // `connect` was never called.
.DQUOT => return error.DiskQuota,
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.PERM => return error.PermissionDenied,
.PIPE => return error.BrokenPipe,
.NXIO => return error.Unseekable,
.SPIPE => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return unexpectedErrno(err),
}
}
// Prevent EINVAL.
const max_count = switch (native_os) {
.linux => 0x7ffff000,
.macos, .ios, .watchos, .tvos, .visionos => maxInt(i32),
else => maxInt(isize),
};
const pwrite_sym = if (lfs64_abi) system.pwrite64 else system.pwrite;
while (true) {
const rc = pwrite_sym(fd, bytes.ptr, @min(bytes.len, max_count), @bitCast(offset));
switch (errno(rc)) {
.SUCCESS => return @intCast(rc),
.INTR => continue,
.INVAL => return error.InvalidArgument,
.FAULT => unreachable,
.NOENT => return error.ProcessNotFound,
.AGAIN => return error.WouldBlock,
.BADF => return error.NotOpenForWriting, // Can be a race condition.
.DESTADDRREQ => unreachable, // `connect` was never called.
.DQUOT => return error.DiskQuota,
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.PERM => return error.PermissionDenied,
.PIPE => return error.BrokenPipe,
.NXIO => return error.Unseekable,
.SPIPE => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.BUSY => return error.DeviceBusy,
else => |err| return unexpectedErrno(err),
}
}
}