Function pread [src]
Number of bytes read is returned. Upon reading end-of-file, zero is returned.
Retries when interrupted by a signal.
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 pread 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 read man page.
The limit on Darwin is 0x7fffffff, trying to read more than that returns EINVAL.
The corresponding POSIX limit is maxInt(isize).
Prototype
pub fn pread(fd: fd_t, buf: []u8, offset: u64) PReadError!usize Parameters
fd: fd_tbuf: []u8offset: u64 Possible Errors
In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.
reading a timerfd with CANCEL_ON_SET will lead to this error when the clock goes through a discontinuous change
Unable to read file due to lock.
This error occurs in Linux if the process to be read from 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 pread(fd: fd_t, buf: []u8, offset: u64) PReadError!usize {
if (buf.len == 0) return 0;
if (native_os == .windows) {
return windows.ReadFile(fd, buf, offset);
}
if (native_os == .wasi and !builtin.link_libc) {
const iovs = [1]iovec{iovec{
.base = buf.ptr,
.len = buf.len,
}};
var nread: usize = undefined;
switch (wasi.fd_pread(fd, &iovs, iovs.len, offset, &nread)) {
.SUCCESS => return nread,
.INTR => unreachable,
.INVAL => unreachable,
.FAULT => unreachable,
.AGAIN => unreachable,
.BADF => return error.NotOpenForReading, // Can be a race condition.
.IO => return error.InputOutput,
.ISDIR => return error.IsDir,
.NOBUFS => return error.SystemResources,
.NOMEM => return error.SystemResources,
.NOTCONN => return error.SocketNotConnected,
.CONNRESET => return error.ConnectionResetByPeer,
.TIMEDOUT => return error.ConnectionTimedOut,
.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 pread_sym = if (lfs64_abi) system.pread64 else system.pread;
while (true) {
const rc = pread_sym(fd, buf.ptr, @min(buf.len, max_count), @bitCast(offset));
switch (errno(rc)) {
.SUCCESS => return @intCast(rc),
.INTR => continue,
.INVAL => unreachable,
.FAULT => unreachable,
.NOENT => return error.ProcessNotFound,
.AGAIN => return error.WouldBlock,
.BADF => return error.NotOpenForReading, // Can be a race condition.
.IO => return error.InputOutput,
.ISDIR => return error.IsDir,
.NOBUFS => return error.SystemResources,
.NOMEM => return error.SystemResources,
.NOTCONN => return error.SocketNotConnected,
.CONNRESET => return error.ConnectionResetByPeer,
.TIMEDOUT => return error.ConnectionTimedOut,
.NXIO => return error.Unseekable,
.SPIPE => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
else => |err| return unexpectedErrno(err),
}
}
}