字段
allocator: Allocator
mutex: Io.Mutex = .init
cond: Io.Condition = .init
run_queue: std.SinglyLinkedList = .{}
join_requested: bool = false
stack_size: usize
wait_group: WaitGroup = .init所有线程均以分离状态派生;通过此处等待它们全部退出。
async_limit: Io.Limit
concurrent_limit: Io.Limit = .unlimited
cpu_count_error: ?std.Thread.CpuCountError在 init 中调用 std.Thread.getCpuCount 产生的错误。
busy_count: usize = 0无法接收任务的线程数量。可用数量等于 async_limit 或 concurrent_limit 减去此值。
worker_threads: std.atomic.Value(?*Thread)
pid: Pid = .unknown
have_signal_handler: bool
old_sig_io: if (have_sig_io) posix.Sigaction else void
old_sig_pipe: if (have_sig_pipe) posix.Sigaction else void
use_sendfile: UseSendfile = .default
use_copy_file_range: UseCopyFileRange = .default
use_fcopyfile: UseFcopyfile = .default
use_fchmodat2: UseFchmodat2 = .default
disable_memory_mapping: bool
stderr_writer: File.Writer = .{
.io = undefined,
.interface = File.Writer.initInterface(&.{}),
.file = if (is_windows) undefined else .stderr(),
.mode = .streaming,
}
stderr_mode: Io.Terminal.Mode = .no_color
stderr_writer_initialized: bool = false
stderr_mutex: Io.Mutex = .init
stderr_mutex_locker: std.Thread.Id = Thread.invalid_id
stderr_mutex_lock_count: usize = 0
argv0: Argv0
environ_initialized: bool由 mutex 保护。确定 environ 是否已基于
process_environ 进行记忆化。
environ: Environ
dl: Dl = .init
null_file: NullFile = .{}
random_file: RandomFile = .{}
pipe_file: PipeFile = .{}
csprng: Csprng = .uninitialized
system_basic_information: SystemBasicInformation = .{}
process_spawn_mutex: if (is_windows) Io.Mutex else void = if (is_windows) .init else {}
Threadedbuiltinnative_osis_windowsis_darwinis_debugstdIonetFileDirHostNameIpAddressprocessAllocatorAlignmentassertposixwindowsws2_32SystemBasicInformationDlCsprngArgv0EnvironNullFileRandomFilePipeFilePidUseSendfileUseCopyFileRangeUseFcopyfileUseFchmodat2apc_aligndefault_fn_alignRunnableGroupFutureAwaitableIdThreadSyscallAlertableSyscallwaitForApcOrAlertmax_iovecs_lensplat_buffer_sizepoll_buffer_lendefault_PATHmax_windows_kernel_bug_retriesInitOptionsinitinit_single_threadedglobal_single_threaded_instanceglobal_single_threadedsetAsyncLimitdeinitjoinworkeriosocket_flags_unsupportedhave_accept4have_flock_open_flagshave_networkinghave_flockhave_sendmmsghave_futexhave_preadvhave_sig_iohave_sig_pipehave_sendfilehave_copy_file_rangehave_fcntlhave_fcopyfilehave_fchmodat2have_fchmodat_flagshave_fchownhave_fchmodhave_waitidhave_wait4have_mmaphave_pollopen_symopenat_symfstat_symfstatat_symlseek_sympreadv_sympread_symftruncate_sympwritev_sympwrite_symsendfile_symmmap_symlinux_copy_file_range_use_clinux_copy_file_range_sysstatx_use_cuse_libc_getrandomuse_dev_urandomcrashHandlerasyncconcurrentgroupAsyncgroupAsyncEagergroupConcurrentgroupAwaitgroupCancelrecancelrecancelInnerswapCancelProtectioncheckCancelawaitcancelfutexWaitfutexWaitUncancelablefutexWakeoperatebatchAwaitAsyncbatchAwaitConcurrentWindowsBatchOperationUserdatabatchCancelbatchCompleteBlockingWindowsbatchApcbatchDrainSubmittedWindowswindowsWriteBuffersubmitCompletedirCreateDirdirCreateDirPosixdirCreateDirWasidirCreateDirWindowsdirCreateDirPathdirCreateDirPathOpendirCreateDirPathOpenPosixdirCreateDirPathOpenWindowsdirCreateDirPathOpenWasidirStatdirStatFiledirStatFileLinuxdirStatFilePosixposixStatFiledirStatFileWindowsdirStatFileWasifilePathKindfileLengthfileStatfileStatPosixfileStatLinuxfileStatWindowssystemBasicInformationfileStatWasidirAccessdirAccessPosixdirAccessWasidirAccessWindowsdirCreateFiledirCreateFilePosixdirCreateFileWindowsdirCreateFileWasidirCreateFileAtomicatomicFileInitdirOpenFiledirOpenFilePosixdirOpenFileWindowsdirOpenFileWtf16dirOpenFileWasidirOpenDirdirOpenDirPosixdirOpenDirHaikudirOpenDirWindowsdirClosedirReaddirReadLinuxdirReadDarwindirReadBsddirReadIllumosdirReadHaikudirReadWindowsdirReadWasidirReadUnimplementeddirRealPathFiledirRealPathFileWindowsrealPathWindowsrealPathWindowsBufGetFinalPathNameByHandleFormatGetFinalPathNameByHandleErrorGetFinalPathNameByHandlemountmgrIsVolumeNameQueryObjectNameErrorQueryObjectNameWtf16ToPrefixedFileWErrorWtf16ToPrefixedFileWOptionswToPrefixedFileWLocalDevicePathTypegetLocalDevicePathTypeWtf8ToPrefixedFileWErrorsliceToPrefixedFileWWindowsPathSpacedirRealPathFilePosixdirRealPathdirRealPathPosixdirRealPathWindowsfileRealPathfileRealPathWindowsfileRealPathPosixrealPathPosixfileHardLinklinkatdirDeleteFiledirDeleteFileWindowsdirDeleteFileWasidirDeleteFilePosixdirDeleteDirdirDeleteDirWindowsdirDeleteWindowsdirDeleteDirWasidirDeleteDirPosixdirRenamedirRenameWindowsdirRenamePreservedirRenameWindowsInnerdirRenameWasidirRenamePosixdirRenamePreserveDarwindirRenamePreserveLinuxrenameatdirSymLinkdirSymLinkWindowsdirSymLinkWasidirSymLinkPosixdirReadLinkdirReadLinkWindowsparseReadLinkPathdirReadLinkWasidirReadLinkPosixdirSetPermissionsdirSetPermissionsWindowsdirSetPermissionsPosixdirSetFilePermissionsposixFchmodatfchmodatFallbackdirSetOwnerdirSetOwnerUnsupporteddirSetOwnerPosixposixFchowndirSetFileOwnerfileSyncfileSyncWindowsfileSyncPosixfileSyncWasifileIsTtyisTtyfileEnableAnsiEscapeCodesfileSupportsAnsiEscapeCodessupportsAnsiEscapeCodesisCygwinPtyfileSetLengthfileSetOwnerfileSetPermissionssetPermissionsPosixdirSetTimestampsfileSetTimestampswindows_lock_range_offwindows_lock_range_lenfileLockfileTryLockfileUnlockfileDowngradeLockdirOpenDirWasidirHardLinkfileClosefileReadStreamingfileReadStreamingPosixfileReadStreamingWindowsflagApcntReadFileResultntWriteFileResultfileReadPositionalPosixfileReadPositionalfileReadPositionalWindowsreadFilePositionalWindowsfileSeekByfileSeekToposixSeekToprocessExecutableOpenprocessExecutablePathfileWritePositionalwriteFilePositionalWindowsfileWriteStreamingfileWriteStreamingWindowsfileWriteFileStreamingnetWriteFilefileWriteFilePositionalnowPosixnowclockResolutionclockResolutionPosixnowWindowsnowWasisleepsleepPosixsleepWasisleepNanosleepnetListenIpPosixnetListenIpWindowsnetListenUnixPosixnetListenUnixWindowsposixBindUnixposixBindposixConnectposixConnectUnixposixGetSockNamesetSocketOptionPosixsetSocketOptionAfdsocketOptionAfdnetConnectIpPosixnetConnectIpWindowsnetConnectUnixPosixnetConnectUnixWindowsnetBindIpPosixnetBindIpWindowsopenSocketPosixsetCloexecnetSocketCreatePairopenSocketAfdbindSocketIpAfdbindSocketUnixAfdnetAcceptPosixnetAcceptWindowsdeferAcceptAfdnetReadnetReadPosixnetReadWindowsnetSendPosixnetSendWindowsnetSendOneWindowsnetSendOnePosixnetSendManyPosixnetReceivePosixnetReceiveWindowsnetReceiveOneWindowsnetWritePosixnetWriteWindowsaddAfdBufiovlen_taddBufnetClosenetShutdownPosixnetShutdownWindowsnetInterfaceNameResolvenetInterfaceNamenetLookupnetLookupFalliblelockStderrtryLockStderrinitLockedStderrunlockStderrprocessCurrentPathprocessCurrentPathPosixprocessSetCurrentDirprocessSetCurrentPathPosixAddressUnixAddressposixAddressFamilyaddressFromPosixaddressToPosixaddressUnixToPosixaddress4FromPosixaddress6FromPosixaddress4ToPosixaddress6ToPosixerrnoBugposixSocketModeProtocolrecoverableOsBugDetectedclockToPosixclockToWasilinux_statx_requestlinux_statx_checkstatFromLinuxstatxKindstatFromPosixstatFromWasitimestampFromPosixnanosecondsFromPosixtimestampToPosixsetTimestampToPosixpathToPosixlookupDnsSearchlookupDnslookupHostslookupHostsReaderwriteResolutionQueryLookupDnsWindowscopyCanondarwin_supports_ulock_wait2doNothingSignalHandlerWindowsEnvironStringsscanEnvironprocessReplaceprocessSpawnprocessSpawnUnsupportedSpawnedspawnPosixgetDevNullFdprocessSpawnPosixchildWaitchildKillchildKillWindowschildWaitWindowschildCleanupWindowschildWaitPosixstatusToTermchildKillPosixchildCleanupPosixForkBailErrorforkBailwriteIntFdreadIntFdErrIntdestroyPipeprocessSpawnDarwinprocessSpawnWindowsgetCngDevicegetNulDevicegetNamedPipeDevicewindowsCreateProcessPathExtwindowsCreateProcesswindowsCreateProcessSupportsExtensionWindowsCommandLineCacheArgvToScriptCommandLineErrorargvToScriptCommandLineWindowsArgvToCommandLineErrorargvToCommandLineWindowstestArgvToCommandLineWindowsposixExecposixExecveatspawnDarwinCreatePipeOptionswindowsCreatePipeprogressParentFileinheritParentHandleinheritParentDirinheritParentFileenvironStringrandomrandomMainThreadfallbackSeedfallbackSeedPosixfallbackSeedWindowsfallbackSeedWasirandomSecuregetRandomFduse_parking_futexuse_parking_sleepparking_futexparking_sleepParkingMutextimeoutToWindowsIntervalneed_unpark_flagUnparkFlagunpark_flag_initsetUnparkFlagUnparkTidParkTidpark_semgetParkTiddestroyParkSemparkunparkPipeErrorpipe2DupErrordup2FchdirErrorfchdirChdirErrorchdirfileMemoryMapCreateCreateFileMapErrorcreateFileMapfileMemoryMapDestroyfileMemoryMapSetLengthfileMemoryMapReadfileMemoryMapWritemmSyncReadmmSyncWritedeviceIoControlWaitGroupeventWaiteventSetcondBroadcastcondSignalcondWaitmutexLockmutexLockUncancelablemutexUnlockOpenErrorOpenFileOptionsOpenFilecloseFd
std.Io.Threaded.addAfdBuf
函数
fn addAfdBuf( comptime mutability: windows.AFD.Mutability, iovecs: []windows.AFD.WSABUF(mutability), len: *u32, bytes: switch (mutability) { .@"const" => []const u8, .@"var" => []u8, }, ) void
参数
std.Io.Threaded.addBuf
函数
fn addBuf(v: []posix.iovec_const, i: *iovlen_t, bytes: []const u8) void
参数
std.Io.Threaded.address4FromPosix
函数
fn address4FromPosix(in: *const posix.sockaddr.in) net.Ip4Address
参数
std.Io.Threaded.address4ToPosix
函数
fn address4ToPosix(a: net.Ip4Address) posix.sockaddr.in
参数
a: net.Ip4Address
std.Io.Threaded.address6FromPosix
函数
fn address6FromPosix(in6: *const posix.sockaddr.in6) net.Ip6Address
参数
std.Io.Threaded.address6ToPosix
函数
fn address6ToPosix(a: *const net.Ip6Address) posix.sockaddr.in6
参数
a: *const net.Ip6Address
std.Io.Threaded.addressFromPosix
函数
pub fn addressFromPosix(posix_address: *const PosixAddress) IpAddress
参数
posix_address: *const PosixAddress
std.Io.Threaded.addressToPosix
函数
pub fn addressToPosix(a: *const IpAddress, storage: *PosixAddress) posix.socklen_t
参数
a: *const IpAddress
storage: *PosixAddress
std.Io.Threaded.addressUnixToPosix
函数
fn addressUnixToPosix(a: *const net.UnixAddress, storage: *UnixAddress) posix.socklen_t
参数
a: *const net.UnixAddress
storage: *UnixAddress
std.Io.Threaded.AlertableSyscall
容器
字段
thread: ?*Thread
std.Io.Threaded.AlertableSyscall.checkCancel
函数
fn checkCancel(s: AlertableSyscall) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.AlertableSyscall.fail
函数
fn fail(s: AlertableSyscall, err: anytype) @TypeOf(err)
参数
std.Io.Threaded.AlertableSyscall.finish
函数
fn finish(s: AlertableSyscall) void
参数
std.Io.Threaded.AlertableSyscall.ntstatusBug
函数
fn ntstatusBug(s: AlertableSyscall, status: windows.NTSTATUS) Io.UnexpectedError
参数
s: AlertableSyscall
status: windows.NTSTATUS
std.Io.Threaded.AlertableSyscall.start
函数
fn start() Io.Cancelable!AlertableSyscall
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.AlertableSyscall.unexpectedNtstatus
函数
fn unexpectedNtstatus(s: AlertableSyscall, status: windows.NTSTATUS) Io.UnexpectedError
参数
s: AlertableSyscall
status: windows.NTSTATUS
std.Io.Threaded.Alignment
别名
别名目标 std.mem.Alignment
std.Io.Threaded.Allocator
别名
别名目标 std.mem.Allocator
std.Io.Threaded.apc_align
常量
std.Io.Threaded.Argv0
类型
std.Io.Threaded.Argv0.empty
常量
Argv0
std.Io.Threaded.Argv0.empty
常量
Argv0
std.Io.Threaded.Argv0.init
函数
pub fn init(args: process.Args) Argv0
参数
std.Io.Threaded.Argv0.init
函数
pub fn init(args: process.Args) Argv0
参数
std.Io.Threaded.ArgvToCommandLineError
错误集合
错误
- InvalidArg0
- InvalidWtf8
- OutOfMemory
std.Io.Threaded.argvToCommandLineWindows
函数
将 argv 序列化为 Windows 命令行字符串,可传给子进程并由
CommandLineToArgvW 算法解析。调用方拥有返回切片。
启动 .bat/.cmd 脚本时,不应使用此函数,以免发生任意命令执行。
https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
执行 .bat/.cmd 脚本时,请改用 argvToScriptCommandLineWindows。
fn argvToCommandLineWindows( allocator: Allocator, argv: []const []const u8, ) ArgvToCommandLineError![:0]u16
参数
allocator: Allocator
argv: []const []const u8
错误
- InvalidArg0
- InvalidWtf8
- OutOfMemory
用法示例
test argvToCommandLineWindows {
const t = testArgvToCommandLineWindows;
try t(&.{
\\C:\Program Files\zig\zig.exe
,
\\run
,
\\.\src\main.zig
,
\\-target
,
\\x86_64-windows-gnu
,
\\-O
,
\\safe
,
\\--
,
\\--emoji=🗿
,
\\--eval=new Regex("Dwayne \"The Rock\" Johnson")
,
},
\\"C:\Program Files\zig\zig.exe" run .\src\main.zig -target x86_64-windows-gnu -O safe -- --emoji=🗿 "--eval=new Regex(\"Dwayne \\\"The Rock\\\" Johnson\")"
);
try t(&.{}, "");
try t(&.{""}, "\"\"");
try t(&.{" "}, "\" \"");
try t(&.{"\t"}, "\"\t\"");
try t(&.{"\x07"}, "\"\x07\"");
try t(&.{"🦎"}, "🦎");
try t(
&.{ "zig", "aa aa", "bb\tbb", "cc\ncc", "dd\r\ndd", "ee\x7Fee" },
"zig \"aa aa\" \"bb\tbb\" \"cc\ncc\" \"dd\r\ndd\" ee\x7Fee",
);
try t(
&.{ "\\\\foo bar\\foo bar\\", "\\\\zig zag\\zig zag\\" },
"\"\\\\foo bar\\foo bar\\\" \"\\\\zig zag\\zig zag\\\\\"",
);
try std.testing.expectError(
error.InvalidArg0,
argvToCommandLineWindows(std.testing.allocator, &.{"\"quotes\"quotes\""}),
);
try std.testing.expectError(
error.InvalidArg0,
argvToCommandLineWindows(std.testing.allocator, &.{"quotes\"quotes"}),
);
try std.testing.expectError(
error.InvalidArg0,
argvToCommandLineWindows(std.testing.allocator, &.{"q u o t e s \" q u o t e s"}),
);
}
std.Io.Threaded.ArgvToScriptCommandLineError
错误集合
错误
- InvalidBatchScriptArg
执行
.bat/.cmd脚本时,参数内不允许包含 NUL(U+0000)、LF(U+000A)、CR(U+000D)。- NUL/LF 表示参数结束,因此其后所有内容 在执行后都会丢失。
cmd.exe会移除 CR,因此任何 CR 码点 在执行后都会丢失。
- InvalidWtf8
- OutOfMemory
std.Io.Threaded.argvToScriptCommandLineWindows
函数
将 argv 序列化为 Windows 命令行字符串,使用 cmd.exe /c 及 cmd.exe 专用转义规则。调用方拥有返回切片的所有权。
转义 argv 时采用以下文章针对任意命令执行所建议的缓解措施:
https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
此函数返回的内容形如
cmd.exe /d /e:ON /v:OFF /c "<escaped command line>"
应将其用作 CreateProcessW 的 lpCommandLine,而 WindowsCommandLineCache.cmdExePath 的返回值应作为 lpApplicationName。
仅在创建 .bat/.cmd 脚本进程时使用;其他情况见 argvToCommandLineWindows。必须已知该 .bat/.cmd 文件既具有 .bat/.cmd 扩展名,也确实存在于文件系统中。
fn argvToScriptCommandLineWindows( allocator: Allocator, script_path: []const u16, script_args: []const []const u8, ) ArgvToScriptCommandLineError![:0]u16
参数
allocator: Allocator
script_path: []const u16.bat/.cmd 脚本的路径。若为相对路径,则假定相对于当前工作目录。
调用此函数前,必须已确认脚本存在于此路径。
script_args: []const []const u8参数,不包括脚本名称本身。预期采用 WTF-8 编码。
错误
- InvalidBatchScriptArg
执行
.bat/.cmd脚本时,参数内不允许包含 NUL(U+0000)、LF(U+000A)、CR(U+000D)。- NUL/LF 表示参数结束,因此其后所有内容 在执行后都会丢失。
cmd.exe会移除 CR,因此任何 CR 码点 在执行后都会丢失。
- InvalidWtf8
- OutOfMemory
std.Io.Threaded.assert
别名
别名目标 std.debug.assert
std.Io.Threaded.async
函数
fn async( userdata: ?*anyopaque, result: []u8, result_alignment: Alignment, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void, ) ?*Io.AnyFuture
参数
std.Io.Threaded.atomicFileInit
函数
fn atomicFileInit( t_io: Io, dest_basename: []const u8, permissions: File.Permissions, dir: Dir, close_dir_on_deinit: bool, ) Dir.CreateFileAtomicError!File.Atomic
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试创建的文件是正在运行的可执行文件。
- FileNotFound
以下情况之一:
- 某个路径分量不存在。
- 使用了 Cwd,但当前工作目录已被删除。
- 与已打开目录句柄关联的路径已被删除。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。
- NotDir
路径中作为目录使用的某个组成部分实际上不是目录。
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
可用内核内存不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Threaded.await
函数
fn await( userdata: ?*anyopaque, any_future: *Io.AnyFuture, result: []u8, result_alignment: Alignment, ) void
参数
std.Io.Threaded.AwaitableId
容器
唯一标识某个组或 future 的 (ptr_bit_width - 3) 位序列。它们是
*Io.Group 或 *Future 的最高有效位。这些地址末尾不一定有 3 个零位,
因为仅按指针对齐,32 位目标上只有 2 个。但因为两者的
大小都至少为 8 字节,内存中同时存在的任意两个组/future
不可能在这些位上完全相同。换言之,给定一个组/future 指针,
下一个组或 future 至少在其后 8 字节处,因此其地址最高
(ptr_bit_width - 3) 位中至少有一位不同。
字段
std.Io.Threaded.AwaitableId.fromFuture
函数
fn fromFuture(f: *Future) AwaitableId
参数
f: *Future
std.Io.Threaded.AwaitableId.fromGroup
函数
fn fromGroup(g: *Io.Group) AwaitableId
参数
std.Io.Threaded.AwaitableId.Split
容器
字段
low: u3
high: AwaitableId
std.Io.Threaded.batchApc
函数
fn batchApc( apc_context: ?*anyopaque, iosb: *windows.IO_STATUS_BLOCK, _: windows.ULONG, ) align(apc_align) callconv(.winapi) void
参数
std.Io.Threaded.batchAwaitAsync
函数
fn batchAwaitAsync(userdata: ?*anyopaque, b: *Io.Batch) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.batchAwaitConcurrent
函数
fn batchAwaitConcurrent(userdata: ?*anyopaque, b: *Io.Batch, timeout: Io.Timeout) Io.Batch.AwaitConcurrentError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConcurrencyUnavailable ConcurrentError
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
- Timeout Error
std.Io.Threaded.batchAwaitConcurrent.add
函数
fn add(storage: *@This(), fd: File.Handle, events: @FieldType(posix.pollfd, "events")) Io.ConcurrentError!void
参数
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.Threaded.batchCancel
函数
fn batchCancel(userdata: ?*anyopaque, b: *Io.Batch) void
参数
std.Io.Threaded.batchCompleteBlockingWindows
函数
fn batchCompleteBlockingWindows( b: *Io.Batch, operation_userdata: *WindowsBatchOperationUserdata, result: Io.Operation.Result, ) void
参数
std.Io.Threaded.batchDrainSubmittedWindows
函数
若 concurrency 为 false,则 error.ConcurrencyUnavailable 不可达。
fn batchDrainSubmittedWindows(t: *Threaded, b: *Io.Batch, concurrency: bool) (Io.ConcurrentError || Io.Cancelable)!void
参数
std.Io.Threaded.bindSocketIpAfd
函数
fn bindSocketIpAfd(socket_handle: net.Socket.Handle, address: *const IpAddress, mode: windows.AFD.BIND_INFO.MODE) !IpAddress
参数
std.Io.Threaded.bindSocketUnixAfd
函数
fn bindSocketUnixAfd(socket_handle: net.Socket.Handle, address: *const net.UnixAddress) !void
参数
socket_handle: net.Socket.Handle
address: *const net.UnixAddress
std.Io.Threaded.builtin
常量
std.Io.Threaded.cancel
函数
fn cancel( userdata: ?*anyopaque, any_future: *Io.AnyFuture, result: []u8, result_alignment: Alignment, ) void
参数
std.Io.Threaded.chdir
函数
pub fn chdir(dir_path: []const u8) ChdirError!void
参数
dir_path: []const u8
错误
- AccessDenied
- BadPathName
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- FileSystem
- NameTooLong
- NotDir
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.ChdirError
错误集合
错误
- AccessDenied
- BadPathName
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- FileSystem
- NameTooLong
- NotDir
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.checkCancel
函数
fn checkCancel(userdata: ?*anyopaque) Io.Cancelable!void
参数
userdata: ?*anyopaque
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.childCleanupPosix
函数
fn childCleanupPosix(child: *process.Child) void
参数
std.Io.Threaded.childCleanupWindows
函数
fn childCleanupWindows(child: *process.Child) void
参数
std.Io.Threaded.childKill
函数
fn childKill(userdata: ?*anyopaque, child: *process.Child) void
参数
std.Io.Threaded.childKillPosix
函数
fn childKillPosix(child: *process.Child) !void
参数
std.Io.Threaded.childKillWindows
函数
fn childKillWindows(t: *Threaded, child: *process.Child, exit_code: windows.UINT) !void
参数
std.Io.Threaded.childWait
函数
fn childWait(userdata: ?*anyopaque, child: *process.Child) process.Child.WaitError!process.Child.Term
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.childWaitPosix
函数
fn childWaitPosix(child: *process.Child) process.Child.WaitError!process.Child.Term
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.childWaitWindows
函数
fn childWaitWindows(child: *process.Child) process.Child.WaitError!process.Child.Term
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.clockResolution
函数
fn clockResolution(userdata: ?*anyopaque, clock: Io.Clock) Io.Clock.ResolutionError!Io.Duration
参数
错误
- ClockUnavailable
- Unexpected
std.Io.Threaded.clockResolutionPosix
函数
fn clockResolutionPosix(clock: Io.Clock) Io.Clock.ResolutionError!Io.Duration
参数
错误
- ClockUnavailable
- Unexpected
std.Io.Threaded.clockToPosix
函数
pub fn clockToPosix(clock: Io.Clock) posix.clockid_t
参数
std.Io.Threaded.clockToWasi
函数
fn clockToWasi(clock: Io.Clock) std.os.wasi.clockid_t
参数
std.Io.Threaded.closeFd
函数
pub fn closeFd(fd: posix.fd_t) void
参数
std.Io.Threaded.concurrent
函数
fn concurrent( userdata: ?*anyopaque, result_len: usize, result_alignment: Alignment, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void, ) Io.ConcurrentError!*Io.AnyFuture
参数
userdata: ?*anyopaque
result_len: usize
result_alignment: Alignment
context: []const u8
context_alignment: Alignment
start: *const fn (context: *const anyopaque, result: *anyopaque) void
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.Threaded.condBroadcast
函数
与 Io.Condition.broadcast 相同,但绕过虚函数表。
fn condBroadcast(cond: *Io.Condition) void
参数
std.Io.Threaded.condSignal
函数
与 Io.Condition.signal 相同,但绕过虚函数表。
fn condSignal(cond: *Io.Condition) void
参数
std.Io.Threaded.condWait
函数
与 Io.Condition.waitUncancelable 相同,但绕过虚函数表。
fn condWait(cond: *Io.Condition, mutex: *Io.Mutex) void
参数
std.Io.Threaded.copyCanon
函数
fn copyCanon(canonical_name_buffer: ?*[HostName.max_len]u8, name: []const u8) ?HostName
参数
std.Io.Threaded.crashHandler
函数
fn crashHandler(userdata: ?*anyopaque) void
参数
userdata: ?*anyopaque
std.Io.Threaded.createFileMap
函数
fn createFileMap( file: File, protection: process.MemoryProtection, offset: u64, populate: bool, len: usize, ) CreateFileMapError!File.MemoryMap
参数
错误
- AccessDenied
文件描述符引用非普通文件;或请求文件映射, 但文件描述符未以读取方式打开;或请求
MAP.SHARED并设置PROT_WRITE,但文件描述符未以RDWR模式打开; 或设置PROT_WRITE,但文件仅允许追加。- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- LockViolation
- LockedMemoryLimitExceeded
- MappingAlreadyExists
- OperationUnsupported
- OutOfMemory
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SectionOversize
MaximumSize 大于系统定义的节大小上限,或 大于指定文件的大小且该节不可写。
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.Threaded.CreateFileMapError
错误集合
错误
- AccessDenied
文件描述符引用非普通文件;或请求文件映射, 但文件描述符未以读取方式打开;或请求
MAP.SHARED并设置PROT_WRITE,但文件描述符未以RDWR模式打开; 或设置PROT_WRITE,但文件仅允许追加。- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- LockViolation
- LockedMemoryLimitExceeded
- MappingAlreadyExists
- OperationUnsupported
- OutOfMemory
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SectionOversize
MaximumSize 大于系统定义的节大小上限,或 大于指定文件的大小且该节不可写。
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.Threaded.CreatePipeOptions
容器
字段
std.Io.Threaded.CreatePipeOptions.End
容器
字段
std.Io.Threaded.Csprng
容器
字段
rng: std.Random.DefaultCsprng
std.Io.Threaded.Csprng.isInitialized
函数
pub fn isInitialized(c: *const Csprng) bool
参数
c: *const Csprng
std.Io.Threaded.Csprng.seed_len
别名
std.Io.Threaded.Csprng.uninitialized
常量
Csprng
std.Io.Threaded.darwin_supports_ulock_wait2
常量
Darwin XNU 7195.50.7.100.1 引入 __ulock_wait2,并将若干代码路径,尤其是 pthread_cond_t,迁移到该接口: https://github.com/apple/darwin-xnu/commit/d4061fb0260b3ed486147341b72468f836ed6c8f#diff-08f993cc40af475663274687b7c326cc6c3031e0db3ac8de7b24624610616be6
此 XNU 版本似乎对应 11.0.1: https://kernelshaman.blogspot.com/2021/01/building-xnu-for-macos-big-sur-1101.html
ulock_wait() 使用 32 位微秒超时,其中 0 表示无限等待或无超时。 ulock_wait2() 使用 64 位纳秒超时,约定相同。
std.Io.Threaded.default_fn_align
常量
std.Io.Threaded.default_PATH
常量
std.Io.Threaded.deferAcceptAfd
函数
fn deferAcceptAfd(t: *Threaded, listen_handle: net.Socket.Handle, info: windows.AFD.LISTEN_RESPONSE_INFO) void
参数
std.Io.Threaded.deinit
函数
pub fn deinit(t: *Threaded) void
参数
t: *Threaded
std.Io.Threaded.destroyParkSem
函数
fn destroyParkSem(_: ?*anyopaque) callconv(.c) void
参数
_: ?*anyopaque
std.Io.Threaded.destroyPipe
函数
fn destroyPipe(pipe: [2]posix.fd_t) void
参数
std.Io.Threaded.deviceIoControl
函数
fn deviceIoControl(o: *const Io.Operation.DeviceIoControl) Io.Cancelable!Io.Operation.DeviceIoControl.Result
参数
o: *const Io.Operation.DeviceIoControl
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Dir
别名
别名目标 std.Io.Dir
std.Io.Threaded.dirAccess
常量
std.Io.Threaded.dirAccessPosix
函数
fn dirAccessPosix( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions, ) Dir.AccessError!void
参数
错误
- AccessDenied
文件不允许请求的
AccessOptions,或路径前缀中的 某个目录不允许搜索。- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- InputOutput
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied
请求了写入权限,但文件不可变。
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirAccessWasi
函数
fn dirAccessWasi( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions, ) Dir.AccessError!void
参数
错误
- AccessDenied
文件不允许请求的
AccessOptions,或路径前缀中的 某个目录不允许搜索。- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- InputOutput
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied
请求了写入权限,但文件不可变。
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirAccessWindows
函数
fn dirAccessWindows( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions, ) Dir.AccessError!void
参数
错误
- AccessDenied
文件不允许请求的
AccessOptions,或路径前缀中的 某个目录不允许搜索。- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- InputOutput
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied
请求了写入权限,但文件不可变。
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirClose
函数
fn dirClose(userdata: ?*anyopaque, dirs: []const Dir) void
参数
userdata: ?*anyopaque
dirs: []const Dir
std.Io.Threaded.dirCreateDir
常量
std.Io.Threaded.dirCreateDirPath
函数
fn dirCreateDirPath( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, ) Dir.CreateDirPathError!Dir.CreatePathStatus
参数
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirCreateDirPathOpen
常量
std.Io.Threaded.dirCreateDirPathOpenPosix
函数
fn dirCreateDirPathOpenPosix( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.OpenOptions, ) Dir.CreateDirPathOpenError!Dir
参数
userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.OpenOptions
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirCreateDirPathOpenWasi
函数
fn dirCreateDirPathOpenWasi( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.OpenOptions, ) Dir.CreateDirPathOpenError!Dir
参数
userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.OpenOptions
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirCreateDirPathOpenWindows
函数
fn dirCreateDirPathOpenWindows( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.OpenOptions, ) Dir.CreateDirPathOpenError!Dir
参数
userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.OpenOptions
错误
- AccessDenied CreateDirError
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- DiskQuota CreateDirError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- LinkQuotaExceeded CreateDirError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound CreateDirError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice CreateDirError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied CreateDirError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem CreateDirError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop CreateDirError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirCreateDirPosix
函数
fn dirCreateDirPosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirCreateDirWasi
函数
fn dirCreateDirWasi(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirCreateDirWindows
函数
fn dirCreateDirWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirCreateFile
常量
std.Io.Threaded.dirCreateFileAtomic
函数
fn dirCreateFileAtomic( userdata: ?*anyopaque, dir: Dir, dest_path: []const u8, options: Dir.CreateFileAtomicOptions, ) Dir.CreateFileAtomicError!File.Atomic
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试创建的文件是正在运行的可执行文件。
- FileNotFound
以下情况之一:
- 某个路径分量不存在。
- 使用了 Cwd,但当前工作目录已被删除。
- 与已打开目录句柄关联的路径已被删除。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。
- NotDir
路径中作为目录使用的某个组成部分实际上不是目录。
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
可用内核内存不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Threaded.dirCreateFilePosix
函数
fn dirCreateFilePosix( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirCreateFileWasi
函数
fn dirCreateFileWasi( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.CreateFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirCreateFileWindows
函数
fn dirCreateFileWindows( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.CreateFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirDeleteDir
常量
std.Io.Threaded.dirDeleteDirPosix
函数
fn dirDeleteDirPosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DirNotEmpty
- FileBusy
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirDeleteDirWasi
函数
fn dirDeleteDirWasi(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DirNotEmpty
- FileBusy
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirDeleteDirWindows
函数
fn dirDeleteDirWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DirNotEmpty
- FileBusy
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirDeleteFile
常量
std.Io.Threaded.dirDeleteFilePosix
函数
fn dirDeleteFilePosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- FileSystem
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirDeleteFileWasi
函数
fn dirDeleteFileWasi(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- FileSystem
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirDeleteFileWindows
函数
fn dirDeleteFileWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- FileSystem
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirDeleteWindows
函数
fn dirDeleteWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, remove_dir: bool) (Dir.DeleteDirError || Dir.DeleteFileError)!void
参数
std.Io.Threaded.dirHardLink
函数
fn dirHardLink( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, options: Dir.HardLinkOptions, ) Dir.HardLinkError!void
参数
userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
options: Dir.HardLinkOptions
错误
- AccessDenied HardLinkError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice HardLinkError
- DiskQuota HardLinkError
- FileNotFound HardLinkError
- HardwareFailure HardLinkError
- LinkQuotaExceeded HardLinkError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NoSpaceLeft HardLinkError
- NotDir HardLinkError
- OperationUnsupported HardLinkError
操作系统或文件系统不支持硬链接。
- PathAlreadyExists HardLinkError
- PermissionDenied HardLinkError
- ReadOnlyFileSystem HardLinkError
- SymLinkLoop HardLinkError
- SystemResources HardLinkError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirOpenDir
常量
std.Io.Threaded.dirOpenDirHaiku
函数
fn dirOpenDirHaiku( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions, ) Dir.OpenError!Dir
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirOpenDirPosix
函数
链接 libc 时,此函数也用于 WASI。
fn dirOpenDirPosix( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions, ) Dir.OpenError!Dir
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirOpenDirWasi
函数
fn dirOpenDirWasi( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions, ) Dir.OpenError!Dir
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirOpenDirWindows
函数
pub fn dirOpenDirWindows( dir: Dir, sub_path_w: []const u16, options: Dir.OpenOptions, ) Dir.OpenError!Dir
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirOpenFile
常量
std.Io.Threaded.dirOpenFilePosix
函数
fn dirOpenFilePosix( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirOpenFileWasi
函数
fn dirOpenFileWasi( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.OpenFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirOpenFileWindows
函数
fn dirOpenFileWindows( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.OpenFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirOpenFileWtf16
函数
pub fn dirOpenFileWtf16( dir_handle: ?windows.HANDLE, sub_path_w: []const u16, flags: Dir.OpenFileOptions, ) File.OpenError!File
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirRead
常量
std.Io.Threaded.dirReadBsd
函数
fn dirReadBsd(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadDarwin
函数
fn dirReadDarwin(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadHaiku
函数
fn dirReadHaiku(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadIllumos
函数
fn dirReadIllumos(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadLink
函数
fn dirReadLink(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Threaded.dirReadLinkPosix
函数
fn dirReadLinkPosix(dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Threaded.dirReadLinkWasi
函数
fn dirReadLinkWasi(dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Threaded.dirReadLinkWindows
函数
fn dirReadLinkWindows(dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize
参数
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
尝试打开的文件是正在运行的可执行文件。
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NotDir
- NotLink
- PermissionDenied
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedReparsePointType
仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。
std.Io.Threaded.dirReadLinux
函数
fn dirReadLinux(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadUnimplemented
函数
fn dirReadUnimplemented(userdata: ?*anyopaque, dir_reader: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadWasi
函数
fn dirReadWasi(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirReadWindows
函数
fn dirReadWindows(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRealPath
常量
std.Io.Threaded.dirRealPathFile
常量
std.Io.Threaded.dirRealPathFilePosix
函数
fn dirRealPathFilePosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.dirRealPathFileWindows
函数
fn dirRealPathFileWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.dirRealPathPosix
函数
fn dirRealPathPosix(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.dirRealPathWindows
函数
fn dirRealPathWindows(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize
参数
错误
- AccessDenied RealPathError
- AntivirusInterference RealPathError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy RealPathError
- FileBusy RealPathError
- FileNotFound RealPathError
- FileSystem RealPathError
- FileTooBig RealPathError
- InputOutput RealPathError
- IsDir RealPathError
- NameTooLong RealPathError
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound RealPathError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RealPathError
- NoSpaceLeft RealPathError
- NotDir RealPathError
- OperationUnsupported RealPathError
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists RealPathError
- PermissionDenied RealPathError
- PipeBusy RealPathError
- ProcessFdQuotaExceeded RealPathError
- SymLinkLoop RealPathError
- SystemFdQuotaExceeded RealPathError
- SystemResources RealPathError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume RealPathError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.dirRename
常量
std.Io.Threaded.dirRenamePosix
函数
fn dirRenamePosix( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenameError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRenamePreserve
函数
fn dirRenamePreserve( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenamePreserveError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice RenameError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound RenameError
- HardwareFailure RenameError
- IsDir RenameError
- LinkQuotaExceeded RenameError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft RenameError
- NotDir RenameError
- OperationUnsupported
操作系统或文件系统不支持原子的不覆盖目标 重命名。
- PathAlreadyExists
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRenamePreserveDarwin
函数
fn dirRenamePreserveDarwin( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenamePreserveError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice RenameError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound RenameError
- HardwareFailure RenameError
- IsDir RenameError
- LinkQuotaExceeded RenameError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft RenameError
- NotDir RenameError
- OperationUnsupported
操作系统或文件系统不支持原子的不覆盖目标 重命名。
- PathAlreadyExists
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRenamePreserveLinux
函数
fn dirRenamePreserveLinux( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenamePreserveError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice RenameError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound RenameError
- HardwareFailure RenameError
- IsDir RenameError
- LinkQuotaExceeded RenameError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft RenameError
- NotDir RenameError
- OperationUnsupported
操作系统或文件系统不支持原子的不覆盖目标 重命名。
- PathAlreadyExists
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRenameWasi
函数
fn dirRenameWasi( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenameError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRenameWindows
函数
fn dirRenameWindows( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenameError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirRenameWindowsInner
函数
fn dirRenameWindowsInner( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, replace_if_exists: bool, ) Dir.RenamePreserveError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。
在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。
- AntivirusInterference RenameError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice RenameError
- DirNotEmpty RenameError
试图替换非空目录。
- DiskQuota RenameError
- FileBusy RenameError
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound RenameError
- HardwareFailure RenameError
- IsDir RenameError
- LinkQuotaExceeded RenameError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound RenameError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice RenameError
- NoSpaceLeft RenameError
- NotDir RenameError
- OperationUnsupported
操作系统或文件系统不支持原子的不覆盖目标 重命名。
- PathAlreadyExists
- PermissionDenied RenameError
- PipeBusy RenameError
- ReadOnlyFileSystem RenameError
- SymLinkLoop RenameError
- SystemResources RenameError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetFileOwner
函数
fn dirSetFileOwner( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, owner: ?File.Uid, group: ?File.Gid, options: Dir.SetFileOwnerOptions, ) Dir.SetFileOwnerError!void
参数
userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
owner: ?File.Uid
group: ?File.Gid
options: Dir.SetFileOwnerOptions
错误
- AccessDenied SetOwnerError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetFilePermissions
函数
fn dirSetFilePermissions( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.SetFilePermissionsOptions, ) Dir.SetFilePermissionsError!void
参数
userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.SetFilePermissionsOptions
错误
- AccessDenied SetPermissionsError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- OperationUnsupported
SetFilePermissionsOptions.follow_symlinks被设为 false,但文件系统或操作系统不允许。- PermissionDenied SetPermissionsError
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemFdQuotaExceeded
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetOwner
常量
std.Io.Threaded.dirSetOwnerPosix
函数
fn dirSetOwnerPosix(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void
参数
错误
- AccessDenied SetOwnerError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetOwnerUnsupported
函数
fn dirSetOwnerUnsupported(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void
参数
错误
- AccessDenied SetOwnerError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetPermissions
常量
std.Io.Threaded.dirSetPermissionsPosix
函数
fn dirSetPermissionsPosix(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void
参数
错误
- AccessDenied SetPermissionsError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- PermissionDenied SetPermissionsError
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetPermissionsWindows
函数
fn dirSetPermissionsWindows(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void
参数
错误
- AccessDenied SetPermissionsError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- PermissionDenied SetPermissionsError
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSetTimestamps
函数
fn dirSetTimestamps( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.SetTimestampsOptions, ) Dir.SetTimestampsError!void
参数
错误
- AccessDenied SetTimestampsError
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- PermissionDenied SetTimestampsError
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem SetTimestampsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirStat
函数
fn dirStat(userdata: ?*anyopaque, dir: Dir) Dir.StatError!Dir.Stat
参数
userdata: ?*anyopaque
dir: Dir
错误
- AccessDenied StatError
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied StatError
- Streaming StatError
尝试对非文件流调用 stat。
- SystemResources StatError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirStatFile
常量
std.Io.Threaded.dirStatFileLinux
函数
fn dirStatFileLinux( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions, ) Dir.StatFileError!File.Stat
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirStatFilePosix
函数
fn dirStatFilePosix( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions, ) Dir.StatFileError!File.Stat
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirStatFileWasi
函数
fn dirStatFileWasi( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions, ) Dir.StatFileError!File.Stat
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirStatFileWindows
函数
fn dirStatFileWindows( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions, ) Dir.StatFileError!File.Stat
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.dirSymLink
常量
std.Io.Threaded.dirSymLinkPosix
函数
fn dirSymLinkPosix( userdata: ?*anyopaque, dir: Dir, target_path: []const u8, sym_link_path: []const u8, flags: Dir.SymLinkFlags, ) Dir.SymLinkError!void
参数
userdata: ?*anyopaque
dir: Dir
target_path: []const u8
sym_link_path: []const u8
flags: Dir.SymLinkFlags
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSymLinkWasi
函数
fn dirSymLinkWasi( userdata: ?*anyopaque, dir: Dir, target_path: []const u8, sym_link_path: []const u8, flags: Dir.SymLinkFlags, ) Dir.SymLinkError!void
参数
userdata: ?*anyopaque
dir: Dir
target_path: []const u8
sym_link_path: []const u8
flags: Dir.SymLinkFlags
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.dirSymLinkWindows
函数
fn dirSymLinkWindows( userdata: ?*anyopaque, dir: Dir, target_path: []const u8, sym_link_path: []const u8, flags: Dir.SymLinkFlags, ) Dir.SymLinkError!void
参数
userdata: ?*anyopaque
dir: Dir
target_path: []const u8
sym_link_path: []const u8
flags: Dir.SymLinkFlags
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- FileNotFound
- FileSystem
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoSpaceLeft
- NotDir
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.Dl
类型
std.Io.Threaded.Dl.deinit
函数
fn deinit(dl: *Dl) void
参数
dl: *Dl
std.Io.Threaded.Dl.deinit
函数
fn deinit(_: Dl) void
参数
_: Dl
std.Io.Threaded.Dl.init
常量
Dl
std.Io.Threaded.Dl.init
常量
Dl
std.Io.Threaded.doNothingSignalHandler
函数
fn doNothingSignalHandler(_: posix.SIG) callconv(.c) void
参数
std.Io.Threaded.dup2
函数
pub fn dup2(old_fd: posix.fd_t, new_fd: posix.fd_t) DupError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ProcessFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.DupError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ProcessFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.Environ
容器
字段
process_environ: process.Environ直接来自操作系统的未修改数据。
exist: Exist = .{}由 mutex 保护,基于 process_environ 进行记忆化缓存。跟踪环境变量是否存在,而忽略其值。
string: String = .{}由 mutex 保护。基于 process_environ 进行记忆化缓存。
zig_progress_file: std.Progress.ParentFileError!File = error.EnvironmentVariableMissingZIG_PROGRESS
err: ?Error = null由 mutex 保护。跟踪尝试扫描环境变量时
发生的问题,若存在。
仅 WASI 上可能发生错误。
std.Io.Threaded.Environ.empty
常量
Environ
std.Io.Threaded.Environ.Error
错误集合
错误
- OutOfMemory Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.Environ.Exist
容器
字段
NO_COLOR: bool = false
CLICOLOR_FORCE: bool = false
std.Io.Threaded.Environ.scan
函数
pub fn scan(environ: *Environ, allocator: Allocator) void
参数
std.Io.Threaded.Environ.String
类型
std.Io.Threaded.environString
函数
pub fn environString(t: *Threaded, comptime name: []const u8) ?[:0]const u8
参数
t: *Threaded
name: []const u8
std.Io.Threaded.ErrInt
常量
std.Io.Threaded.errnoBug
函数
pub fn errnoBug(err: posix.E) Io.UnexpectedError
参数
std.Io.Threaded.eventSet
函数
与 Io.Event.set 相同,但绕过虚函数表。
fn eventSet(event: *Io.Event) void
参数
std.Io.Threaded.eventWait
函数
与 Io.Event.wait 相同,但绕过虚函数表。
fn eventWait(event: *Io.Event) void
参数
std.Io.Threaded.fallbackSeed
函数
pub fn fallbackSeed(aslr_addr: ?*anyopaque, seed: *[Csprng.seed_len]u8) void
参数
std.Io.Threaded.fallbackSeedPosix
函数
fn fallbackSeedPosix(seed: *[Csprng.seed_len]u8) void
参数
std.Io.Threaded.fallbackSeedWasi
函数
fn fallbackSeedWasi(seed: *[Csprng.seed_len]u8) void
参数
std.Io.Threaded.fallbackSeedWindows
函数
fn fallbackSeedWindows(seed: *[Csprng.seed_len]u8) void
参数
std.Io.Threaded.fchdir
函数
pub fn fchdir(fd: posix.fd_t) FchdirError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileSystem
- NotDir
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.FchdirError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileSystem
- NotDir
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fchmodatFallback
函数
fn fchmodatFallback( dir_fd: posix.fd_t, path: [*:0]const u8, mode: posix.mode_t, ) Dir.SetFilePermissionsError!void
参数
错误
- AccessDenied SetPermissionsError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- OperationUnsupported
SetFilePermissionsOptions.follow_symlinks被设为 false,但文件系统或操作系统不允许。- PermissionDenied SetPermissionsError
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemFdQuotaExceeded
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.File
别名
别名目标 std.Io.File
std.Io.Threaded.fileClose
函数
fn fileClose(userdata: ?*anyopaque, files: []const File) void
参数
userdata: ?*anyopaque
files: []const File
std.Io.Threaded.fileDowngradeLock
函数
fn fileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void
参数
userdata: ?*anyopaque
file: File
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileEnableAnsiEscapeCodes
函数
fn fileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void
参数
userdata: ?*anyopaque
file: File
错误
- Canceled Cancelable
调用方请求停止异步操作。
- NotTerminalDevice
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileHardLink
函数
fn fileHardLink( userdata: ?*anyopaque, file: File, new_dir: Dir, new_sub_path: []const u8, options: File.HardLinkOptions, ) File.HardLinkError!void
参数
userdata: ?*anyopaque
file: File
new_dir: Dir
new_sub_path: []const u8
options: File.HardLinkOptions
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DiskQuota
- FileNotFound
- HardwareFailure
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NoSpaceLeft
- NotDir
- OperationUnsupported
操作系统或文件系统不支持硬链接。
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileIsTty
函数
fn fileIsTty(userdata: ?*anyopaque, file: File) Io.Cancelable!bool
参数
userdata: ?*anyopaque
file: File
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.fileLength
函数
fn fileLength(userdata: ?*anyopaque, file: File) File.LengthError!u64
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied StatError
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied StatError
- Streaming StatError
尝试对非文件流调用 stat。
- SystemResources StatError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileLock
函数
fn fileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileMemoryMapCreate
函数
fn fileMemoryMapCreate( userdata: ?*anyopaque, file: File, options: File.MemoryMap.CreateOptions, ) File.MemoryMap.CreateError!File.MemoryMap
参数
错误
- AccessDenied
以下任一情况:
File.Kind不是file。- 文件未以读取方式打开,且启用了读取访问保护。
- 文件未以写入方式打开,且启用了写入访问保护。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput ReadPositionalError
- IsDir ReadPositionalError
尝试将目录文件描述符当作普通文件读取。
- LockViolation ReadPositionalError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- LockedMemoryLimitExceeded
- NotOpenForReading ReadPositionalError
打开文件时未授予读取能力。
- OutOfMemory Error
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- SystemResources ReadPositionalError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable ReadPositionalError
此文件不支持按位置读取。
- WouldBlock ReadPositionalError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileMemoryMapDestroy
函数
fn fileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void
参数
std.Io.Threaded.fileMemoryMapRead
函数
fn fileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileMemoryMapSetLength
函数
fn fileMemoryMapSetLength( userdata: ?*anyopaque, mm: *File.MemoryMap, new_len: usize, ) File.MemoryMap.SetLengthError!void
参数
错误
- AccessDenied
以下任一情况:
File.Kind不是file。- 文件未以读取方式打开,且启用了读取访问保护。
- 文件未以写入方式打开,且启用了写入访问保护。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- LockedMemoryLimitExceeded
- NonResizable SetLengthError
- OperationUnsupported
- OutOfMemory Error
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileMemoryMapWrite
函数
fn fileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void
参数
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.filePathKind
函数
fn filePathKind(t: *Threaded, dir: Dir, sub_path: []const u8) !File.Kind
参数
std.Io.Threaded.fileReadPositional
函数
fn fileReadPositional(userdata: ?*anyopaque, file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileReadPositionalPosix
函数
fn fileReadPositionalPosix(file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileReadPositionalWindows
函数
fn fileReadPositionalWindows(file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileReadStreaming
函数
fn fileReadStreaming(userdata: ?*anyopaque, file: File, data: []const []u8) File.ReadStreamingError!usize
参数
错误
- AccessDenied UnendingError
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- EndOfStream
- InputOutput UnendingError
- IsDir UnendingError
尝试将目录文件描述符当作普通文件读取。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- SocketUnconnected UnendingError
- SystemResources UnendingError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock UnendingError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileReadStreamingPosix
函数
fn fileReadStreamingPosix(file: File, data: []const []u8) File.ReadStreamingError!usize
参数
file: File
data: []const []u8
错误
- AccessDenied UnendingError
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- EndOfStream
- InputOutput UnendingError
- IsDir UnendingError
尝试将目录文件描述符当作普通文件读取。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- SocketUnconnected UnendingError
- SystemResources UnendingError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock UnendingError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileReadStreamingWindows
函数
fn fileReadStreamingWindows(file: File, data: []const []u8) File.ReadStreamingError!usize
参数
file: File
data: []const []u8
错误
- AccessDenied UnendingError
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- EndOfStream
- InputOutput UnendingError
- IsDir UnendingError
尝试将目录文件描述符当作普通文件读取。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- SocketUnconnected UnendingError
- SystemResources UnendingError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock UnendingError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.fileRealPath
常量
std.Io.Threaded.fileRealPathPosix
函数
fn fileRealPathPosix(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize
参数
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.fileRealPathWindows
函数
fn fileRealPathWindows(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize
参数
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.fileSeekBy
函数
fn fileSeekBy(userdata: ?*anyopaque, file: File, offset: i64) File.SeekError!void
参数
错误
- AccessDenied
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.Threaded.fileSeekTo
函数
fn fileSeekTo(userdata: ?*anyopaque, file: File, offset: u64) File.SeekError!void
参数
错误
- AccessDenied
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.Threaded.fileSetLength
函数
fn fileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileTooBig
- InputOutput
- NonResizable
- PermissionDenied
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileSetOwner
函数
fn fileSetOwner(userdata: ?*anyopaque, file: File, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileSetPermissions
函数
fn fileSetPermissions(userdata: ?*anyopaque, file: File, permissions: File.Permissions) File.SetPermissionsError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileSetTimestamps
函数
fn fileSetTimestamps( userdata: ?*anyopaque, file: File, options: File.SetTimestampsOptions, ) File.SetTimestampsError!void
参数
错误
- AccessDenied
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileStat
常量
std.Io.Threaded.fileStatLinux
函数
fn fileStatLinux(userdata: ?*anyopaque, file: File) File.StatError!File.Stat
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- Streaming
尝试对非文件流调用 stat。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileStatPosix
函数
fn fileStatPosix(userdata: ?*anyopaque, file: File) File.StatError!File.Stat
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- Streaming
尝试对非文件流调用 stat。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileStatWasi
函数
fn fileStatWasi(userdata: ?*anyopaque, file: File) File.StatError!File.Stat
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- Streaming
尝试对非文件流调用 stat。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileStatWindows
函数
fn fileStatWindows(userdata: ?*anyopaque, file: File) File.StatError!File.Stat
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- Streaming
尝试对非文件流调用 stat。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileSupportsAnsiEscapeCodes
函数
fn fileSupportsAnsiEscapeCodes(userdata: ?*anyopaque, file: File) Io.Cancelable!bool
参数
userdata: ?*anyopaque
file: File
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.fileSync
常量
std.Io.Threaded.fileSyncPosix
函数
fn fileSyncPosix(userdata: ?*anyopaque, file: File) File.SyncError!void
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- InputOutput
- NoSpaceLeft
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileSyncWasi
函数
fn fileSyncWasi(userdata: ?*anyopaque, file: File) File.SyncError!void
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- InputOutput
- NoSpaceLeft
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileSyncWindows
函数
fn fileSyncWindows(userdata: ?*anyopaque, file: File) File.SyncError!void
参数
userdata: ?*anyopaque
file: File
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- InputOutput
- NoSpaceLeft
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileTryLock
函数
fn fileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.fileUnlock
函数
fn fileUnlock(userdata: ?*anyopaque, file: File) void
参数
userdata: ?*anyopaque
file: File
std.Io.Threaded.fileWriteFilePositional
函数
fn fileWriteFilePositional( userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *File.Reader, limit: Io.Limit, offset: u64, ) File.WriteFilePositionalError!usize
参数
userdata: ?*anyopaque
file: File
header: []const u8
file_reader: *File.Reader
limit: Io.Limit
offset: u64
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- CorruptedData WriteFileError
在 FreeBSD 上使用 copy_file_range 时可能发生。
- DeviceBusy Error
- DiskQuota Error
- EndOfStream WriteFileError
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- ReadFailed WriteFileError
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unimplemented WriteFileError
描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。
- Unseekable
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.fileWriteFileStreaming
函数
fn fileWriteFileStreaming( userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *File.Reader, limit: Io.Limit, ) File.Writer.WriteFileError!usize
参数
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- CorruptedData
在 FreeBSD 上使用 copy_file_range 时可能发生。
- DeviceBusy Error
- DiskQuota Error
- EndOfStream
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- ReadFailed
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unimplemented
描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.fileWritePositional
函数
fn fileWritePositional( userdata: ?*anyopaque, file: File, header: []const u8, data: []const []const u8, splat: usize, offset: u64, ) File.WritePositionalError!usize
参数
userdata: ?*anyopaque
file: File
header: []const u8
data: []const []const u8
splat: usize
offset: u64
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.fileWriteStreaming
函数
fn fileWriteStreaming( userdata: ?*anyopaque, file: File, header: []const u8, data: []const []const u8, splat: usize, ) File.Writer.Error!usize
参数
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy Error
- DiskQuota Error
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.fileWriteStreamingWindows
函数
fn fileWriteStreamingWindows(file: File, buffer: []const u8) File.Writer.Error!usize
参数
file: File
buffer: []const u8
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy Error
- DiskQuota Error
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.flagApc
函数
fn flagApc(userdata: ?*anyopaque, _: *windows.IO_STATUS_BLOCK, _: windows.ULONG) align(apc_align) callconv(.winapi) void
参数
std.Io.Threaded.forkBail
函数
fork 子进程调用此函数,向 fork 父进程报告错误。 然后子进程退出。
fn forkBail(fd: posix.fd_t, err: ForkBailError) noreturn
参数
fd: posix.fd_t
err: ForkBailError
std.Io.Threaded.ForkBailError
错误集合
fork() 与 execv() 之间可能发生的错误。
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem SpawnError
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidBatchScriptArg SpawnError
仅限 Windows。执行
.bat或.cmd脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。- NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
- CR 会被
cmd.exe移除,因此执行后所有 CR 码点都会丢失。
- InvalidExe SpawnError
- InvalidName SpawnError
- InvalidProcessGroupId SpawnError
- InvalidUserId SpawnError
- InvalidWtf8 SpawnError
仅限 Windows。提供的
cwd或argv为无效 WTF-8。 https://wtf-8.codeberg.page/- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice SpawnError
仅限 POSIX。选择了
StdIo.ignore,且打开/dev/null时返回 ENODEV。- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OperationUnsupported SpawnError
操作系统不支持创建子进程。
- OutOfMemory SpawnError
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied SpawnError
- PipeBusy OpenError
- ProcessAlreadyExec SpawnError
尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。
- ProcessFdQuotaExceeded SpawnError
- ReadOnlyFileSystem OpenError
- ResourceLimitReached SpawnError
- SymLinkLoop SpawnError
- SystemFdQuotaExceeded SpawnError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume SpawnError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.fstat_sym
常量
std.Io.Threaded.fstatat_sym
常量
std.Io.Threaded.ftruncate_sym
常量
std.Io.Threaded.futexWait
函数
fn futexWait(userdata: ?*anyopaque, ptr: *const u32, expected: u32, timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.futexWaitUncancelable
函数
fn futexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void
参数
userdata: ?*anyopaque
ptr: *const u32
expected: u32
std.Io.Threaded.futexWake
函数
fn futexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void
参数
userdata: ?*anyopaque
ptr: *const u32
max_waiters: u32
std.Io.Threaded.Future
容器
尾随数据:
- context
- result
字段
std.Io.Threaded.Future.contextPointer
函数
fn contextPointer(future: *Future) [*]u8
参数
future: *Future
std.Io.Threaded.Future.create
函数
创建出的 Future 中,Future.runnable.node 为 undefined。
fn create( gpa: Allocator, result_len: usize, result_alignment: Alignment, context: []const u8, context_alignment: Alignment, func: *const fn (context: *const anyopaque, result: *anyopaque) void, ) Allocator.Error!*Future
参数
gpa: Allocator
result_len: usize
result_alignment: Alignment
context: []const u8
context_alignment: Alignment
func: *const fn (context: *const anyopaque, result: *anyopaque) void
错误
- OutOfMemory
std.Io.Threaded.Future.destroy
函数
fn destroy(future: *Future, gpa: Allocator) void
参数
std.Io.Threaded.Future.resultPointer
函数
fn resultPointer(future: *Future) [*]u8
参数
future: *Future
std.Io.Threaded.Future.start
函数
fn start(r: *Runnable, thread: *Thread, t: *Threaded) void
参数
std.Io.Threaded.Future.Status
容器
字段
tag: enum(u2) {
/// future 已排队或正在运行(取决于是否设置 `thread`)。
pending = 0b00,
/// 类似 `pending`,但该 future 正被等待。已填充 `Future.awaiter`。
pending_awaited = 0b01,
/// 类似于 `pending`,但 future 正在取消。`Future.awaiter` 已填充。
pending_canceled = 0b11,
/// future 已完成。除非 future 因已确认的取消请求而终止,
/// 此时 `thread` 为 `.all_ones`,否则 `thread` 为 `.null`。
done = 0b10,
}此枚举的取值经过选择,使 await/cancel 分别只需与 0b01 和 0b11 按位或。
这确实会覆盖 .done,但并无妨碍,因为标签为 .done 时,
仅有等待方仍在引用此 Future。
thread: Thread.PackedPtrfuture 开始执行时,此字段以原子方式从 null 更新为运行该 Future 的线程,
以便取消逻辑知道要取消哪个线程。
std.Io.Threaded.Future.waitForCancelWithSignaling
函数
调用方已取消 future。thread 是当前运行该 future 的线程。
必要时将取消请求通知 thread,并等待 future 完成,以 num_completed
从 0 增加到 1 为标志;必要时定期向 thread 发送信号,
使其从可取消的系统调用中解除阻塞。
fn waitForCancelWithSignaling( future: *Future, t: *Threaded, num_completed: *std.atomic.Value(u32), thread: ?*Thread, ) void
参数
std.Io.Threaded.getCngDevice
函数
fn getCngDevice(t: *Threaded) Io.RandomSecureError!windows.HANDLE
参数
t: *Threaded
错误
- Canceled Cancelable
调用方请求停止异步操作。
- EntropyUnavailable
std.Io.Threaded.getDevNullFd
函数
fn getDevNullFd(t: *Threaded) !posix.fd_t
参数
t: *Threaded
std.Io.Threaded.GetFinalPathNameByHandle
函数
返回句柄对应的规范化路径。
使用 GetFinalPathNameByHandleFormat 指定路径包含 NT 还是 DOS 卷名,例如 \Device\HarddiskVolume0\foo.txt 与 C:\foo.txt。
若选择 DOS 卷名格式,注意此函数不会给结果路径添加 \\?\ 前缀。
pub fn GetFinalPathNameByHandle( hFile: windows.HANDLE, fmt: GetFinalPathNameByHandleFormat, out_buffer: []u16, ) GetFinalPathNameByHandleError![]u16
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
卷不包含可识别的文件系统。文件系统驱动程序 可能未加载,或卷可能已损坏。
用法示例
test GetFinalPathNameByHandle {
if (builtin.os.tag != .windows)
return;
// 任何文件均可
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const handle = tmp.dir.handle;
var buffer: [windows.PATH_MAX_WIDE]u16 = undefined;
// 使用足够大的大小进行检查
const nt_path = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Nt }, &buffer);
_ = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Dos }, &buffer);
const required_len_in_u16 = nt_path.len + @divExact(@intFromPtr(nt_path.ptr) - @intFromPtr(&buffer), 2) + 1;
// 检查容量不足的情况
try std.testing.expectError(error.NameTooLong, GetFinalPathNameByHandle(handle, .{ .volume_name = .Nt }, buffer[0 .. required_len_in_u16 - 1]));
try std.testing.expectError(error.NameTooLong, GetFinalPathNameByHandle(handle, .{ .volume_name = .Dos }, buffer[0 .. required_len_in_u16 - 1]));
// 使用刚好足够的大小进行检查
_ = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Nt }, buffer[0..required_len_in_u16]);
_ = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Dos }, buffer[0..required_len_in_u16]);
}
std.Io.Threaded.GetFinalPathNameByHandleError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
卷不包含可识别的文件系统。文件系统驱动程序 可能未加载,或卷可能已损坏。
std.Io.Threaded.GetFinalPathNameByHandleFormat
容器
指定 GetFinalPathNameByHandle 结果中卷路径的格式。
默认为 DOS 卷名。
字段
volume_name: enum {
/// 格式化为 DOS 卷名
Dos,
/// 格式化为 NT 卷名称
Nt,
} = .Dos
std.Io.Threaded.getLocalDevicePathType
函数
仅与 Win32 到 NT 路径转换有关。
断言 path 的类型为 Dir.path.Win32PathType.local_device。
fn getLocalDevicePathType(comptime T: type, path: []const T) LocalDevicePathType
参数
T: type
path: []const T
std.Io.Threaded.getNamedPipeDevice
函数
fn getNamedPipeDevice(t: *Threaded) !windows.HANDLE
参数
t: *Threaded
std.Io.Threaded.getNulDevice
函数
fn getNulDevice(t: *Threaded) !windows.HANDLE
参数
t: *Threaded
std.Io.Threaded.getParkTid
函数
fn getParkTid() ParkTid
std.Io.Threaded.getRandomFd
函数
fn getRandomFd(t: *Threaded) Io.RandomSecureError!posix.fd_t
参数
t: *Threaded
错误
- Canceled Cancelable
调用方请求停止异步操作。
- EntropyUnavailable
std.Io.Threaded.global_single_threaded
常量
通常,应用程序负责选择 Io 实现,库代码应接受 Io 参数,而不是访问此声明。多数代码应完全避免引用此声明。
不过,在调试等某些情况下,可能希望硬编码对此 Io 实现的引用。
此实例不支持并发或取消。
*Threaded
std.Io.Threaded.global_single_threaded_instance
变量
Threaded
std.Io.Threaded.Group
容器
字段
std.Io.Threaded.Group.awaiter
函数
返回类型正确、指向 Io.Group.state 字段的指针。这里使用二级指针是
有意的,因为 state 字段本身保存指针,而此函数返回
指向该字段的指针。
整个组完成时,如果 status 表示存在等待方,最后一个
任务必须递增此 u32,并对其执行 futex 唤醒以通知等待方。
fn awaiter(g: Group) **std.atomic.Value(u32)
参数
g: Group
std.Io.Threaded.Group.cancelThreads
函数
假定调用者已原子更新组状态,标记取消, 并将此取消通知已运行的所有线程。
fn cancelThreads(g: Group, t: *Threaded) bool
参数
std.Io.Threaded.Group.signalAllCanceledSyscalls
函数
使用 Thread.signalCanceledSyscall 向此组中仍阻塞于系统调用、尚未观察到取消请求的线程发送信号。
若可能需要更多信号,则返回 true;此时调用者必须在延迟后再次调用。
fn signalAllCanceledSyscalls(g: Group, t: *Threaded) bool
参数
std.Io.Threaded.Group.status
函数
返回指向 Io.Group.token 字段、类型正确的指针。
状态表示组内待处理任务数、是否 已取消,以及是否已被等待。
注意,Status 的零值有意表示初始组状态,即为空
且没有等待者。这是 Io.Group 的要求。
fn status(g: Group) *std.atomic.Value(Status)
参数
g: Group
std.Io.Threaded.Group.Status
容器
字段
num_running: @Int(.unsigned, @bitSizeOf(usize) - 2)
have_awaiter: bool
canceled: bool
std.Io.Threaded.Group.Task
容器
字段
std.Io.Threaded.Group.Task.contextPointer
函数
fn contextPointer(task: *Task) [*]u8
参数
task: *Task
std.Io.Threaded.Group.Task.create
函数
创建的 Task 中,Task.runnable.node 为 undefined。
fn create( gpa: Allocator, group: Group, context: []const u8, context_alignment: Alignment, func: *const fn (context: *const anyopaque) void, ) Allocator.Error!*Task
参数
gpa: Allocator
group: Group
context: []const u8
context_alignment: Alignment
func: *const fn (context: *const anyopaque) void
错误
- OutOfMemory
std.Io.Threaded.Group.Task.destroy
函数
fn destroy(task: *Task, gpa: Allocator) void
参数
std.Io.Threaded.Group.Task.start
函数
fn start(r: *Runnable, thread: *Thread, t: *Threaded) void
参数
std.Io.Threaded.Group.waitForCancelWithSignaling
函数
调用方已取消 g。必要时通知正在处理该组的线程,
并等待 g 完成,以 num_completed 从 0 递增
至 1 为标志;必要时定期向线程发送信号,
使其从可取消的系统调用中解除阻塞。
skip_signals 表示已知当前没有线程处理该组,
因此不需要通知或信号。
fn waitForCancelWithSignaling( g: Group, t: *Threaded, num_completed: *std.atomic.Value(u32), skip_signals: bool, ) void
参数
std.Io.Threaded.groupAsync
函数
fn groupAsync( userdata: ?*anyopaque, type_erased: *Io.Group, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque) void, ) void
参数
std.Io.Threaded.groupAsyncEager
函数
fn groupAsyncEager( start: *const fn (context: *const anyopaque) void, context: *const anyopaque, ) void
参数
start: *const fn (context: *const anyopaque) void
context: *const anyopaque
std.Io.Threaded.groupAwait
函数
fn groupAwait(userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.groupCancel
函数
fn groupCancel(userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque) void
参数
std.Io.Threaded.groupConcurrent
函数
fn groupConcurrent( userdata: ?*anyopaque, type_erased: *Io.Group, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque) void, ) Io.ConcurrentError!void
参数
userdata: ?*anyopaque
type_erased: *Io.Group
context: []const u8
context_alignment: Alignment
start: *const fn (context: *const anyopaque) void
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.Threaded.have_accept4
常量
std.Io.Threaded.have_copy_file_range
常量
std.Io.Threaded.have_fchmod
常量
std.Io.Threaded.have_fchmodat_flags
常量
std.Io.Threaded.have_fchmodat2
常量
std.Io.Threaded.have_fchown
常量
std.Io.Threaded.have_fcntl
常量
std.Io.Threaded.have_fcopyfile
别名
std.Io.Threaded.have_flock
常量
std.Io.Threaded.have_flock_open_flags
常量
std.Io.Threaded.have_futex
常量
std.Io.Threaded.have_mmap
常量
std.Io.Threaded.have_networking
常量
std.Io.Threaded.have_poll
常量
std.Io.Threaded.have_preadv
常量
std.Io.Threaded.have_sendfile
常量
std.Io.Threaded.have_sendmmsg
常量
std.Io.Threaded.have_sig_io
常量
std.Io.Threaded.have_sig_pipe
常量
std.Io.Threaded.have_wait4
常量
std.Io.Threaded.have_waitid
常量
std.Io.Threaded.HostName
别名
别名目标 std.Io.net.HostName
std.Io.Threaded.inheritParentDir
函数
fn inheritParentDir(userdata: ?*anyopaque, handle: Dir.Handle) Io.InheritParentHandleError!Dir
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedOperation
std.Io.Threaded.inheritParentFile
函数
fn inheritParentFile( userdata: ?*anyopaque, handle: File.Handle, flags: File.Flags, ) Io.InheritParentHandleError!File
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedOperation
std.Io.Threaded.inheritParentHandle
函数
fn inheritParentHandle(handle: posix.fd_t) Io.InheritParentHandleError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedOperation
std.Io.Threaded.init
函数
相关项:
pub fn init( gpa: Allocator, options: InitOptions, ) Threaded
参数
gpa: Allocator必须线程安全。仅用于以下函数:
Io.VTable.asyncIo.VTable.concurrentIo.VTable.groupAsyncIo.VTable.groupConcurrent如果不使用这些函数,则可在此传入Allocator.failing。
options: InitOptions
std.Io.Threaded.init_single_threaded
常量
静态初始化,使 Io.VTable.concurrent 调用会以
error.ConcurrencyUnavailable 失败。
采用此种初始化时:
- 取消请求无效。
- 可以安全调用
deinit,但没有必要。
Threaded
std.Io.Threaded.initLockedStderr
函数
fn initLockedStderr(t: *Threaded, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.InitOptions
容器
字段
stack_size: usize = std.Thread.SpawnConfig.default_stack_size影响为线程进行内存映射的字节数。
async_limit: ?Io.Limit = null分派异步任务时的线程池最大大小,不包括主线程。在达到限制之前,若全部线程都忙,调用 Io.async 会创建新线程,并永久加入线程池。达到限制之后,若全部线程都忙,调用 Io.async 会立即执行任务。
默认值为逻辑处理器核心数减一。
I/O 实例开始使用后,由 Threaded.mutex 保护。参见 setAsyncLimit。
concurrent_limit: Io.Limit = .unlimited用于分派并发任务的线程池大小上限,不包括主线程。
达到此上限之前,调用 Io.concurrent 会增加线程
池大小。
超过此数量后,调用 Io.concurrent 返回 error.ConcurrencyUnavailable。
argv0: Argv0 = .empty影响以下操作:
- OpenBSD 和 Haiku 上的
processExecutablePath。
environ: process.Environ = .empty影响以下操作:
fileIsTty- OpenBSD 和 Haiku 上的
processExecutablePath(读取“PATH”)。 processSpawn、processSpawnPath、processReplace、processReplacePath
disable_memory_mapping: bool = false若设为 true,则 File.MemoryMap API 始终采用回退路径。
std.Io.Threaded.io
函数
pub fn io(t: *Threaded) Io
参数
t: *Threaded
std.Io.Threaded.Io
别名
别名目标 std.Io
std.Io.Threaded.iovlen_t
类型
此处为 usize 或 u32,二者均可。因此对写入文件
和发送网络消息均使用同一个 addBuf 函数。
std.Io.Threaded.IpAddress
别名
别名目标 std.Io.net.IpAddress
std.Io.Threaded.is_darwin
常量
std.Io.Threaded.is_debug
常量
std.Io.Threaded.is_windows
常量
std.Io.Threaded.isCygwinPty
函数
fn isCygwinPty(file: File) Io.Cancelable!bool
参数
file: File
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.isTty
函数
fn isTty(file: File) Io.Cancelable!bool
参数
file: File
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.join
函数
fn join(t: *Threaded) void
参数
t: *Threaded
std.Io.Threaded.linkat
函数
fn linkat( old_dir: posix.fd_t, old_path: [*:0]const u8, new_dir: posix.fd_t, new_path: [*:0]const u8, flags: u32, ) File.HardLinkError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DiskQuota
- FileNotFound
- HardwareFailure
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NoSpaceLeft
- NotDir
- OperationUnsupported
操作系统或文件系统不支持硬链接。
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.linux_copy_file_range_sys
常量
std.Io.Threaded.linux_copy_file_range_use_c
常量
std.Io.Threaded.linux_statx_check
常量
std.os.linux.STATX
std.Io.Threaded.linux_statx_request
常量
std.os.linux.STATX
std.Io.Threaded.LocalDevicePathType
容器
字段
local_device\\.\(路径分隔符可为 \ 或 /)
verbatim\\?\
转换为 NT 路径时,前缀之后的所有内容均保持
不变,\\?\ 替换为 \??\。
fake_verbatim\\?\,但并非所有路径分隔符都是 \。
这似乎会被识别为前缀,但不遵循“原样”
语义,即若将 //?/C:/foo 转换为 NT 路径,
会得到 \??\C:\foo:路径会被规范化,//?/ 不会
被视为最终路径的一部分。
std.Io.Threaded.lockStderr
函数
fn lockStderr(userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.lookupDns
函数
fn lookupDns( t: *Threaded, lookup_canon_name: []const u8, rc: *const HostName.ResolvConf, resolved: *Io.Queue(HostName.LookupResult), options: HostName.LookupOptions, ) (HostName.LookupError || Io.QueueClosedError)!void
参数
t: *Threaded
lookup_canon_name: []const u8
rc: *const HostName.ResolvConf
resolved: *Io.Queue(HostName.LookupResult)
options: HostName.LookupOptions
std.Io.Threaded.lookupDnsSearch
函数
fn lookupDnsSearch( t: *Threaded, host_name: HostName, resolved: *Io.Queue(HostName.LookupResult), options: HostName.LookupOptions, ) (HostName.LookupError || Io.QueueClosedError)!void
参数
t: *Threaded
host_name: HostName
resolved: *Io.Queue(HostName.LookupResult)
options: HostName.LookupOptions
std.Io.Threaded.LookupDnsWindows
容器
字段
std.Io.Threaded.LookupDnsWindows.completed
函数
fn completed( pQueryContext: ?*anyopaque, pQueryResults: *windows.DNS.QUERY.RESULT, ) callconv(.winapi) void
参数
std.Io.Threaded.LookupDnsWindows.completedFallible
函数
fn completedFallible(lookup_dns: *LookupDnsWindows) (Io.QueueClosedError || Io.Cancelable)!void
参数
lookup_dns: *LookupDnsWindows
std.Io.Threaded.lookupHosts
函数
fn lookupHosts( t: *Threaded, host_name: HostName, resolved: *Io.Queue(HostName.LookupResult), options: HostName.LookupOptions, ) !void
参数
t: *Threaded
host_name: HostName
resolved: *Io.Queue(HostName.LookupResult)
options: HostName.LookupOptions
std.Io.Threaded.lookupHostsReader
函数
fn lookupHostsReader( t: *Threaded, host_name: HostName, resolved: *Io.Queue(HostName.LookupResult), options: HostName.LookupOptions, reader: *Io.Reader, ) error{ ReadFailed, Canceled, UnknownHostName, Closed }!void
参数
t: *Threaded
host_name: HostName
resolved: *Io.Queue(HostName.LookupResult)
options: HostName.LookupOptions
reader: *Io.Reader
错误
- Canceled
- Closed
- ReadFailed
- UnknownHostName
std.Io.Threaded.lseek_sym
常量
std.Io.Threaded.max_iovecs_len
常量
std.Io.Threaded.max_windows_kernel_bug_retries
常量
通过重试规避多个内核缺陷。
std.Io.Threaded.mmap_sym
常量
std.Io.Threaded.mmSyncRead
函数
fn mmSyncRead(file: File, memory: []u8, offset: u64) File.ReadPositionalError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.mmSyncWrite
函数
fn mmSyncWrite(file: File, memory: []u8, offset: u64) File.WritePositionalError!void
参数
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.mountmgrIsVolumeName
函数
等价于 mountmgr.h 中的 MOUNTMGR_IS_VOLUME_NAME 宏
fn mountmgrIsVolumeName(name: []const u16) bool
参数
name: []const u16
用法示例
test mountmgrIsVolumeName {
@setEvalBranchQuota(2000);
const L = std.unicode.utf8ToUtf16LeStringLiteral;
try std.testing.expect(mountmgrIsVolumeName(L("\\\\?\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}")));
try std.testing.expect(mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}")));
try std.testing.expect(mountmgrIsVolumeName(L("\\\\?\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}\\")));
try std.testing.expect(mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}\\")));
try std.testing.expect(!mountmgrIsVolumeName(L("\\\\.\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}")));
try std.testing.expect(!mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}\\foo")));
try std.testing.expect(!mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58}")));
}
std.Io.Threaded.mutexLock
函数
与 Io.Mutex.lock 相同,但绕过虚函数表。
pub fn mutexLock(m: *Io.Mutex) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.mutexLockUncancelable
函数
与 Io.Mutex.lockUncancelable 相同,但绕过虚函数表。
pub fn mutexLockUncancelable(m: *Io.Mutex) void
参数
std.Io.Threaded.mutexUnlock
函数
与 Io.Mutex.unlock 相同,但绕过虚函数表。
pub fn mutexUnlock(m: *Io.Mutex) void
参数
std.Io.Threaded.nanosecondsFromPosix
函数
pub fn nanosecondsFromPosix(timespec: *const posix.timespec) i96
参数
std.Io.Threaded.native_os
常量
std.Io.Threaded.need_unpark_flag
常量
NetBSD 和 Illumos 上的接口存在问题,可能产生虚假的解除停放。严格来说,接口本身不会如此,但信号引起的解除阻塞无法与之区分,而 libpthread 经常留下待处理的解除停放操作。 因此,仅在这些目标上,需要传递一个标志,跟踪线程是否“确实”被解除停放。
std.Io.Threaded.net
别名
别名目标 std.Io.net
std.Io.Threaded.netAcceptPosix
函数
fn netAcceptPosix(userdata: ?*anyopaque, listen_fd: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket
参数
错误
- BlockedByFirewall
防火墙规则禁止连接。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
曾有传入连接,但在接受调用之前, 远端对等方已将其终止。
- NetworkDown
网络子系统已失败。
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolFailure
- SocketNotListening
从未调用
listen,或已调用shutdown,后者可能发生于 本调用阻塞期间。因此,可将shutdown用作 并发取消机制。- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。
std.Io.Threaded.netAcceptWindows
函数
fn netAcceptWindows(userdata: ?*anyopaque, listen_handle: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket
参数
错误
- BlockedByFirewall
防火墙规则禁止连接。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
曾有传入连接,但在接受调用之前, 远端对等方已将其终止。
- NetworkDown
网络子系统已失败。
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolFailure
- SocketNotListening
从未调用
listen,或已调用shutdown,后者可能发生于 本调用阻塞期间。因此,可将shutdown用作 并发取消机制。- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。
std.Io.Threaded.netBindIpPosix
函数
fn netBindIpPosix( userdata: ?*anyopaque, address: *const IpAddress, options: IpAddress.BindOptions, ) IpAddress.BindError!net.Socket
参数
错误
- AccessDenied
该地址受到保护,当前用户没有绑定它的权限。
- AddressFamilyUnsupported
该地址对于套接字的地址族无效。
- AddressInUse
地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。
- AddressUnavailable
请求了不存在的接口,或请求的地址不是本地地址。
- Canceled Cancelable
调用方请求停止异步操作。
- NetworkDown
用于到达目标的本地网络接口已离线。
- OptionUnsupported
Io 实现不支持某个
BindOptions。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netBindIpWindows
函数
fn netBindIpWindows( userdata: ?*anyopaque, address: *const IpAddress, options: IpAddress.BindOptions, ) IpAddress.BindError!net.Socket
参数
错误
- AccessDenied
该地址受到保护,当前用户没有绑定它的权限。
- AddressFamilyUnsupported
该地址对于套接字的地址族无效。
- AddressInUse
地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。
- AddressUnavailable
请求了不存在的接口,或请求的地址不是本地地址。
- Canceled Cancelable
调用方请求停止异步操作。
- NetworkDown
用于到达目标的本地网络接口已离线。
- OptionUnsupported
Io 实现不支持某个
BindOptions。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netClose
函数
fn netClose(userdata: ?*anyopaque, sockets: []const net.Socket) void
参数
std.Io.Threaded.netConnectIpPosix
函数
fn netConnectIpPosix( userdata: ?*anyopaque, address: *const IpAddress, options: IpAddress.ConnectOptions, ) IpAddress.ConnectError!net.Socket
参数
错误
- AccessDenied
用户尝试连接广播地址,但未启用套接字广播标志;或 连接请求因本地防火墙规则而失败。
- AddressFamilyUnsupported
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionPending
- ConnectionRefused
- ConnectionResetByPeer
- HostUnreachable
- NetworkDown
- NetworkUnreachable
- OptionUnsupported
Io 实现不支持某个
ConnectOptions选项。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Timeout
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.netConnectIpWindows
函数
fn netConnectIpWindows( userdata: ?*anyopaque, address: *const IpAddress, options: IpAddress.ConnectOptions, ) IpAddress.ConnectError!net.Socket
参数
错误
- AccessDenied
用户尝试连接广播地址,但未启用套接字广播标志;或 连接请求因本地防火墙规则而失败。
- AddressFamilyUnsupported
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionPending
- ConnectionRefused
- ConnectionResetByPeer
- HostUnreachable
- NetworkDown
- NetworkUnreachable
- OptionUnsupported
Io 实现不支持某个
ConnectOptions选项。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Timeout
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.netConnectUnixPosix
函数
fn netConnectUnixPosix( userdata: ?*anyopaque, address: *const net.UnixAddress, ) net.UnixAddress.ConnectError!net.Socket.Handle
参数
userdata: ?*anyopaque
address: *const net.UnixAddress
错误
- AccessDenied
- AddressFamilyUnsupported
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionRefused
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ProtocolUnsupportedBySystem
- ReadOnlyFileSystem
- SocketModeUnsupported
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Threaded.netConnectUnixWindows
函数
fn netConnectUnixWindows( userdata: ?*anyopaque, address: *const net.UnixAddress, ) net.UnixAddress.ConnectError!net.Socket.Handle
参数
userdata: ?*anyopaque
address: *const net.UnixAddress
错误
- AccessDenied
- AddressFamilyUnsupported
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionRefused
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ProtocolUnsupportedBySystem
- ReadOnlyFileSystem
- SocketModeUnsupported
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Threaded.netInterfaceName
函数
fn netInterfaceName(userdata: ?*anyopaque, interface: net.Interface) net.Interface.NameError!net.Interface.Name
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
index超出范围。- NameTooLong
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netInterfaceNameResolve
函数
fn netInterfaceNameResolve( userdata: ?*anyopaque, name: *const net.Interface.Name, ) net.Interface.Name.ResolveError!net.Interface
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netListenIpPosix
函数
fn netListenIpPosix( userdata: ?*anyopaque, address: *const IpAddress, options: IpAddress.ListenOptions, ) IpAddress.ListenError!net.Socket
参数
错误
- AccessDenied
该地址受到保护,当前用户没有绑定它的权限。
- AddressFamilyUnsupported
操作系统不支持请求的地址族(IPv4 或 IPv6)。
- AddressInUse
地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。
- AddressUnavailable
请求了不存在的接口,或请求的地址不是本地地址。
- Canceled Cancelable
调用方请求停止异步操作。
- NetworkDown
用于到达目标的本地网络接口已离线。
- OptionUnsupported
Io 实现不支持某个
ListenOptions。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netListenIpWindows
函数
fn netListenIpWindows( userdata: ?*anyopaque, address: *const IpAddress, options: IpAddress.ListenOptions, ) IpAddress.ListenError!net.Socket
参数
错误
- AccessDenied
该地址受到保护,当前用户没有绑定它的权限。
- AddressFamilyUnsupported
操作系统不支持请求的地址族(IPv4 或 IPv6)。
- AddressInUse
地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。
- AddressUnavailable
请求了不存在的接口,或请求的地址不是本地地址。
- Canceled Cancelable
调用方请求停止异步操作。
- NetworkDown
用于到达目标的本地网络接口已离线。
- OptionUnsupported
Io 实现不支持某个
ListenOptions。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netListenUnixPosix
函数
fn netListenUnixPosix( userdata: ?*anyopaque, address: *const net.UnixAddress, options: net.UnixAddress.ListenOptions, ) net.UnixAddress.ListenError!net.Socket.Handle
参数
错误
- AccessDenied
- AddressFamilyUnsupported
- AddressInUse
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netListenUnixWindows
函数
fn netListenUnixWindows( userdata: ?*anyopaque, address: *const net.UnixAddress, options: net.UnixAddress.ListenOptions, ) net.UnixAddress.ListenError!net.Socket.Handle
参数
错误
- AccessDenied
- AddressFamilyUnsupported
- AddressInUse
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netLookup
函数
fn netLookup( userdata: ?*anyopaque, host_name: HostName, resolved: *Io.Queue(HostName.LookupResult), options: HostName.LookupOptions, ) net.HostName.LookupError!void
参数
userdata: ?*anyopaque
host_name: HostName
resolved: *Io.Queue(HostName.LookupResult)
options: HostName.LookupOptions
错误
- AccessDenied BindError
该地址受到保护,当前用户没有绑定它的权限。
- AddressFamilyUnsupported BindError
该地址对于套接字的地址族无效。
- AddressInUse BindError
地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。
- AddressUnavailable BindError
请求了不存在的接口,或请求的地址不是本地地址。
- Canceled Cancelable
调用方请求停止异步操作。
- DetectingNetworkConfigurationFailed
无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。
- InvalidDnsAAAARecord
- InvalidDnsARecord
- InvalidDnsCnameRecord
- NameServerFailure
- NetworkDown BindError
用于到达目标的本地网络接口已离线。
- NoAddressReturned
- OptionUnsupported BindError
Io 实现不支持某个
BindOptions。- ProcessFdQuotaExceeded BindError
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily BindError
- ProtocolUnsupportedBySystem BindError
- ResolvConfParseFailed
- SocketModeUnsupported BindError
- SystemFdQuotaExceeded BindError
已达到系统范围内已打开文件的总数上限。
- SystemResources BindError
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnknownHostName
std.Io.Threaded.netLookupFallible
函数
fn netLookupFallible( t: *Threaded, host_name: HostName, resolved: *Io.Queue(HostName.LookupResult), options: HostName.LookupOptions, ) (net.HostName.LookupError || Io.QueueClosedError)!void
参数
t: *Threaded
host_name: HostName
resolved: *Io.Queue(HostName.LookupResult)
options: HostName.LookupOptions
std.Io.Threaded.netRead
函数
fn netRead(socket_handle: net.Socket.Handle, data: [][]u8, control: []u8) net.Stream.Reader.Error!net.Stream.ReadResult
参数
错误
- AccessDenied Error
文件描述符不具有读取所需权限。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown Error
- SocketUnconnected Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netReadPosix
函数
fn netReadPosix(fd: net.Socket.Handle, data: [][]u8, control: []u8) net.Stream.Reader.Error!net.Stream.ReadResult
参数
错误
- AccessDenied Error
文件描述符不具有读取所需权限。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown Error
- SocketUnconnected Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netReadWindows
函数
fn netReadWindows(socket_handle: net.Socket.Handle, data: [][]u8) net.Stream.Reader.Error!usize
参数
错误
- AccessDenied Error
文件描述符不具有读取所需权限。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown Error
- SocketUnconnected Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netReceiveOneWindows
函数
fn netReceiveOneWindows( t: *Threaded, socket_handle: net.Socket.Handle, message: *net.IncomingMessage, data_buffer: []u8, flags: net.ReceiveFlags, ) net.Socket.ReceiveError!void
参数
t: *Threaded
socket_handle: net.Socket.Handle
message: *net.IncomingMessage
data_buffer: []u8
flags: net.ReceiveFlags
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
发送方意外关闭了网络连接。
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- MessageOversize Error
此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。
- NetworkDown Error
用于到达目标的本地网络接口已离线。
- PortUnreachable Error
此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。
- ProcessFdQuotaExceeded Error
已达到每进程可打开文件描述符数量上限。
- SocketUnconnected Error
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemFdQuotaExceeded Error
已达到系统范围内已打开文件的总数上限。
- SystemResources Error
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netReceivePosix
函数
fn netReceivePosix( socket_handle: net.Socket.Handle, message: *net.IncomingMessage, data_buffer: []u8, flags: net.ReceiveFlags, nonblocking: bool, ) (net.Socket.ReceiveError || error{WouldBlock})!void
参数
socket_handle: net.Socket.Handle
message: *net.IncomingMessage
data_buffer: []u8
flags: net.ReceiveFlags
nonblocking: bool
std.Io.Threaded.netReceiveWindows
类型函数
fn netReceiveWindows( t: *Threaded, socket_handle: net.Socket.Handle, message_buffer: []net.IncomingMessage, data_buffer: []u8, flags: net.ReceiveFlags, ) struct { ?net.Socket.ReceiveError, usize }
参数
t: *Threaded
socket_handle: net.Socket.Handle
message_buffer: []net.IncomingMessage
data_buffer: []u8
flags: net.ReceiveFlags
std.Io.Threaded.netSendManyPosix
函数
fn netSendManyPosix( socket_handle: net.Socket.Handle, messages: []net.OutgoingMessage, flags: u32, ) (net.Socket.SendError || error{WouldBlock})!usize
参数
std.Io.Threaded.netSendOnePosix
函数
fn netSendOnePosix( t: *Threaded, socket_handle: net.Socket.Handle, message: *net.OutgoingMessage, flags: u32, ) (net.Socket.SendError || error{WouldBlock})!void
参数
std.Io.Threaded.netSendOneWindows
函数
fn netSendOneWindows( t: *Threaded, socket_handle: net.Socket.Handle, message: *net.OutgoingMessage, flags: net.SendFlags, ) net.Socket.SendError!void
参数
错误
- AccessDenied Error
尝试向网络/广播地址发送数据, 却将其当作单播地址。
- AddressFamilyUnsupported Error
操作系统或协议不支持该地址族。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionRefused Error
目标地址未在侦听;对于无连接消息也可能发生此情况。
- ConnectionResetByPeer Error
网络会话被接收方意外关闭。
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- FastOpenAlreadyInProgress Error
另一个 TCP 快速打开已在进行。
- HostUnreachable Error
可到达网络,但没有到主机的路由。
- MessageOversize Error
此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。
- NetworkDown Error
用于到达目标的本地网络接口已离线。
- NetworkUnreachable Error
没有到网络的路由。
- SocketUnconnected Error
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemResources Error
网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。
可用内核内存不足时也会发生此错误。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netSendPosix
类型函数
fn netSendPosix( t: *Threaded, socket_handle: net.Socket.Handle, messages: []net.OutgoingMessage, flags: net.SendFlags, nonblocking: bool, ) struct { ?(net.Socket.SendError || error{WouldBlock}), usize }
参数
std.Io.Threaded.netSendWindows
类型函数
fn netSendWindows( t: *Threaded, socket_handle: net.Socket.Handle, messages: []net.OutgoingMessage, flags: net.SendFlags, ) struct { ?net.Socket.SendError, usize }
参数
std.Io.Threaded.netShutdownPosix
函数
fn netShutdownPosix(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
- ConnectionResetByPeer
- NetworkDown
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netShutdownWindows
函数
fn netShutdownWindows(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
- ConnectionResetByPeer
- NetworkDown
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netSocketCreatePair
函数
fn netSocketCreatePair( userdata: ?*anyopaque, options: net.Socket.CreatePairOptions, ) net.Socket.CreatePairError![2]net.Socket
参数
userdata: ?*anyopaque
options: net.Socket.CreatePairOptions
错误
- AccessDenied
- AddressFamilyUnsupported
- Canceled Cancelable
调用方请求停止异步操作。
- OperationUnsupported
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。在释放足够资源前, 无法创建套接字。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netWriteFile
函数
fn netWriteFile( userdata: ?*anyopaque, socket_handle: net.Socket.Handle, header: []const u8, file_reader: *File.Reader, limit: Io.Limit, ) net.Stream.Writer.WriteFileError!usize
参数
userdata: ?*anyopaque
socket_handle: net.Socket.Handle
header: []const u8
file_reader: *File.Reader
limit: Io.Limit
错误
- AddressFamilyUnsupported Error
传入地址的 sa_family 字段未包含正确的地址族。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionRefused Error
目标地址未在监听。
- ConnectionResetByPeer Error
网络会话被接收方意外关闭。
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- EndOfStream
已到达正在读取的文件末尾。
- FastOpenAlreadyInProgress Error
另一个 TCP 快速打开已在进行。
- HostUnreachable Error
可到达网络,但没有到主机的路由。
- NetworkDown Error
用于到达目标的本地网络接口已关闭。
- NetworkUnreachable Error
没有到网络的路由。
- ReadFailed
源
File.Reader失败; 详细诊断信息见该结构体。- SocketNotBound Error
- SocketUnconnected Error
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemResources Error
网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。
可用内核内存不足时也会发生此错误。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unimplemented
Io实现无法提供更高效的文件到套接字传输路径; 调用者应退回基于读取的复制。参见Io.Writer.sendFile。
std.Io.Threaded.netWritePosix
函数
fn netWritePosix( fd: net.Socket.Handle, header: []const u8, data: []const []const u8, splat: usize, control: []const u8, ) net.Stream.Writer.Error!usize
参数
错误
- AddressFamilyUnsupported Error
传入地址的 sa_family 字段未包含正确的地址族。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionRefused Error
目标地址未在监听。
- ConnectionResetByPeer Error
网络会话被接收方意外关闭。
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- FastOpenAlreadyInProgress Error
另一个 TCP 快速打开已在进行。
- HostUnreachable Error
可到达网络,但没有到主机的路由。
- NetworkDown Error
用于到达目标的本地网络接口已关闭。
- NetworkUnreachable Error
没有到网络的路由。
- SocketNotBound Error
- SocketUnconnected Error
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemResources Error
网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。
可用内核内存不足时也会发生此错误。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.netWriteWindows
函数
fn netWriteWindows( handle: net.Socket.Handle, header: []const u8, data: []const []const u8, splat: usize, control: []const u8, ) net.Stream.Writer.Error!usize
参数
handle: net.Socket.Handle
header: []const u8
data: []const []const u8
splat: usize
control: []const u8
错误
- AddressFamilyUnsupported Error
传入地址的 sa_family 字段未包含正确的地址族。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionRefused Error
目标地址未在监听。
- ConnectionResetByPeer Error
网络会话被接收方意外关闭。
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- FastOpenAlreadyInProgress Error
另一个 TCP 快速打开已在进行。
- HostUnreachable Error
可到达网络,但没有到主机的路由。
- NetworkDown Error
用于到达目标的本地网络接口已关闭。
- NetworkUnreachable Error
没有到网络的路由。
- SocketNotBound Error
- SocketUnconnected Error
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemResources Error
网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。
可用内核内存不足时也会发生此错误。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.now
函数
fn now(userdata: ?*anyopaque, clock: Io.Clock) Io.Timestamp
参数
std.Io.Threaded.nowPosix
函数
fn nowPosix(clock: Io.Clock) Io.Timestamp
参数
std.Io.Threaded.nowWasi
函数
fn nowWasi(clock: Io.Clock) Io.Timestamp
参数
std.Io.Threaded.nowWindows
函数
fn nowWindows(clock: Io.Clock) Io.Timestamp
参数
std.Io.Threaded.ntReadFileResult
函数
fn ntReadFileResult(io_status_block: *const windows.IO_STATUS_BLOCK) !usize
参数
io_status_block: *const windows.IO_STATUS_BLOCK
std.Io.Threaded.ntWriteFileResult
函数
fn ntWriteFileResult(io_status_block: *const windows.IO_STATUS_BLOCK) !usize
参数
io_status_block: *const windows.IO_STATUS_BLOCK
std.Io.Threaded.NullFile
类型
std.Io.Threaded.NullFile.deinit
函数
fn deinit(this: *@This()) void
参数
this: *@This()
std.Io.Threaded.NullFile.deinit
函数
fn deinit(this: @This()) void
参数
this: @This()
std.Io.Threaded.NullFile.deinit
函数
fn deinit(this: *@This()) void
参数
this: *@This()
std.Io.Threaded.open_sym
常量
std.Io.Threaded.openat_sym
常量
std.Io.Threaded.OpenError
错误集合
错误
- AccessDenied
- AntivirusInterference
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
- NoDevice
- NotDir
- PathAlreadyExists
- PipeBusy
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Threaded.OpenFile
函数
TODO: 在所有位置内联此逻辑,并删除此函数。
fn OpenFile(sub_path_w: []const u16, options: OpenFileOptions) OpenError!windows.HANDLE
参数
sub_path_w: []const u16
options: OpenFileOptions
错误
- AccessDenied
- AntivirusInterference
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileNotFound
- IsDir
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
- NoDevice
- NotDir
- PathAlreadyExists
- PipeBusy
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
std.Io.Threaded.OpenFileOptions
容器
字段
access_mask: windows.ACCESS_MASK
dir: ?windows.HANDLE = null
sa: ?*const windows.SECURITY_ATTRIBUTES = null
share_access: windows.FILE.SHARE = .VALID_FLAGS
creation: windows.FILE.CREATE_DISPOSITION
filter: Filter = .non_directory_only
follow_symlinks: bool = true如果为 false,则尝试以重解析点形式打开路径,不解引用。 默认为 true。
std.Io.Threaded.OpenFileOptions.Filter
容器
字段
std.Io.Threaded.openSocketAfd
函数
fn openSocketAfd(family: ws2_32.ADDRESS_FAMILY, options: IpAddress.BindOptions) !net.Socket.Handle
参数
family: ws2_32.ADDRESS_FAMILY
options: IpAddress.BindOptions
std.Io.Threaded.openSocketPosix
函数
fn openSocketPosix( family: posix.sa_family_t, options: IpAddress.BindOptions, ) error{ AddressFamilyUnsupported, ProtocolUnsupportedBySystem, ProcessFdQuotaExceeded, SystemFdQuotaExceeded, SystemResources, ProtocolUnsupportedByAddressFamily, SocketModeUnsupported, OptionUnsupported, Unexpected, Canceled, }!posix.socket_t
参数
family: posix.sa_family_t
options: IpAddress.BindOptions
错误
- AddressFamilyUnsupported
- Canceled
- OptionUnsupported
- ProcessFdQuotaExceeded
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
- SystemResources
- Unexpected
std.Io.Threaded.operate
函数
fn operate(userdata: ?*anyopaque, operation: Io.Operation) Io.Cancelable!Io.Operation.Result
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.park
函数
fn park( timeout: Io.Timeout, addr_hint: ?*const anyopaque, unpark_flag: if (need_unpark_flag) *UnparkFlag else void, ) error{Timeout}!void
参数
timeout: Io.Timeout
addr_hint: ?*const anyopaque此值不影响语义,但可能允许操作系统优化该操作。
unpark_flag: if (need_unpark_flag) *UnparkFlag else void
错误
- Timeout
std.Io.Threaded.park_sem
变量
std.c.sem_id
std.Io.Threaded.parking_futex
命名空间
std.Io.Threaded.parking_futex.Bucket
容器
字段
num_waiters: std.atomic.Value(u32)
mutex: ParkingMutex保护 waiters。
waiters: std.DoublyLinkedList
_: void align(std.atomic.cache_line) = {}避免桶之间的伪共享。
std.Io.Threaded.parking_futex.Bucket.init
常量
Bucket
std.Io.Threaded.parking_futex.bucketForAddress
函数
fn bucketForAddress(address: usize) *Bucket
参数
address: usize
std.Io.Threaded.parking_futex.bucketForAddress.buckets
变量
长度必须为二的幂。此数组越长,不同 futex 之间
发生争用的可能性越小。此长度似乎能合理平衡
争用与内存用量:假定 Bucket 为 128 字节(由于缓存行
对齐),这里使用 32 KiB 内存。
[256]Bucket
std.Io.Threaded.parking_futex.removeCanceledWaiter
函数
fn removeCanceledWaiter(waiter: *Waiter) void
参数
waiter: *Waiter
std.Io.Threaded.parking_futex.wait
函数
fn wait(ptr: *const u32, expect: u32, uncancelable: bool, timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.parking_futex.Waiter
容器
字段
node: std.DoublyLinkedList.Node
address: usize
tid: ParkTid
thread_status: *std.atomic.Value(Thread.Status)线程等待时,thread_status.cancelation 为 .parked。
以原子方式将其更新为 .none 或 .canceling 的唯一线程负责:
unpark_flag: if (need_unpark_flag) *UnparkFlag else void
std.Io.Threaded.parking_futex.wake
函数
fn wake(ptr: *const u32, max_waiters: u32) void
参数
ptr: *const u32
max_waiters: u32
std.Io.Threaded.parking_sleep
命名空间
std.Io.Threaded.parking_sleep.sleep
函数
fn sleep(timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.ParkingMutex
容器
字段
std.Io.Threaded.ParkingMutex.init
常量
ParkingMutex
std.Io.Threaded.ParkingMutex.lock
函数
fn lock(m: *ParkingMutex) void
参数
m: *ParkingMutex
std.Io.Threaded.ParkingMutex.State
容器
字段
std.Io.Threaded.ParkingMutex.State.fromWaiter
函数
返回 w 正在竞争锁的锁定状态。
若 w 为 null,则返回 .locked_once。
fn fromWaiter(w: ?*Waiter) State
参数
w: ?*Waiter
std.Io.Threaded.ParkingMutex.State.waiter
函数
返回等待者链表的头部。s == .unlocked 时调用属于非法操作。
fn waiter(s: State) ?*Waiter
参数
s: State
std.Io.Threaded.ParkingMutex.unlock
函数
fn unlock(m: *ParkingMutex) void
参数
m: *ParkingMutex
std.Io.Threaded.ParkingMutex.Waiter
容器
字段
std.Io.Threaded.ParkTid
类型
std.Io.Threaded.parseReadLinkPath
函数
fn parseReadLinkPath(path: []const u16, is_relative: bool, out_buffer: []u16) error{NameTooLong}![]u16
参数
path: []const u16
is_relative: bool
out_buffer: []u16
错误
- NameTooLong
std.Io.Threaded.pathToPosix
函数
pub fn pathToPosix(file_path: []const u8, buffer: *[posix.PATH_MAX]u8) Dir.PathNameError![:0]u8
参数
错误
- BadPathName
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- NameTooLong
提供的缓冲区过小, 无法容纳路径名时返回。
std.Io.Threaded.Pid
类型
std.Io.Threaded.pipe2
函数
pub fn pipe2(flags: posix.O) PipeError![2]posix.fd_t
参数
错误
- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.PipeError
错误集合
错误
- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.PipeFile
类型
std.Io.Threaded.PipeFile.deinit
函数
fn deinit(this: *@This()) void
参数
this: *@This()
std.Io.Threaded.PipeFile.deinit
函数
fn deinit(this: @This()) void
参数
this: @This()
std.Io.Threaded.poll_buffer_len
常量
此值恰好与 NtWaitForMultipleObjects 接受的 最大句柄数相同。POSIX 系统上的 poll() 也使用此值。
std.Io.Threaded.posix
别名
别名目标 std.posix
std.Io.Threaded.PosixAddress
容器
字段
std.Io.Threaded.posixAddressFamily
函数
pub fn posixAddressFamily(a: *const IpAddress) posix.sa_family_t
参数
a: *const IpAddress
std.Io.Threaded.posixBind
函数
fn posixBind( socket_fd: posix.socket_t, addr: *const posix.sockaddr, addr_len: posix.socklen_t, ) !void
参数
std.Io.Threaded.posixBindUnix
函数
fn posixBindUnix( fd: posix.socket_t, addr: *const posix.sockaddr, addr_len: posix.socklen_t, ) !void
参数
std.Io.Threaded.posixConnect
函数
fn posixConnect( socket_fd: posix.socket_t, addr: *const posix.sockaddr, addr_len: posix.socklen_t, ) !void
参数
std.Io.Threaded.posixConnectUnix
函数
fn posixConnectUnix( fd: posix.socket_t, addr: *const posix.sockaddr, addr_len: posix.socklen_t, ) !void
参数
std.Io.Threaded.posixExec
函数
fn posixExec( exe: process.ReplaceOptions.Exe, argv: [*:null]?[*:0]const u8, expand_arg0: process.ArgExpansion, env_block: process.Environ.PosixBlock, PATH: []const u8, ) process.ReplaceError
参数
exe: process.ReplaceOptions.Exe
argv: [*:null]?[*:0]const u8
expand_arg0: process.ArgExpansion
env_block: process.Environ.PosixBlock
PATH: []const u8
std.Io.Threaded.posixExecveat
函数
此函数忽略 PATH 环境变量。
pub fn posixExecveat( dir: posix.fd_t, path: ?[*:0]const u8, argv: [*:null]const ?[*:0]const u8, env_block: process.Environ.PosixBlock, ) process.ReplaceError
参数
dir: posix.fd_t
path: ?[*:0]const u8
argv: [*:null]const ?[*:0]const u8
env_block: process.Environ.PosixBlock
std.Io.Threaded.posixFchmodat
函数
fn posixFchmodat( t: *Threaded, dir_fd: posix.fd_t, path: [*:0]const u8, mode: posix.mode_t, flags: u32, ) Dir.SetFilePermissionsError!void
参数
错误
- AccessDenied SetPermissionsError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- OperationUnsupported
SetFilePermissionsOptions.follow_symlinks被设为 false,但文件系统或操作系统不允许。- PermissionDenied SetPermissionsError
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemFdQuotaExceeded
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.posixFchown
函数
fn posixFchown(fd: posix.fd_t, uid: posix.uid_t, gid: posix.gid_t) File.SetOwnerError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.posixGetSockName
函数
fn posixGetSockName( socket_fd: posix.fd_t, addr: *posix.sockaddr, addr_len: *posix.socklen_t, ) !void
参数
std.Io.Threaded.posixSeekTo
函数
fn posixSeekTo(fd: posix.fd_t, offset: u64) File.SeekError!void
参数
错误
- AccessDenied
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.Threaded.posixSocketModeProtocol
类型函数
pub fn posixSocketModeProtocol(family: posix.sa_family_t, mode: net.Socket.Mode, protocol: ?net.Protocol) !struct { u32, u32 }
参数
std.Io.Threaded.posixStatFile
函数
fn posixStatFile(dir_fd: posix.fd_t, sub_path: [:0]const u8, flags: u32) Dir.StatFileError!File.Stat
参数
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ReadOnlyFileSystem OpenError
- Streaming StatError
尝试对非文件流调用 stat。
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.pread_sym
常量
std.Io.Threaded.preadv_sym
常量
std.Io.Threaded.process
别名
别名目标 std.process
std.Io.Threaded.processCurrentPath
函数
fn processCurrentPath(userdata: ?*anyopaque, buffer: []u8) process.CurrentPathError!usize
参数
userdata: ?*anyopaque
buffer: []u8
错误
- Canceled Cancelable
调用方请求停止异步操作。
- CurrentDirUnlinked
在 Windows 上不可能发生。在 WASI 上始终返回。
- NameTooLong
缓冲区过小,无法容纳当前路径。
- PathExceedsLimit
受底层 libc 或系统调用实现限制,无法获取当前路径。换用更大缓冲区重试也不会成功。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.processCurrentPathPosix
函数
fn processCurrentPathPosix(buffer: []u8) process.CurrentPathError!usize
参数
buffer: []u8
错误
- Canceled Cancelable
调用方请求停止异步操作。
- CurrentDirUnlinked
在 Windows 上不可能发生。在 WASI 上始终返回。
- NameTooLong
缓冲区过小,无法容纳当前路径。
- PathExceedsLimit
受底层 libc 或系统调用实现限制,无法获取当前路径。换用更大缓冲区重试也不会成功。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.processExecutableOpen
函数
fn processExecutableOpen(userdata: ?*anyopaque, flags: Dir.OpenFileOptions) process.OpenExecutableError!File
参数
userdata: ?*anyopaque
flags: Dir.OpenFileOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem ExecutablePathBaseError
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InputOutput ExecutablePathBaseError
- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice OpenError
- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- NotLink ExecutablePathBaseError
- OperationUnsupported ExecutablePathBaseError
操作系统不支持可执行文件获取自身 路径。
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied OpenError
- PipeBusy OpenError
- ProcessFdQuotaExceeded OpenError
- ProcessNotFound ExecutablePathBaseError
- ReadOnlyFileSystem OpenError
- SymLinkLoop OpenError
- SystemFdQuotaExceeded OpenError
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume ExecutablePathBaseError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.processExecutablePath
函数
fn processExecutablePath(userdata: ?*anyopaque, out_buffer: []u8) process.ExecutablePathError!usize
参数
userdata: ?*anyopaque
out_buffer: []u8
错误
- AccessDenied ExecutablePathBaseError
- AntivirusInterference ExecutablePathBaseError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName ExecutablePathBaseError
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy ExecutablePathBaseError
- FileNotFound ExecutablePathBaseError
- FileSystem ExecutablePathBaseError
- FileTooBig ExecutablePathBaseError
- InputOutput ExecutablePathBaseError
- IsDir ExecutablePathBaseError
- NameTooLong
- NetworkNotFound ExecutablePathBaseError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice ExecutablePathBaseError
- NoSpaceLeft ExecutablePathBaseError
- NotDir ExecutablePathBaseError
- NotLink ExecutablePathBaseError
- OperationUnsupported ExecutablePathBaseError
操作系统不支持可执行文件获取自身 路径。
- PathAlreadyExists ExecutablePathBaseError
- PermissionDenied ExecutablePathBaseError
- PipeBusy ExecutablePathBaseError
- ProcessFdQuotaExceeded ExecutablePathBaseError
- ProcessNotFound ExecutablePathBaseError
- SymLinkLoop ExecutablePathBaseError
- SystemFdQuotaExceeded ExecutablePathBaseError
- SystemResources ExecutablePathBaseError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume ExecutablePathBaseError
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.processReplace
函数
fn processReplace(userdata: ?*anyopaque, options: process.ReplaceOptions) process.ReplaceError
参数
userdata: ?*anyopaque
options: process.ReplaceOptions
std.Io.Threaded.processSetCurrentDir
函数
fn processSetCurrentDir(userdata: ?*anyopaque, dir: Dir) process.SetCurrentDirError!void
参数
userdata: ?*anyopaque
dir: Dir
错误
- AccessDenied
- BadPathName
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- FileSystem
- NameTooLong
- NoDevice
- NotDir
- OperationUnsupported
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
std.Io.Threaded.processSetCurrentPath
函数
fn processSetCurrentPath(userdata: ?*anyopaque, path: []const u8) process.SetCurrentPathError!void
参数
userdata: ?*anyopaque
path: []const u8
错误
- AccessDenied
- BadPathName
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- FileSystem
- InvalidWtf8
仅限 Windows。路径不是有效的 WTF-8。 https://wtf-8.codeberg.page/
- NameTooLong
- NoDevice
- NotDir
- OperationUnsupported
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.processSpawn
常量
std.Io.Threaded.processSpawnDarwin
函数
fn processSpawnDarwin(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child
参数
userdata: ?*anyopaque
options: process.SpawnOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidBatchScriptArg
仅限 Windows。执行
.bat或.cmd脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。- NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
- CR 会被
cmd.exe移除,因此执行后所有 CR 码点都会丢失。
- InvalidExe
- InvalidName
- InvalidProcessGroupId
- InvalidUserId
- InvalidWtf8
仅限 Windows。提供的
cwd或argv为无效 WTF-8。 https://wtf-8.codeberg.page/- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
仅限 POSIX。选择了
StdIo.ignore,且打开/dev/null时返回 ENODEV。- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OperationUnsupported
操作系统不支持创建子进程。
- OutOfMemory
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy OpenError
- ProcessAlreadyExec
尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem OpenError
- ResourceLimitReached
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.processSpawnPosix
函数
fn processSpawnPosix(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child
参数
userdata: ?*anyopaque
options: process.SpawnOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidBatchScriptArg
仅限 Windows。执行
.bat或.cmd脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。- NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
- CR 会被
cmd.exe移除,因此执行后所有 CR 码点都会丢失。
- InvalidExe
- InvalidName
- InvalidProcessGroupId
- InvalidUserId
- InvalidWtf8
仅限 Windows。提供的
cwd或argv为无效 WTF-8。 https://wtf-8.codeberg.page/- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
仅限 POSIX。选择了
StdIo.ignore,且打开/dev/null时返回 ENODEV。- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OperationUnsupported
操作系统不支持创建子进程。
- OutOfMemory
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy OpenError
- ProcessAlreadyExec
尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem OpenError
- ResourceLimitReached
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.processSpawnUnsupported
函数
fn processSpawnUnsupported(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child
参数
userdata: ?*anyopaque
options: process.SpawnOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidBatchScriptArg
仅限 Windows。执行
.bat或.cmd脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。- NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
- CR 会被
cmd.exe移除,因此执行后所有 CR 码点都会丢失。
- InvalidExe
- InvalidName
- InvalidProcessGroupId
- InvalidUserId
- InvalidWtf8
仅限 Windows。提供的
cwd或argv为无效 WTF-8。 https://wtf-8.codeberg.page/- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
仅限 POSIX。选择了
StdIo.ignore,且打开/dev/null时返回 ENODEV。- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OperationUnsupported
操作系统不支持创建子进程。
- OutOfMemory
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy OpenError
- ProcessAlreadyExec
尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem OpenError
- ResourceLimitReached
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.processSpawnWindows
函数
fn processSpawnWindows(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child
参数
userdata: ?*anyopaque
options: process.SpawnOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidBatchScriptArg
仅限 Windows。执行
.bat或.cmd脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。- NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
- CR 会被
cmd.exe移除,因此执行后所有 CR 码点都会丢失。
- InvalidExe
- InvalidName
- InvalidProcessGroupId
- InvalidUserId
- InvalidWtf8
仅限 Windows。提供的
cwd或argv为无效 WTF-8。 https://wtf-8.codeberg.page/- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
仅限 POSIX。选择了
StdIo.ignore,且打开/dev/null时返回 ENODEV。- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OperationUnsupported
操作系统不支持创建子进程。
- OutOfMemory
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy OpenError
- ProcessAlreadyExec
尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem OpenError
- ResourceLimitReached
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.progressParentFile
函数
fn progressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File
参数
userdata: ?*anyopaque
错误
- EnvironmentVariableMissing
- UnrecognizedFormat
- UnsupportedOperation
std.Io.Threaded.pwrite_sym
常量
std.Io.Threaded.pwritev_sym
常量
std.Io.Threaded.QueryObjectName
函数
pub fn QueryObjectName(handle: windows.HANDLE, out_buffer: []u16) QueryObjectNameError![]u16
参数
错误
- AccessDenied
- InvalidHandle
- NameTooLong
- Unexpected
用法示例
test QueryObjectName {
if (builtin.os.tag != .windows)
return;
// 任意文件均可;规范化适用于 NTFS 联接点和符号链接,硬链接仍保留为独立路径。
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const handle = tmp.dir.handle;
var out_buffer: [windows.PATH_MAX_WIDE]u16 = undefined;
const result_path = try QueryObjectName(handle, &out_buffer);
const required_len_in_u16 = result_path.len + @divExact(@intFromPtr(result_path.ptr) - @intFromPtr(&out_buffer), 2) + 1;
// 大小不足
try std.testing.expectError(error.NameTooLong, QueryObjectName(handle, out_buffer[0 .. required_len_in_u16 - 1]));
// 恰好足够的大小
_ = try QueryObjectName(handle, out_buffer[0..required_len_in_u16]);
}
std.Io.Threaded.QueryObjectNameError
错误集合
错误
- AccessDenied
- InvalidHandle
- NameTooLong
- Unexpected
std.Io.Threaded.random
函数
fn random(userdata: ?*anyopaque, buffer: []u8) void
参数
userdata: ?*anyopaque
buffer: []u8
std.Io.Threaded.RandomFile
类型
std.Io.Threaded.RandomFile.deinit
函数
fn deinit(this: @This()) void
参数
this: @This()
std.Io.Threaded.randomMainThread
函数
fn randomMainThread(t: *Threaded, buffer: []u8) void
参数
t: *Threaded
buffer: []u8
std.Io.Threaded.randomSecure
函数
fn randomSecure(userdata: ?*anyopaque, buffer: []u8) Io.RandomSecureError!void
参数
userdata: ?*anyopaque
buffer: []u8
错误
- Canceled Cancelable
调用方请求停止异步操作。
- EntropyUnavailable
std.Io.Threaded.readFilePositionalWindows
函数
fn readFilePositionalWindows(file: File, buffer: []u8, offset: u64) File.ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Threaded.readIntFd
函数
fn readIntFd(fd: posix.fd_t) !ErrInt
参数
std.Io.Threaded.realPathPosix
函数
fn realPathPosix(fd: posix.fd_t, out_buffer: []u8) File.RealPathError!usize
参数
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.realPathWindows
函数
fn realPathWindows(h_file: windows.HANDLE, out_buffer: []u8) File.RealPathError!usize
参数
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.realPathWindowsBuf
函数
fn realPathWindowsBuf(h_file: windows.HANDLE, out_buffer: []u8, wtf16_buffer: []u16) File.RealPathError!usize
参数
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.Threaded.recancel
函数
fn recancel(userdata: ?*anyopaque) void
参数
userdata: ?*anyopaque
std.Io.Threaded.recancelInner
函数
fn recancelInner() void
std.Io.Threaded.recoverableOsBugDetected
函数
pub fn recoverableOsBugDetected() void
std.Io.Threaded.renameat
函数
fn renameat( old_dir: posix.fd_t, old_sub_path: [*:0]const u8, new_dir: posix.fd_t, new_sub_path: [*:0]const u8, ) Dir.RenameError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DirNotEmpty
试图替换非空目录。
- DiskQuota
- FileBusy
尝试移动或替换的文件是正在运行的可执行文件。
- FileNotFound
- HardwareFailure
- IsDir
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- PermissionDenied
- PipeBusy
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.Runnable
容器
字段
std.Io.Threaded.scanEnviron
函数
fn scanEnviron(t: *Threaded) void
参数
t: *Threaded
std.Io.Threaded.sendfile_sym
常量
std.Io.Threaded.setAsyncLimit
函数
pub fn setAsyncLimit(t: *Threaded, new_limit: Io.Limit) void
参数
std.Io.Threaded.setCloexec
函数
fn setCloexec(fd: posix.fd_t) error{ Canceled, Unexpected }!void
参数
错误
- Canceled
- Unexpected
std.Io.Threaded.setPermissionsPosix
函数
fn setPermissionsPosix(fd: posix.fd_t, mode: posix.mode_t) File.SetPermissionsError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.setSocketOptionAfd
函数
fn setSocketOptionAfd(socket: net.Socket.Handle, level: i32, opt_name: u32, opt_val: anytype) !void
参数
std.Io.Threaded.setSocketOptionPosix
函数
fn setSocketOptionPosix(fd: posix.fd_t, level: i32, opt_name: u32, option: u32) !void
参数
std.Io.Threaded.setTimestampToPosix
函数
pub fn setTimestampToPosix(set_ts: File.SetTimestamp) posix.timespec
参数
set_ts: File.SetTimestamp
std.Io.Threaded.setUnparkFlag
函数
必须在 unpark 前调用。调用后,线程随时可能被解除停驻,
因此调用者不得引用该线程栈上的值。
fn setUnparkFlag(f: *UnparkFlag) void
参数
f: *UnparkFlag
std.Io.Threaded.sleep
函数
fn sleep(userdata: ?*anyopaque, timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.sleepNanosleep
函数
fn sleepNanosleep(t: *Threaded, timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.sleepPosix
函数
fn sleepPosix(timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.sleepWasi
函数
fn sleepWasi(t: *Threaded, timeout: Io.Timeout) Io.Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.sliceToPrefixedFileW
函数
与 wToPrefixedFileW 相同,但接受 WTF-8 编码路径。
https://wtf-8.codeberg.page/
pub fn sliceToPrefixedFileW(dir: ?windows.HANDLE, path: []const u8, options: Wtf16ToPrefixedFileWOptions) Wtf8ToPrefixedFileWError!WindowsPathSpace
参数
错误
- AccessDenied Wtf16ToPrefixedFileWError
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound Wtf16ToPrefixedFileWError
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.socket_flags_unsupported
常量
std.Io.Threaded.socketOptionAfd
函数
fn socketOptionAfd(socket: net.Socket.Handle, mode: windows.AFD.SOCKOPT_INFO.Mode, level: i32, opt_name: u32, opt_val: []u8) !void
参数
std.Io.Threaded.spawnDarwin
函数
fn spawnDarwin( t: *Threaded, mode: enum { spawn, replace }, exe: process.ReplaceOptions.Exe, argv: [*:null]?[*:0]const u8, cwd: process.Child.Cwd, env_block: process.Environ.PosixBlock, expand_arg0: process.ArgExpansion, progress_node: std.Progress.Node, stdin: process.SpawnOptions.StdIo, stdout: process.SpawnOptions.StdIo, stderr: process.SpawnOptions.StdIo, inherit_dirs: []const Dir, inherit_files: []const File, pgid: ?posix.pid_t, start_suspended: bool, PATH: []const u8, ) (process.SpawnError || process.ReplaceError)!Spawned
参数
t: *Threaded
mode: enum { spawn, replace }
exe: process.ReplaceOptions.Exe
argv: [*:null]?[*:0]const u8
cwd: process.Child.Cwd
env_block: process.Environ.PosixBlock
expand_arg0: process.ArgExpansion
progress_node: std.Progress.Node
stdin: process.SpawnOptions.StdIo
stdout: process.SpawnOptions.StdIo
stderr: process.SpawnOptions.StdIo
inherit_dirs: []const Dir
inherit_files: []const File
pgid: ?posix.pid_t
start_suspended: bool
PATH: []const u8
std.Io.Threaded.Spawned
容器
字段
std.Io.Threaded.spawnPosix
函数
fn spawnPosix(t: *Threaded, options: process.SpawnOptions) process.SpawnError!Spawned
参数
t: *Threaded
options: process.SpawnOptions
错误
- AccessDenied OpenError
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference OpenError
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy OpenError
- FileBusy OpenError
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported OpenError
- FileNotFound OpenError
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileSystem
- FileTooBig OpenError
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- InvalidBatchScriptArg
仅限 Windows。执行
.bat或.cmd脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。- NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
- CR 会被
cmd.exe移除,因此执行后所有 CR 码点都会丢失。
- InvalidExe
- InvalidName
- InvalidProcessGroupId
- InvalidUserId
- InvalidWtf8
仅限 Windows。提供的
cwd或argv为无效 WTF-8。 https://wtf-8.codeberg.page/- IsDir OpenError
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound OpenError
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
仅限 POSIX。选择了
StdIo.ignore,且打开/dev/null时返回 ENODEV。- NoSpaceLeft OpenError
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir OpenError
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- OperationUnsupported
操作系统不支持创建子进程。
- OutOfMemory
- PathAlreadyExists OpenError
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy OpenError
- ProcessAlreadyExec
尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem OpenError
- ResourceLimitReached
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources OpenError
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
- WouldBlock OpenError
已请求非阻塞模式,但该操作无法立即返回。
std.Io.Threaded.splat_buffer_size
常量
std.Io.Threaded.statFromLinux
函数
pub fn statFromLinux(stx: *const std.os.linux.Statx) Io.UnexpectedError!File.Stat
参数
错误
- Unexpected
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.statFromPosix
函数
pub fn statFromPosix(st: *const posix.Stat) File.Stat
参数
std.Io.Threaded.statFromWasi
函数
fn statFromWasi(st: *const std.os.wasi.filestat_t) File.Stat
参数
st: *const std.os.wasi.filestat_t
std.Io.Threaded.statusToTerm
函数
pub fn statusToTerm(status: u32) process.Child.Term
参数
status: u32
std.Io.Threaded.statx_use_c
常量
std.Io.Threaded.statxKind
函数
pub fn statxKind(stx_mode: u16) File.Kind
参数
stx_mode: u16
std.Io.Threaded.std
别名
别名目标 std
std.Io.Threaded.submitComplete
函数
fn submitComplete(ring: []u32, complete_tail: *Io.Batch.RingIndex, op: u32) void
参数
std.Io.Threaded.supportsAnsiEscapeCodes
函数
fn supportsAnsiEscapeCodes(t: *Threaded, file: File) Io.Cancelable!bool
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.swapCancelProtection
函数
fn swapCancelProtection(userdata: ?*anyopaque, new: Io.CancelProtection) Io.CancelProtection
参数
userdata: ?*anyopaque
new: Io.CancelProtection
std.Io.Threaded.Syscall
容器
字段
thread: ?*Thread
std.Io.Threaded.Syscall.checkCancel
函数
检查此系统调用是否已取消。当系统调用被某种机制
中断,而该中断可能表示取消,也可能是伪中断时,应调用此函数。
如果系统调用已取消,则将其标记为完成并返回 error.Canceled。否则,
不将系统调用标记为完成,调用方应重试。
fn checkCancel(s: Syscall) Io.Cancelable!void
参数
s: Syscall
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Syscall.errnoBug
函数
便捷封装:先调用 finish,再调用 Threaded.errnoBug。
fn errnoBug(s: Syscall, err: posix.E) Io.UnexpectedError
参数
std.Io.Threaded.Syscall.fail
函数
便捷封装:调用 finish,然后返回 err。
fn fail(s: Syscall, err: anytype) @TypeOf(err)
参数
s: Syscall
std.Io.Threaded.Syscall.finish
函数
将此系统调用标记为已完成。
fn finish(s: Syscall) void
参数
s: Syscall
std.Io.Threaded.Syscall.ntstatusBug
函数
便捷封装:先调用 finish,再调用 windows.statusBug。
fn ntstatusBug(s: Syscall, status: windows.NTSTATUS) Io.UnexpectedError
参数
std.Io.Threaded.Syscall.start
函数
标记进入系统调用区域。其作用域应紧密围绕实际系统调用,
以尽量减少竞态。必须通过 checkCancel、finish
或 finish 的某个封装,将系统调用标记为“已完成”。
fn start() Io.Cancelable!Syscall
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Syscall.toAlertable
函数
表示需要使用 NtAlertThread 中断等待,而不是 NtCancelSynchronousIoFile。
仅限 Windows,且仅从阻塞状态调用。
fn toAlertable(s: Syscall) Io.Cancelable!AlertableSyscall
参数
s: Syscall
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Syscall.unexpectedErrno
函数
便捷封装:先调用 finish,再调用 posix.unexpectedErrno。
fn unexpectedErrno(s: Syscall, err: posix.E) Io.UnexpectedError
参数
std.Io.Threaded.Syscall.unexpectedNtstatus
函数
便捷封装:先调用 finish,再调用 windows.unexpectedStatus。
fn unexpectedNtstatus(s: Syscall, status: windows.NTSTATUS) Io.UnexpectedError
参数
std.Io.Threaded.systemBasicInformation
函数
fn systemBasicInformation(t: *Threaded) ?*const windows.SYSTEM.BASIC_INFORMATION
参数
t: *Threaded
std.Io.Threaded.SystemBasicInformation
类型
std.Io.Threaded.testArgvToCommandLineWindows
函数
fn testArgvToCommandLineWindows(argv: []const []const u8, expected_cmd_line: []const u8) !void
参数
argv: []const []const u8
expected_cmd_line: []const u8
std.Io.Threaded.Thread
容器
字段
next: ?*Thread
id: std.Thread.Id
handle: Handle
status: std.atomic.Value(Status)
cancel_protection: Io.CancelProtection
futex_waiter: if (use_parking_futex) ?*parking_futex.Waiter else ?noreturnStatus.cancelation 设置为 .parked 时始终释放。
unpark_flag: UnparkFlag
park_tid: if (ParkTid == std.Thread.Id) void else ParkTid
csprng: Csprng
std.Io.Threaded.Thread.cancelAwaitable
函数
如果 thread 正在处理 awaitable,则取消它。
thread 可能被此函数取消,但仍阻塞在系统调用中。
此时可能需要向线程发送信号以中断调用。此函数会
返回 true 表示此情况,此时调用方必须调用 signalCanceledSyscall。
fn cancelAwaitable(thread: *Thread, awaitable: AwaitableId) bool
参数
thread: *Thread
awaitable: AwaitableId
std.Io.Threaded.Thread.checkCancel
函数
线程既不在系统调用内,也未正在进入系统调用,但仍需检查取消。
若存在待处理的取消请求,则确认该请求并返回 error.Canceled。
fn checkCancel() Io.Cancelable!void
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Thread.current
变量
?*Thread
std.Io.Threaded.Thread.currentId
函数
fn currentId() std.Thread.Id
std.Io.Threaded.Thread.futexWait
函数
fn futexWait(ptr: *const u32, expect: u32, timeout_ns: ?u64) Io.Cancelable!void
参数
ptr: *const u32
expect: u32
timeout_ns: ?u64
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Thread.futexWaitInner
函数
fn futexWaitInner(ptr: *const u32, expect: u32, uncancelable: bool, timeout_ns: ?u64) Io.Cancelable!void
参数
ptr: *const u32
expect: u32
uncancelable: bool
timeout_ns: ?u64
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.Thread.futexWaitUncancelable
函数
fn futexWaitUncancelable(ptr: *const u32, expect: u32, timeout_ns: ?u64) void
参数
ptr: *const u32
expect: u32
timeout_ns: ?u64
std.Io.Threaded.Thread.futexWake
函数
fn futexWake(ptr: *const u32, max_waiters: u32) void
参数
ptr: *const u32
max_waiters: u32
std.Io.Threaded.Thread.Handle
常量
std.Io.Threaded.Thread.invalid_id
常量
不与任何其他线程 ID 重合的值。
std.Thread.Id
std.Io.Threaded.Thread.PackedPtr
容器
类似 *Thread,但比指针少 2 位,因为对齐保证最低有效位始终为 0,
从而可在 packed struct 中使用这两位。
字段
std.Io.Threaded.Thread.PackedPtr.pack
函数
fn pack(ptr: *Thread) PackedPtr
参数
ptr: *Thread
std.Io.Threaded.Thread.PackedPtr.Split
容器
字段
low: u2
high: PackedPtr
std.Io.Threaded.Thread.PackedPtr.unpack
函数
fn unpack(ptr: PackedPtr) ?*Thread
参数
ptr: PackedPtr
std.Io.Threaded.Thread.signalCanceledSyscall
函数
如果 thread 仍阻塞在系统调用中,即尚未观察到
cancelAwaitable 发出的取消请求,则向其发送信号。
遗憾的是,信号可能在系统调用真正开始之前到达,导致中断
未能生效。为解决此问题,可能需要发送多次信号。因此,如果此函数
返回 true,则应在短暂延迟后再次调用,以便在线程
仍阻塞时重新发送信号。实现参见 Future.waitForCancelWithSignaling 和
Group.waitForCancelWithSignaling:它们使用指数退避,从 1 微秒开始,
每次调用延迟翻倍。实际很少需要发送一个以上的信号。
fn signalCanceledSyscall(thread: *Thread, t: *Threaded, awaitable: AwaitableId) bool
参数
std.Io.Threaded.Thread.SignaleeId
类型
std.Io.Threaded.Thread.Status
容器
字段
cancelation: enum(u3) {
/// 线程尚未取消,且不处于可取消操作中。
/// 要请求取消,只需将状态设为 `.canceling`。
none = 0b000,
/// 线程停驻于可取消的 futex 等待或休眠中。
/// 仅在 `use_parking_futex` 或 `use_parking_sleep` 时适用。
/// 请求取消时,将状态设为 `.canceling`,并唤回线程。
/// 因其他原因(futex 唤醒)唤回时,将状态设为 `.none`,并唤回线程。
parked = 0b001,
/// 线程阻塞在可取消的系统调用中。
/// 若要请求取消,将状态设为 `.blocked_canceling`,并反复中断该系统调用,直至状态改变。
blocked = 0b011,
/// 仅限 Windows:线程通过 `NtDelayExecution` 阻塞于可警报等待中。
/// 要请求取消,将状态设为
/// `blocked_alertable_canceling`,并反复向线程发出警报,
/// 直到状态改变。
blocked_alertable = 0b010,
/// 线程有未处理的取消请求,但当前不在可取消操作中。
/// 确认取消后,线程会将状态设置为 `.canceled`。
canceling = 0b110,
/// 线程已收到并确认取消请求。
/// 若调用 `recancel`,状态将恢复为 `.canceling`;否则,
/// 在此任务剩余的执行期间,状态不再变化。
canceled = 0b111,
/// 线程阻塞于可取消系统调用中,且正在
/// 被取消。触发取消的线程将持续向此线程
/// 发送信号,直到其状态改变。
blocked_canceling = 0b101,
/// 仅适用于 Windows:线程通过 `NtDelayExecution`
/// 阻塞于可警报等待中,且正在被取消。
/// 触发取消的线程将持续向此线程发送信号,
/// 直到其状态改变。
blocked_alertable_canceling = 0b100,
}这些枚举字段的具体取值旨在简化 需要对此状态应用的变换的实现。
awaitable: AwaitableId不能将此值转换回指针。它的用途是允许通过对线程状态执行
cmpxchg 来取消任务:若线程正在运行待取消任务,
则更新 cancelation 字段。
std.Io.Threaded.Threaded
别名
别名目标 std.Io.Threaded
std.Io.Threaded.timeoutToWindowsInterval
函数
fn timeoutToWindowsInterval(timeout: Io.Timeout) ?windows.LARGE_INTEGER
参数
std.Io.Threaded.timestampFromPosix
函数
pub fn timestampFromPosix(timespec: *const posix.timespec) Io.Timestamp
参数
std.Io.Threaded.timestampToPosix
函数
fn timestampToPosix(nanoseconds: i96) posix.timespec
参数
nanoseconds: i96
std.Io.Threaded.tryLockStderr
函数
fn tryLockStderr(userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!?Io.LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Threaded.UnixAddress
容器
字段
std.Io.Threaded.unlockStderr
函数
fn unlockStderr(userdata: ?*anyopaque) void
参数
userdata: ?*anyopaque
std.Io.Threaded.unpark
函数
addr_hint 不影响语义,但可能使操作系统能够优化此操作。
fn unpark(tids: []const UnparkTid, addr_hint: ?*const anyopaque) void
参数
tids: []const UnparkTid
addr_hint: ?*const anyopaque
std.Io.Threaded.unpark_flag_init
常量
UnparkFlag
std.Io.Threaded.UnparkFlag
类型
std.Io.Threaded.UnparkTid
类型
传入 unpark 的线程标识类型。直觉上它应是 std.Thread.Id,
但 Microsoft 的实现似乎未遵循自身线程标识的预期大小。
std.Io.Threaded.use_dev_urandom
常量
std.Io.Threaded.use_libc_getrandom
常量
std.Io.Threaded.use_parking_futex
常量
std.Io.Threaded.use_parking_sleep
常量
std.Io.Threaded.UseCopyFileRange
类型
std.Io.Threaded.UseCopyFileRange.default
常量
UseCopyFileRange
std.Io.Threaded.UseCopyFileRange.default
常量
UseCopyFileRange
std.Io.Threaded.UseFchmodat2
类型
std.Io.Threaded.UseFchmodat2.default
常量
UseFchmodat2
std.Io.Threaded.UseFchmodat2.default
常量
UseFchmodat2
std.Io.Threaded.UseFcopyfile
类型
std.Io.Threaded.UseFcopyfile.default
常量
UseFcopyfile
std.Io.Threaded.UseFcopyfile.default
常量
UseFcopyfile
std.Io.Threaded.UseSendfile
类型
std.Io.Threaded.UseSendfile.default
常量
UseSendfile
std.Io.Threaded.UseSendfile.default
常量
UseSendfile
std.Io.Threaded.waitForApcOrAlert
函数
pub fn waitForApcOrAlert() void
std.Io.Threaded.WaitGroup
容器
字段
std.Io.Threaded.WaitGroup.finish
函数
fn finish(wg: *WaitGroup) void
参数
wg: *WaitGroup
std.Io.Threaded.WaitGroup.init
常量
WaitGroup
std.Io.Threaded.WaitGroup.is_waiting
常量
usize
std.Io.Threaded.WaitGroup.one_pending
常量
usize
std.Io.Threaded.WaitGroup.start
函数
fn start(wg: *WaitGroup) void
参数
wg: *WaitGroup
std.Io.Threaded.WaitGroup.value
函数
fn value(wg: *WaitGroup) usize
参数
wg: *WaitGroup
std.Io.Threaded.WaitGroup.wait
函数
fn wait(wg: *WaitGroup) void
参数
wg: *WaitGroup
std.Io.Threaded.windows
别名
别名目标 std.os.windows
std.Io.Threaded.windows_lock_range_len
常量
windows.LARGE_INTEGER
std.Io.Threaded.windows_lock_range_off
常量
windows.LARGE_INTEGER
std.Io.Threaded.WindowsBatchOperationUserdata
容器
字段
file: windows.HANDLE
iosb: windows.IO_STATUS_BLOCK
std.Io.Threaded.WindowsBatchOperationUserdata.Erased
别名
std.Io.Threaded.WindowsBatchOperationUserdata.fromErased
函数
fn fromErased(erased: *Erased) *WindowsBatchOperationUserdata
参数
erased: *Erased
std.Io.Threaded.WindowsBatchOperationUserdata.toErased
函数
fn toErased(userdata: *WindowsBatchOperationUserdata) *Erased
参数
userdata: *WindowsBatchOperationUserdata
std.Io.Threaded.WindowsCommandLineCache
容器
将 argv 序列化为 WTF-16 编码的命令行字符串,供 CreateProcessW 使用。
按需序列化并缓存结果,以便:
- 只序列化需要的命令行类型;
.bat、.cmd的命令行序列化方式与.exe等不同。 - 必要时复用已序列化的命令行,例如命令执行 失败后,还需继续搜索 PATH 中的其他候选项。
字段
cmd_line: ?[:0]u16 = null
script_cmd_line: ?[:0]u16 = null
cmd_exe_path: ?[:0]u16 = null
argv: []const []const u8
allocator: Allocator
std.Io.Threaded.WindowsCommandLineCache.cmdExePath
函数
fn cmdExePath(self: *WindowsCommandLineCache) Allocator.Error![:0]u16
参数
self: *WindowsCommandLineCache
错误
- OutOfMemory
std.Io.Threaded.WindowsCommandLineCache.commandLine
函数
fn commandLine(self: *WindowsCommandLineCache) ![:0]u16
参数
self: *WindowsCommandLineCache
std.Io.Threaded.WindowsCommandLineCache.deinit
函数
fn deinit(self: *WindowsCommandLineCache) void
参数
self: *WindowsCommandLineCache
std.Io.Threaded.WindowsCommandLineCache.init
函数
fn init(allocator: Allocator, argv: []const []const u8) WindowsCommandLineCache
参数
allocator: Allocator
argv: []const []const u8
std.Io.Threaded.WindowsCommandLineCache.scriptCommandLine
函数
不缓存,因为搜索 PATH 时,批处理脚本路径会变化。
script_path 应尽可能完整,例如搜索 PATH 时,script_path 应同时包含搜索路径与脚本文件名,从而避免 cmd.exe 再次搜索 PATH。
fn scriptCommandLine(self: *WindowsCommandLineCache, script_path: []const u16) ![:0]u16
参数
self: *WindowsCommandLineCache
script_path: []const u16
std.Io.Threaded.windowsCreatePipe
函数
pub fn windowsCreatePipe(t: *Threaded, options: CreatePipeOptions) ![2]windows.HANDLE
参数
t: *Threaded
options: CreatePipeOptions
std.Io.Threaded.windowsCreateProcess
函数
fn windowsCreateProcess( app_name: [*:0]u16, cmd_line: [*:0]u16, env_block: ?process.Environ.WindowsBlock, cwd_ptr: ?[*:0]u16, flags: windows.CreateProcessFlags, lpStartupInfo: *windows.STARTUPINFOW, lpProcessInformation: *windows.PROCESS.INFORMATION, ) !void
参数
app_name: [*:0]u16
cmd_line: [*:0]u16
env_block: ?process.Environ.WindowsBlock
cwd_ptr: ?[*:0]u16
flags: windows.CreateProcessFlags
lpStartupInfo: *windows.STARTUPINFOW
lpProcessInformation: *windows.PROCESS.INFORMATION
std.Io.Threaded.windowsCreateProcessPathExt
函数
要求 app_buf 恰好包含应用程序名称,dir_buf 恰好包含目录路径。
返回后,app_buf 始终恰好包含应用程序名称,dir_buf 始终恰好包含目录路径。
注意:app_buf 不应带前导路径分隔符。
注意:若目录为当前工作目录,dir_buf 应为空,即 len = 0。
fn windowsCreateProcessPathExt( arena: Allocator, dir_buf: *std.ArrayList(u16), app_buf: *std.ArrayList(u16), pathext: [:0]const u16, cmd_line_cache: *WindowsCommandLineCache, env_block: ?process.Environ.WindowsBlock, cwd_ptr: ?[*:0]u16, flags: windows.CreateProcessFlags, lpStartupInfo: *windows.STARTUPINFOW, lpProcessInformation: *windows.PROCESS.INFORMATION, ) !void
参数
arena: Allocator
dir_buf: *std.ArrayList(u16)
app_buf: *std.ArrayList(u16)
pathext: [:0]const u16
cmd_line_cache: *WindowsCommandLineCache
env_block: ?process.Environ.WindowsBlock
cwd_ptr: ?[*:0]u16
flags: windows.CreateProcessFlags
lpStartupInfo: *windows.STARTUPINFOW
lpProcessInformation: *windows.PROCESS.INFORMATION
std.Io.Threaded.windowsCreateProcessSupportsExtension
函数
不区分大小写的 WTF-16 查找
fn windowsCreateProcessSupportsExtension(ext: []const u16) ?process.WindowsExtension
参数
ext: []const u16
用法示例
test windowsCreateProcessSupportsExtension {
try std.testing.expectEqual(process.WindowsExtension.exe, windowsCreateProcessSupportsExtension(&[_]u16{ '.', 'e', 'X', 'e' }).?);
try std.testing.expect(windowsCreateProcessSupportsExtension(&[_]u16{ '.', 'e', 'X', 'e', 'c' }) == null);
}
std.Io.Threaded.WindowsEnvironStrings
容器
字段
PATH: ?[:0]const u16 = null
PATHEXT: ?[:0]const u16 = null
std.Io.Threaded.WindowsEnvironStrings.scan
函数
fn scan() WindowsEnvironStrings
std.Io.Threaded.WindowsPathSpace
容器
字段
data: [windows.PATH_MAX_WIDE:0]u16
len: usize
std.Io.Threaded.WindowsPathSpace.span
函数
pub fn span(wps: *const WindowsPathSpace) [:0]const u16
参数
wps: *const WindowsPathSpace
std.Io.Threaded.WindowsPathSpace.string
函数
pub fn string(wps: *const WindowsPathSpace) windows.UNICODE_STRING
参数
wps: *const WindowsPathSpace
std.Io.Threaded.windowsWriteBuffer
函数
由于 Windows 仅支持写入一个连续缓冲区,因此返回 第一个缓冲区,同时将长度限制为 32 位无符号整数可表示的范围。
fn windowsWriteBuffer(header: []const u8, data: []const []const u8, splat: usize) []const u8
参数
header: []const u8
data: []const []const u8
splat: usize
std.Io.Threaded.worker
函数
fn worker(t: *Threaded) void
参数
t: *Threaded
std.Io.Threaded.writeFilePositionalWindows
函数
fn writeFilePositionalWindows(file: File, buffer: []const u8, offset: u64) File.WritePositionalError!usize
参数
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.Threaded.writeIntFd
函数
fn writeIntFd(fd: posix.fd_t, value: ErrInt) !void
参数
std.Io.Threaded.writeResolutionQuery
函数
将 DNS 解析查询数据包写入 w,最多 280 字节。
fn writeResolutionQuery(q: *[280]u8, op: u4, dname: []const u8, class: u8, ty: HostName.DnsRecord, entropy: [2]u8) usize
参数
std.Io.Threaded.ws2_32
别名
std.Io.Threaded.Wtf16ToPrefixedFileWError
错误集合
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Threaded.Wtf16ToPrefixedFileWOptions
容器
字段
allow_relative: bool = true
std.Io.Threaded.Wtf8ToPrefixedFileWError
别名
std.Io.Threaded.wToPrefixedFileW
函数
将 path 转换为以零结尾的 WTF16。若路径包含任意命名空间前缀,或者不是相对路径,例如根路径、驱动器相对路径等,则结果会带有 NT 风格前缀 \??\。
类似 RtlDosPathNameToNtPathName_U,但有以下区别:
- 不进行堆分配。
- 相对路径保持相对形式,除非包含过多 .. 分量;此时若
dir非空,则相对于它解析,否则相对于当前工作目录解析。 - 不会特殊处理 COM1、NUL 等特殊设备名称(TODO)。
- 不会移除相对路径末尾的点和空格(可能的 TODO)。
pub fn wToPrefixedFileW(dir: ?windows.HANDLE, path: [:0]const u16, options: Wtf16ToPrefixedFileWOptions) Wtf16ToPrefixedFileWError!WindowsPathSpace
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
源码
std/Io/Threaded.zig
const Threaded = @This();
const builtin = @import("builtin");
const native_os = builtin.os.tag;
const is_windows = native_os == .windows;
const is_darwin = native_os.isDarwin();
const is_debug = builtin.mode == .debug;
const std = @import("../std.zig");
const Io = std.Io;
const net = std.Io.net;
const File = std.Io.File;
const Dir = std.Io.Dir;
const HostName = net.HostName;
const IpAddress = net.IpAddress;
const process = std.process;
const Allocator = std.mem.Allocator;
const Alignment = std.mem.Alignment;
const assert = std.debug.assert;
const posix = std.posix;
const windows = std.os.windows;
const ws2_32 = windows.ws2_32;
/// 线程安全。
///
/// 用途:
/// * 分配 `Io.Future` 和 `Io.Group` 闭包。
/// * 格式化并创建子进程
/// * 在某些目标上扫描环境变量
/// * mmap 或等价机制不可用时,进行内存映射
allocator: Allocator,
mutex: Io.Mutex = .init,
cond: Io.Condition = .init,
run_queue: std.SinglyLinkedList = .{},
join_requested: bool = false,
stack_size: usize,
/// 所有线程均以分离状态派生;通过此处等待它们全部退出。
wait_group: WaitGroup = .init,
async_limit: Io.Limit,
concurrent_limit: Io.Limit = .unlimited,
/// 在 `init` 中调用 `std.Thread.getCpuCount` 产生的错误。
cpu_count_error: ?std.Thread.CpuCountError,
/// 无法接收任务的线程数量。可用数量等于 `async_limit` 或 `concurrent_limit` 减去此值。
///
///
busy_count: usize = 0,
worker_threads: std.atomic.Value(?*Thread),
pid: Pid = .unknown,
have_signal_handler: bool,
old_sig_io: if (have_sig_io) posix.Sigaction else void,
old_sig_pipe: if (have_sig_pipe) posix.Sigaction else void,
use_sendfile: UseSendfile = .default,
use_copy_file_range: UseCopyFileRange = .default,
use_fcopyfile: UseFcopyfile = .default,
use_fchmodat2: UseFchmodat2 = .default,
disable_memory_mapping: bool,
stderr_writer: File.Writer = .{
.io = undefined,
.interface = File.Writer.initInterface(&.{}),
.file = if (is_windows) undefined else .stderr(),
.mode = .streaming,
},
stderr_mode: Io.Terminal.Mode = .no_color,
stderr_writer_initialized: bool = false,
stderr_mutex: Io.Mutex = .init,
stderr_mutex_locker: std.Thread.Id = Thread.invalid_id,
stderr_mutex_lock_count: usize = 0,
argv0: Argv0,
/// 由 `mutex` 保护。确定 `environ` 是否已基于
/// `process_environ` 进行记忆化。
environ_initialized: bool,
environ: Environ,
dl: Dl = .init,
null_file: NullFile = .{},
random_file: RandomFile = .{},
pipe_file: PipeFile = .{},
csprng: Csprng = .uninitialized,
system_basic_information: SystemBasicInformation = .{},
process_spawn_mutex: if (is_windows) Io.Mutex else void = if (is_windows) .init else {},
const SystemBasicInformation = if (!is_windows) struct {} else struct {
buffer: windows.SYSTEM.BASIC_INFORMATION = undefined,
initialized: std.atomic.Value(bool) = .{ .raw = false },
};
const Dl = switch (native_os) {
.windows => struct {
iphlpapi_dll: std.atomic.Value(?*anyopaque),
ConvertInterfaceNameToLuidW: std.atomic.Value(?*const fn (
InterfaceName: [*:0]const windows.WCHAR,
InterfaceLuid: *windows.NET.LUID,
) callconv(.winapi) windows.Win32Error),
ConvertInterfaceLuidToIndex: std.atomic.Value(?*const fn (
InterfaceLuid: *const windows.NET.LUID,
InterfaceIndex: *windows.NET.IFINDEX,
) callconv(.winapi) windows.Win32Error),
ConvertInterfaceIndexToLuid: std.atomic.Value(?*const fn (
InterfaceIndex: std.os.windows.NET.IFINDEX,
InterfaceLuid: *std.os.windows.NET.LUID,
) callconv(.winapi) windows.Win32Error),
ConvertInterfaceLuidToNameW: std.atomic.Value(?*const fn (
InterfaceLuid: *const std.os.windows.NET.LUID,
InterfaceName: std.os.windows.PWSTR,
Length: std.os.windows.SIZE_T,
) callconv(.winapi) std.os.windows.Win32Error),
dnsapi_dll: std.atomic.Value(?*anyopaque),
DnsQueryEx: std.atomic.Value(?*const fn (
pQueryRequest: *const windows.DNS.QUERY.REQUEST,
pQueryResults: *windows.DNS.QUERY.RESULT,
pCancelHandle: ?*windows.DNS.QUERY.CANCEL,
) callconv(.winapi) windows.DNS.STATUS),
// DnsCancelQuery: std.atomic.Value(?*const fn (
// pCancelHandle: *const windows.DNS.QUERY.CANCEL,
// ) callconv(.winapi) windows.DNS.STATUS),
DnsFree: std.atomic.Value(?*const fn (
pRecordList: ?*anyopaque,
FreeType: windows.DNS.FREE_TYPE,
) callconv(.winapi) void),
const init: Dl = .{
.iphlpapi_dll = .init(null),
.ConvertInterfaceNameToLuidW = .init(null),
.ConvertInterfaceLuidToIndex = .init(null),
.ConvertInterfaceIndexToLuid = .init(null),
.ConvertInterfaceLuidToNameW = .init(null),
.dnsapi_dll = .init(null),
.DnsQueryEx = .init(null),
// .DnsCancelQuery = .init(null),
.DnsFree = .init(null),
};
fn deinit(dl: *Dl) void {
if (dl.iphlpapi_dll.raw) |iphlpapi_dll| switch (windows.ntdll.LdrUnloadDll(iphlpapi_dll)) {
.SUCCESS => {},
else => |status| windows.unexpectedStatus(status) catch {},
};
dl.* = .init;
}
},
else => struct {
const init: Dl = .{};
fn deinit(_: Dl) void {}
},
};
pub const Csprng = struct {
rng: std.Random.DefaultCsprng,
pub const uninitialized: Csprng = .{ .rng = .{
.state = undefined,
.offset = std.math.maxInt(usize),
} };
pub const seed_len = std.Random.DefaultCsprng.secret_seed_length;
pub fn isInitialized(c: *const Csprng) bool {
return c.rng.offset != std.math.maxInt(usize);
}
};
pub const Argv0 = switch (native_os) {
.openbsd, .haiku => struct {
value: ?[*:0]const u8,
pub const empty: Argv0 = .{ .value = null };
pub fn init(args: process.Args) Argv0 {
return .{ .value = args.vector[0] };
}
},
else => struct {
pub const empty: Argv0 = .{};
pub fn init(args: process.Args) Argv0 {
_ = args;
return .{};
}
},
};
pub const Environ = struct {
/// 直接来自操作系统的未修改数据。
process_environ: process.Environ,
/// 由 `mutex` 保护,基于 `process_environ` 进行记忆化缓存。跟踪环境变量是否存在,而忽略其值。
///
exist: Exist = .{},
/// 由 `mutex` 保护。基于 `process_environ` 进行记忆化缓存。
string: String = .{},
/// ZIG_PROGRESS
zig_progress_file: std.Progress.ParentFileError!File = error.EnvironmentVariableMissing,
/// 由 `mutex` 保护。跟踪尝试扫描环境变量时
/// 发生的问题,若存在。
///
/// 仅 WASI 上可能发生错误。
err: ?Error = null,
pub const empty: Environ = .{ .process_environ = .empty };
pub const Error = Allocator.Error || Io.UnexpectedError;
pub const Exist = struct {
NO_COLOR: bool = false,
CLICOLOR_FORCE: bool = false,
};
pub const String = switch (native_os) {
.windows, .wasi => struct {},
else => struct {
PATH: ?[:0]const u8 = null,
DEBUGINFOD_CACHE_PATH: ?[:0]const u8 = null,
XDG_CACHE_HOME: ?[:0]const u8 = null,
HOME: ?[:0]const u8 = null,
TERM: ?[:0]const u8 = null,
},
};
pub fn scan(environ: *Environ, allocator: Allocator) void {
if (is_windows) {
// 任何修改环境的调用都会使此值失效;这超出此 Io 实现的控制,因此引用必须短暂使用。
//
//
const peb = windows.peb();
assert(windows.ntdll.RtlEnterCriticalSection(peb.FastPebLock) == .SUCCESS);
defer assert(windows.ntdll.RtlLeaveCriticalSection(peb.FastPebLock) == .SUCCESS);
const ptr = peb.ProcessParameters.Environment;
var i: usize = 0;
while (ptr[i] != 0) {
// 某些特殊环境变量以 = 开头,
// 因此若第一个字符是 =,就必须特殊处理,不把它当作键值分隔符。
// https://devblogs.microsoft.com/oldnewthing/20100506-00/?p=14133
//
const key_start = i;
if (ptr[i] == '=') i += 1;
while (ptr[i] != 0 and ptr[i] != '=') : (i += 1) {}
const key_w = ptr[key_start..i];
const value_start = i + 1;
while (ptr[i] != 0) : (i += 1) {} // 跳过 '=' 和值
const value_w = ptr[value_start..i];
i += 1; // 跳过空字节
if (windows.eqlIgnoreCaseWtf16(key_w, &.{ 'N', 'O', '_', 'C', 'O', 'L', 'O', 'R' })) {
environ.exist.NO_COLOR = true;
} else if (windows.eqlIgnoreCaseWtf16(key_w, &.{ 'C', 'L', 'I', 'C', 'O', 'L', 'O', 'R', '_', 'F', 'O', 'R', 'C', 'E' })) {
environ.exist.CLICOLOR_FORCE = true;
} else if (windows.eqlIgnoreCaseWtf16(key_w, &.{ 'Z', 'I', 'G', '_', 'P', 'R', 'O', 'G', 'R', 'E', 'S', 'S' })) {
environ.zig_progress_file = file: {
var value_buf: [std.fmt.count("{d}", .{std.math.maxInt(usize)})]u8 = undefined;
const len = std.unicode.calcWtf8Len(value_w);
if (len > value_buf.len) break :file error.UnrecognizedFormat;
assert(std.unicode.wtf16LeToWtf8(&value_buf, value_w) == len);
break :file .{
.handle = @ptrFromInt(std.fmt.parseInt(usize, value_buf[0..len], 10) catch
break :file error.UnrecognizedFormat),
.flags = .{ .nonblocking = true },
};
};
}
comptime assert(@sizeOf(String) == 0);
}
} else if (native_os == .wasi and !builtin.link_libc) {
var environ_size: usize = undefined;
var environ_buf_size: usize = undefined;
switch (std.os.wasi.environ_sizes_get(&environ_size, &environ_buf_size)) {
.SUCCESS => {},
else => |err| {
environ.err = posix.unexpectedErrno(err);
return;
},
}
if (environ_size == 0) return;
const wasi_environ = allocator.alloc([*:0]u8, environ_size) catch |err| {
environ.err = err;
return;
};
defer allocator.free(wasi_environ);
const wasi_environ_buf = allocator.alloc(u8, environ_buf_size) catch |err| {
environ.err = err;
return;
};
defer allocator.free(wasi_environ_buf);
switch (std.os.wasi.environ_get(wasi_environ.ptr, wasi_environ_buf.ptr)) {
.SUCCESS => {},
else => |err| {
environ.err = posix.unexpectedErrno(err);
return;
},
}
for (wasi_environ) |env| {
const pair = std.mem.sliceTo(env, 0);
var parts = std.mem.splitScalar(u8, pair, '=');
const key = parts.first();
if (std.mem.eql(u8, key, "NO_COLOR")) {
environ.exist.NO_COLOR = true;
} else if (std.mem.eql(u8, key, "CLICOLOR_FORCE")) {
environ.exist.CLICOLOR_FORCE = true;
}
comptime assert(@sizeOf(String) == 0);
}
} else {
for (environ.process_environ.block.slice) |opt_entry| {
const entry = opt_entry.?;
var entry_i: usize = 0;
while (entry[entry_i] != 0 and entry[entry_i] != '=') : (entry_i += 1) {}
const key = entry[0..entry_i];
var end_i: usize = entry_i;
while (entry[end_i] != 0) : (end_i += 1) {}
const value = entry[entry_i + 1 .. end_i :0];
if (std.mem.eql(u8, key, "NO_COLOR")) {
environ.exist.NO_COLOR = true;
} else if (std.mem.eql(u8, key, "CLICOLOR_FORCE")) {
environ.exist.CLICOLOR_FORCE = true;
} else if (std.mem.eql(u8, key, "ZIG_PROGRESS")) {
environ.zig_progress_file = file: {
break :file .{
.handle = std.fmt.parseInt(u31, value, 10) catch
break :file error.UnrecognizedFormat,
.flags = .{ .nonblocking = true },
};
};
} else inline for (@typeInfo(String).@"struct".field_names) |field_name| {
if (std.mem.eql(u8, key, field_name)) @field(environ.string, field_name) = value;
}
}
}
}
};
pub const NullFile = switch (native_os) {
.windows => struct {
handle: ?windows.HANDLE = null,
fn deinit(this: *@This()) void {
if (this.handle) |handle| {
windows.CloseHandle(handle);
this.handle = null;
}
}
},
.wasi, .ios, .tvos, .visionos, .watchos => struct {
fn deinit(this: @This()) void {
_ = this;
}
},
else => struct {
fd: posix.fd_t = -1,
fn deinit(this: *@This()) void {
if (this.fd >= 0) {
closeFd(this.fd);
this.fd = -1;
}
}
},
};
pub const RandomFile = switch (native_os) {
.windows => NullFile,
else => if (use_dev_urandom) NullFile else struct {
fn deinit(this: @This()) void {
_ = this;
}
},
};
pub const PipeFile = switch (native_os) {
.windows => struct {
handle: ?windows.HANDLE = null,
fn deinit(this: *@This()) void {
if (this.handle) |handle| {
windows.CloseHandle(handle);
this.handle = null;
}
}
},
else => struct {
fn deinit(this: @This()) void {
_ = this;
}
},
};
pub const Pid = if (native_os == .linux) enum(posix.pid_t) {
unknown = 0,
_,
} else enum(u0) { unknown = 0 };
pub const UseSendfile = if (have_sendfile) enum {
enabled,
disabled,
pub const default: UseSendfile = .enabled;
} else enum {
disabled,
pub const default: UseSendfile = .disabled;
};
pub const UseCopyFileRange = if (have_copy_file_range) enum {
enabled,
disabled,
pub const default: UseCopyFileRange = .enabled;
} else enum {
disabled,
pub const default: UseCopyFileRange = .disabled;
};
pub const UseFcopyfile = if (have_fcopyfile) enum {
enabled,
disabled,
pub const default: UseFcopyfile = .enabled;
} else enum {
disabled,
pub const default: UseFcopyfile = .disabled;
};
pub const UseFchmodat2 = if (have_fchmodat2 and !have_fchmodat_flags) enum {
enabled,
disabled,
pub const default: UseFchmodat2 = .enabled;
} else enum {
disabled,
pub const default: UseFchmodat2 = .disabled;
};
pub const apc_align = @max(default_fn_align, 2);
const default_fn_align = switch (builtin.mode) {
.debug, .safe, .fast => switch (builtin.cpu.arch) {
else => |arch| @compileError("Unsupported architecture: " ++ @tagName(arch)),
.arm, .thumb => 4,
.aarch64, .x86, .x86_64 => 16,
},
.small => 1,
};
const Runnable = struct {
node: std.SinglyLinkedList.Node,
startFn: *const fn (*Runnable, *Thread, *Threaded) void,
};
const Group = struct {
ptr: *Io.Group,
/// 返回指向 `Io.Group.token` 字段、类型正确的指针。
///
/// 状态表示组内待处理任务数、是否
/// 已取消,以及是否已被等待。
///
/// 注意,`Status` 的零值有意表示初始组状态,即为空
/// 且没有等待者。这是 `Io.Group` 的要求。
fn status(g: Group) *std.atomic.Value(Status) {
return @ptrCast(&g.ptr.token);
}
/// 返回类型正确、指向 `Io.Group.state` 字段的指针。这里使用二级指针是
/// 有意的,因为 `state` 字段本身保存指针,而此函数返回
/// 指向该字段的指针。
///
/// 整个组完成时,如果 `status` 表示存在等待方,最后一个
/// 任务必须递增此 `u32`,并对其执行 futex 唤醒以通知等待方。
fn awaiter(g: Group) **std.atomic.Value(u32) {
return @ptrCast(&g.ptr.state);
}
const Status = packed struct(usize) {
num_running: @Int(.unsigned, @bitSizeOf(usize) - 2),
have_awaiter: bool,
canceled: bool,
};
const Task = struct {
runnable: Runnable,
group: *Io.Group,
func: *const fn (context: *const anyopaque) void,
context_alignment: Alignment,
alloc_len: usize,
/// 创建的 `Task` 中,`Task.runnable.node` 为 `undefined`。
fn create(
gpa: Allocator,
group: Group,
context: []const u8,
context_alignment: Alignment,
func: *const fn (context: *const anyopaque) void,
) Allocator.Error!*Task {
const max_context_misalignment = context_alignment.toByteUnits() -| @alignOf(Task);
const worst_case_context_offset = context_alignment.forward(@sizeOf(Task) + max_context_misalignment);
const alloc_len = worst_case_context_offset + context.len;
const task: *Task = @ptrCast(@alignCast(try gpa.alignedAlloc(u8, .of(Task), alloc_len)));
errdefer comptime unreachable;
task.* = .{
.runnable = .{
.node = undefined,
.startFn = &start,
},
.group = group.ptr,
.func = func,
.context_alignment = context_alignment,
.alloc_len = alloc_len,
};
@memcpy(task.contextPointer()[0..context.len], context);
return task;
}
fn destroy(task: *Task, gpa: Allocator) void {
const base: [*]align(@alignOf(Task)) u8 = @ptrCast(task);
gpa.free(base[0..task.alloc_len]);
}
fn contextPointer(task: *Task) [*]u8 {
const base: [*]u8 = @ptrCast(task);
const offset = task.context_alignment.forward(@intFromPtr(base) + @sizeOf(Task)) - @intFromPtr(base);
return base + offset;
}
fn start(r: *Runnable, thread: *Thread, t: *Threaded) void {
const task: *Task = @fieldParentPtr("runnable", r);
const group: Group = .{ .ptr = task.group };
// 此处本可使用简单存储,但改为读改写操作,以便用 `.acquire`
// 约束此操作与下方 `group.status().load` 的顺序。它与
// `cancelThreads` 中对 `Thread.status` 的 `.release` 读改写配对,构成 StoreLoad
// 屏障,保证组取消时,要么我们从组状态中观察到取消,
// 要么取消方看到我们的线程状态,从而能够直接通知我们
// 取消请求。
_ = thread.status.swap(.{
.cancelation = .none,
.awaitable = .fromGroup(group.ptr),
}, .acquire);
if (group.status().load(.monotonic).canceled) {
thread.status.store(.{
.cancelation = .canceling,
.awaitable = .fromGroup(group.ptr),
}, .monotonic);
}
task.func(task.contextPointer());
thread.status.store(.{ .cancelation = .none, .awaitable = .null }, .monotonic);
const old_status = group.status().fetchSub(.{
.num_running = 1,
.have_awaiter = false,
.canceled = false,
}, .acq_rel); // 获取 `group.awaiter()`,释放任务结果
assert(old_status.num_running > 0);
if (old_status.have_awaiter and old_status.num_running == 1) {
const to_signal = group.awaiter().*;
// `awaiter` 只能由当前线程修改。若另一线程在此之后看到 `num_running`
// 降至 0,则说明另一个任务已经启动,这意味着
// `async`/`cancel` 与被等待组的完成过程发生了竞态。
group.awaiter().* = undefined;
_ = to_signal.fetchAdd(1, .release); // 释放结果
Thread.futexWake(&to_signal.raw, 1);
}
// 任务已完成,已启动自毁序列。
task.destroy(t.allocator);
}
};
/// 假定调用者已原子更新组状态,标记取消,
/// 并将此取消通知已运行的所有线程。
fn cancelThreads(g: Group, t: *Threaded) bool {
var any_blocked = false;
var it = t.worker_threads.load(.acquire); // 获取 `Thread` 值
while (it) |thread| : (it = thread.next) {
// 此不修改值的读改写操作用于维持顺序:原因见 `Group.Task.start` 中的注释。
_ = thread.status.fetchOr(.{ .cancelation = @fromBackingInt(@intCast(0)), .awaitable = .null }, .release);
if (thread.cancelAwaitable(.fromGroup(g.ptr))) any_blocked = true;
}
return any_blocked;
}
/// 使用 `Thread.signalCanceledSyscall` 向此组中仍阻塞于系统调用、尚未观察到取消请求的线程发送信号。
/// 若可能需要更多信号,则返回 `true`;此时调用者必须在延迟后再次调用。
///
fn signalAllCanceledSyscalls(g: Group, t: *Threaded) bool {
var any_signaled = false;
var it = t.worker_threads.load(.acquire); // 获取 `Thread` 值
while (it) |thread| : (it = thread.next) {
if (thread.signalCanceledSyscall(t, .fromGroup(g.ptr))) any_signaled = true;
}
return any_signaled;
}
/// 调用方已取消 `g`。必要时通知正在处理该组的线程,
/// 并等待 `g` 完成,以 `num_completed` 从 0 递增
/// 至 1 为标志;必要时定期向线程发送信号,
/// 使其从可取消的系统调用中解除阻塞。
///
/// `skip_signals` 表示已知当前没有线程处理该组,
/// 因此不需要通知或信号。
fn waitForCancelWithSignaling(
g: Group,
t: *Threaded,
num_completed: *std.atomic.Value(u32),
skip_signals: bool,
) void {
var need_signal: bool = !skip_signals and g.cancelThreads(t);
var timeout_ns: u64 = 1 << 10;
while (true) {
need_signal = need_signal and g.signalAllCanceledSyscalls(t);
Thread.futexWaitUncancelable(&num_completed.raw, 0, if (need_signal) timeout_ns else null);
switch (num_completed.load(.acquire)) { // 获取任务结果
0 => {},
1 => break,
else => unreachable,
}
timeout_ns <<|= 1;
}
}
};
/// 尾随数据:
/// 1. context
/// 2. result
const Future = struct {
runnable: Runnable,
func: *const fn (context: *const anyopaque, result: *anyopaque) void,
status: std.atomic.Value(Status),
/// 完成时递增此 `u32`,并对其执行 futex 唤醒。
awaiter: *std.atomic.Value(u32),
context_alignment: Alignment,
result_offset: usize,
alloc_len: usize,
const Status = packed struct(usize) {
/// 此枚举的取值经过选择,使 await/cancel 分别只需与 0b01 和 0b11 按位或。
/// 这确实会覆盖 `.done`,但并无妨碍,因为标签为 `.done` 时,
/// 仅有等待方仍在引用此 `Future`。
tag: enum(u2) {
/// future 已排队或正在运行(取决于是否设置 `thread`)。
pending = 0b00,
/// 类似 `pending`,但该 future 正被等待。已填充 `Future.awaiter`。
pending_awaited = 0b01,
/// 类似于 `pending`,但 future 正在取消。`Future.awaiter` 已填充。
pending_canceled = 0b11,
/// future 已完成。除非 future 因已确认的取消请求而终止,
/// 此时 `thread` 为 `.all_ones`,否则 `thread` 为 `.null`。
done = 0b10,
},
/// future 开始执行时,此字段以原子方式从 `null` 更新为运行该 `Future` 的线程,
/// 以便取消逻辑知道要取消哪个线程。
thread: Thread.PackedPtr,
};
/// 创建出的 `Future` 中,`Future.runnable.node` 为 `undefined`。
fn create(
gpa: Allocator,
result_len: usize,
result_alignment: Alignment,
context: []const u8,
context_alignment: Alignment,
func: *const fn (context: *const anyopaque, result: *anyopaque) void,
) Allocator.Error!*Future {
const max_context_misalignment = context_alignment.toByteUnits() -| @alignOf(Future);
const worst_case_context_offset = context_alignment.forward(@sizeOf(Future) + max_context_misalignment);
const worst_case_result_offset = result_alignment.forward(worst_case_context_offset + context.len);
const alloc_len = worst_case_result_offset + result_len;
const future: *Future = @ptrCast(@alignCast(try gpa.alignedAlloc(u8, .of(Future), alloc_len)));
errdefer comptime unreachable;
const actual_context_addr = context_alignment.forward(@intFromPtr(future) + @sizeOf(Future));
const actual_result_addr = result_alignment.forward(actual_context_addr + context.len);
const actual_result_offset = actual_result_addr - @intFromPtr(future);
future.* = .{
.runnable = .{
.node = undefined,
.startFn = &start,
},
.func = func,
.status = .init(.{
.tag = .pending,
.thread = .null,
}),
.awaiter = undefined,
.context_alignment = context_alignment,
.result_offset = actual_result_offset,
.alloc_len = alloc_len,
};
@memcpy(future.contextPointer()[0..context.len], context);
return future;
}
fn destroy(future: *Future, gpa: Allocator) void {
const base: [*]align(@alignOf(Future)) u8 = @ptrCast(future);
gpa.free(base[0..future.alloc_len]);
}
fn resultPointer(future: *Future) [*]u8 {
const base: [*]u8 = @ptrCast(future);
return base + future.result_offset;
}
fn contextPointer(future: *Future) [*]u8 {
const base: [*]u8 = @ptrCast(future);
const context_offset = future.context_alignment.forward(@intFromPtr(future) + @sizeOf(Future)) - @intFromPtr(future);
return base + context_offset;
}
fn start(r: *Runnable, thread: *Thread, t: *Threaded) void {
_ = t;
const future: *Future = @fieldParentPtr("runnable", r);
thread.status.store(.{
.cancelation = .none,
.awaitable = .fromFuture(future),
}, .monotonic);
{
const old_status = future.status.fetchOr(.{
.tag = .pending,
.thread = .pack(thread),
}, .release);
assert(old_status.thread == .null);
switch (old_status.tag) {
.pending, .pending_awaited => {},
.pending_canceled => thread.status.store(.{
.cancelation = .canceling,
.awaitable = .fromFuture(future),
}, .monotonic),
.done => unreachable,
}
}
future.func(future.contextPointer(), future.resultPointer());
const had_acknowledged_cancel = switch (thread.status.load(.monotonic).cancelation) {
.none, .canceling => false,
.canceled => true,
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
};
thread.status.store(.{ .cancelation = .none, .awaitable = .null }, .monotonic);
const old_status = future.status.swap(.{
.tag = .done,
.thread = if (had_acknowledged_cancel) .all_ones else .null,
}, .acq_rel); // 获取 `future.awaiter`,发布结果
switch (old_status.tag) {
.pending => {},
.pending_awaited, .pending_canceled => {
const to_signal = future.awaiter;
_ = to_signal.fetchAdd(1, .release); // 释放结果
Thread.futexWake(&to_signal.raw, 1);
},
.done => unreachable,
}
}
/// 调用方已取消 `future`。`thread` 是当前运行该 future 的线程。
/// 必要时将取消请求通知 `thread`,并等待 `future` 完成,以 `num_completed`
/// 从 0 增加到 1 为标志;必要时定期向 `thread` 发送信号,
/// 使其从可取消的系统调用中解除阻塞。
fn waitForCancelWithSignaling(
future: *Future,
t: *Threaded,
num_completed: *std.atomic.Value(u32),
thread: ?*Thread,
) void {
var need_signal: bool = if (thread) |th| th.cancelAwaitable(.fromFuture(future)) else false;
var timeout_ns: u64 = 1 << 10;
while (true) {
need_signal = need_signal and thread.?.signalCanceledSyscall(t, .fromFuture(future));
Thread.futexWaitUncancelable(&num_completed.raw, 0, if (need_signal) timeout_ns else null);
switch (num_completed.load(.acquire)) { // 获取任务结果
0 => {},
1 => break,
else => unreachable,
}
timeout_ns <<|= 1;
}
}
};
/// 唯一标识某个组或 future 的 (ptr_bit_width - 3) 位序列。它们是
/// `*Io.Group` 或 `*Future` 的最高有效位。这些地址末尾不一定有 3 个零位,
/// 因为仅按指针对齐,32 位目标上只有 2 个。但因为两者的
/// 大小都至少为 8 字节,内存中同时存在的任意两个组/future
/// 不可能在这些位上完全相同。换言之,给定一个组/future 指针,
/// 下一个组或 future 至少在其后 8 字节处,因此其地址最高
/// (ptr_bit_width - 3) 位中至少有一位不同。
const AwaitableId = enum(@Int(.unsigned, @bitSizeOf(usize) - 3)) {
comptime {
assert(@sizeOf(Future) >= 8);
assert(@sizeOf(Io.Group) >= 8);
}
null = 0,
all_ones = std.math.maxInt(@Int(.unsigned, @bitSizeOf(usize) - 3)),
_,
const Split = packed struct(usize) { low: u3, high: AwaitableId };
fn fromGroup(g: *Io.Group) AwaitableId {
const split: Split = @bitCast(@intFromPtr(g));
return split.high;
}
fn fromFuture(f: *Future) AwaitableId {
const split: Split = @bitCast(@intFromPtr(f));
return split.high;
}
};
const Thread = struct {
next: ?*Thread,
id: std.Thread.Id,
handle: Handle,
status: std.atomic.Value(Status),
cancel_protection: Io.CancelProtection,
/// `Status.cancelation` 设置为 `.parked` 时始终释放。
futex_waiter: if (use_parking_futex) ?*parking_futex.Waiter else ?noreturn,
unpark_flag: UnparkFlag,
park_tid: if (ParkTid == std.Thread.Id) void else ParkTid,
csprng: Csprng,
const Handle = Handle: {
if (std.Thread.use_pthreads) break :Handle std.c.pthread_t;
if (is_windows) break :Handle windows.HANDLE;
break :Handle void;
};
const Status = packed struct(usize) {
/// 这些枚举字段的具体取值旨在简化
/// 需要对此状态应用的变换的实现。
cancelation: enum(u3) {
/// 线程尚未取消,且不处于可取消操作中。
/// 要请求取消,只需将状态设为 `.canceling`。
none = 0b000,
/// 线程停驻于可取消的 futex 等待或休眠中。
/// 仅在 `use_parking_futex` 或 `use_parking_sleep` 时适用。
/// 请求取消时,将状态设为 `.canceling`,并唤回线程。
/// 因其他原因(futex 唤醒)唤回时,将状态设为 `.none`,并唤回线程。
parked = 0b001,
/// 线程阻塞在可取消的系统调用中。
/// 若要请求取消,将状态设为 `.blocked_canceling`,并反复中断该系统调用,直至状态改变。
blocked = 0b011,
/// 仅限 Windows:线程通过 `NtDelayExecution` 阻塞于可警报等待中。
/// 要请求取消,将状态设为
/// `blocked_alertable_canceling`,并反复向线程发出警报,
/// 直到状态改变。
blocked_alertable = 0b010,
/// 线程有未处理的取消请求,但当前不在可取消操作中。
/// 确认取消后,线程会将状态设置为 `.canceled`。
canceling = 0b110,
/// 线程已收到并确认取消请求。
/// 若调用 `recancel`,状态将恢复为 `.canceling`;否则,
/// 在此任务剩余的执行期间,状态不再变化。
canceled = 0b111,
/// 线程阻塞于可取消系统调用中,且正在
/// 被取消。触发取消的线程将持续向此线程
/// 发送信号,直到其状态改变。
blocked_canceling = 0b101,
/// 仅适用于 Windows:线程通过 `NtDelayExecution`
/// 阻塞于可警报等待中,且正在被取消。
/// 触发取消的线程将持续向此线程发送信号,
/// 直到其状态改变。
blocked_alertable_canceling = 0b100,
},
/// 不能将此值转换回指针。它的用途是允许通过对线程状态执行
/// cmpxchg 来取消任务:若线程正在运行待取消任务,
/// 则更新 `cancelation` 字段。
awaitable: AwaitableId,
};
const SignaleeId = if (std.Thread.use_pthreads) std.c.pthread_t else std.Thread.Id;
threadlocal var current: ?*Thread = null;
/// 不与任何其他线程 ID 重合的值。
const invalid_id: std.Thread.Id = std.math.maxInt(std.Thread.Id);
fn currentId() std.Thread.Id {
return if (current) |t| t.id else std.Thread.getCurrentId();
}
/// 线程既不在系统调用内,也未正在进入系统调用,但仍需检查取消。
/// 若存在待处理的取消请求,则确认该请求并返回 `error.Canceled`。
fn checkCancel() Io.Cancelable!void {
const thread = Thread.current orelse return;
switch (thread.cancel_protection) {
.blocked => return,
.unblocked => {},
}
// 与 `Syscall.checkCancel` 不同,此处取消的可能性并不高,因此
// 似乎更适合先执行低成本的原子加载,仅在低概率情况下单独存储
// 以确认取消。此外,此处需要的状态转换无法通过一次对
// `Status.cancelation` 的原子 OR/AND/XOR 完成,因此实际上也没有其他选择。
const status = thread.status.load(.monotonic);
switch (status.cancelation) {
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
.none, .canceled => {},
.canceling => {
thread.status.store(.{
.cancelation = .canceled,
.awaitable = status.awaitable,
}, .monotonic);
return error.Canceled;
},
}
}
fn futexWaitUncancelable(ptr: *const u32, expect: u32, timeout_ns: ?u64) void {
return Thread.futexWaitInner(ptr, expect, true, timeout_ns) catch unreachable;
}
fn futexWait(ptr: *const u32, expect: u32, timeout_ns: ?u64) Io.Cancelable!void {
return Thread.futexWaitInner(ptr, expect, false, timeout_ns);
}
fn futexWaitInner(ptr: *const u32, expect: u32, uncancelable: bool, timeout_ns: ?u64) Io.Cancelable!void {
@branchHint(.cold);
if (builtin.single_threaded) unreachable; // 没人会唤醒我们
if (use_parking_futex) {
return parking_futex.wait(
ptr,
expect,
uncancelable,
if (timeout_ns) |ns| .{ .duration = .{
.raw = .fromNanoseconds(ns),
.clock = .boot,
} } else .none,
);
} else if (builtin.cpu.arch.isWasm()) {
comptime assert(builtin.cpu.has(.wasm, .atomics));
// TODO 通过向 futex 发信号,实现 WASM futex 等待的取消
if (!uncancelable) try Thread.checkCancel();
const to: i64 = if (timeout_ns) |ns| std.math.cast(i64, ns) orelse std.math.maxInt(i64) else -1;
const signed_expect: i32 = @bitCast(expect);
const result = asm volatile (
\\local.get %[ptr]
\\local.get %[expected]
\\local.get %[timeout]
\\memory.atomic.wait32 0
\\local.set %[ret]
: [ret] "=r" (-> u32),
: [ptr] "r" (ptr),
[expected] "r" (signed_expect),
[timeout] "r" (to),
);
switch (result) {
0 => {}, // 成功
1 => {}, // expected != loaded
2 => {}, // 超时
else => assert(!is_debug),
}
} else switch (native_os) {
.linux => {
const linux = std.os.linux;
var ts_buffer: linux.timespec = undefined;
const ts: ?*linux.timespec = if (timeout_ns) |ns| ts: {
ts_buffer = timestampToPosix(ns);
break :ts &ts_buffer;
} else null;
const syscall: Syscall = if (uncancelable) .{ .thread = null } else try .start();
const rc = linux.futex_4arg(ptr, .{ .cmd = .WAIT, .private = true }, expect, ts);
syscall.finish();
switch (linux.errno(rc)) {
.SUCCESS => {}, // 由 `wake()` 通知
.INTR => {}, // 调用者负责重试
.AGAIN => {}, // ptr.* != expect
.INVAL => {}, // 可能发生超时溢出
.TIMEDOUT => {},
.FAULT => recoverableOsBugDetected(), // ptr 无效
else => recoverableOsBugDetected(),
}
},
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => {
const c = std.c;
const flags: c.UL = .{
.op = .COMPARE_AND_WAIT,
.NO_ERRNO = true,
};
const syscall: Syscall = if (uncancelable) .{ .thread = null } else try .start();
const status = switch (darwin_supports_ulock_wait2) {
true => c.__ulock_wait2(flags, ptr, expect, ns: {
const ns = timeout_ns orelse break :ns 0;
if (ns == 0) break :ns 1;
break :ns ns;
}, 0),
false => c.__ulock_wait(flags, ptr, expect, us: {
const ns = timeout_ns orelse break :us 0;
const us = std.math.lossyCast(u32, ns / std.time.ns_per_us);
if (us == 0) break :us 1;
break :us us;
}),
};
syscall.finish();
if (status >= 0) return;
switch (@as(c.E, @fromBackingInt(@intCast(-status)))) {
.INTR => {}, // 伪唤醒。
// futex 地址所在页被换出。这虽不常见,但理论上可能发生,
// 且 Darwin 上的 pthread/libdispatch 也会处理此情况。
// 此时直接返回,不执行等待,但调用者仍应重试。
.FAULT => {},
.TIMEDOUT => {}, // 超时
else => recoverableOsBugDetected(),
}
},
.freebsd => {
const flags = @backingInt(std.c.UMTX_OP.WAIT_UINT_PRIVATE);
var tm_size: usize = 0;
var tm: std.c._umtx_time = undefined;
var tm_ptr: ?*const std.c._umtx_time = null;
if (timeout_ns) |ns| {
tm_ptr = &tm;
tm_size = @sizeOf(@TypeOf(tm));
tm.flags = 0; // 使用相对时间,而非 UMTX_ABSTIME
tm.clockid = .MONOTONIC;
tm.timeout = timestampToPosix(ns);
}
const syscall: Syscall = if (uncancelable) .{ .thread = null } else try .start();
const rc = std.c._umtx_op(@intFromPtr(ptr), flags, @as(c_ulong, expect), tm_size, @intFromPtr(tm_ptr));
syscall.finish();
if (is_debug) switch (posix.errno(rc)) {
.SUCCESS => {},
.FAULT => unreachable, // 某个参数指向无效内存
.INVAL => unreachable, // 参数应当正确
.TIMEDOUT => {}, // 超时
.INTR => {}, // 虚假唤醒
else => unreachable,
};
},
.openbsd => {
var tm: std.c.timespec = undefined;
var tm_ptr: ?*const std.c.timespec = null;
if (timeout_ns) |ns| {
tm_ptr = &tm;
tm = timestampToPosix(ns);
}
const syscall: Syscall = if (uncancelable) .{ .thread = null } else try .start();
const rc = std.c.futex(
ptr,
std.c.FUTEX.WAIT | std.c.FUTEX.PRIVATE_FLAG,
@as(c_int, @bitCast(expect)),
tm_ptr,
null, // 忽略 uaddr2
);
syscall.finish();
if (is_debug) switch (posix.errno(rc)) {
.SUCCESS => {},
.NOSYS => unreachable, // 常量操作的已知有效值
.AGAIN => {}, // uaddr 处的内容 != val
.INVAL => unreachable, // 无效的超时时间
.TIMEDOUT => {}, // 超时
.INTR => {}, // 收到信号
.CANCELED => {}, // 收到信号,且已设置 SA_RESTART
else => unreachable,
};
},
.dragonfly => {
var timeout_us: c_int = undefined;
if (timeout_ns) |ns| {
timeout_us = std.math.cast(c_int, ns / std.time.ns_per_us) orelse std.math.maxInt(c_int);
} else {
timeout_us = 0;
}
const syscall: Syscall = if (uncancelable) .{ .thread = null } else try .start();
const rc = std.c.umtx_sleep(@ptrCast(ptr), @bitCast(expect), timeout_us);
syscall.finish();
if (is_debug) switch (std.posix.errno(rc)) {
.SUCCESS => {},
.BUSY => {}, // ptr != expect
.AGAIN => {}, // 可能已超时、已换出,或触发内核的 2 秒刷新。
.INTR => {}, // 虚假唤醒
.INVAL => unreachable, // 无效的超时时间
else => unreachable,
};
},
else => @compileError("unimplemented: futexWait"),
}
}
fn futexWake(ptr: *const u32, max_waiters: u32) void {
@branchHint(.cold);
assert(max_waiters != 0);
if (builtin.single_threaded) return; // 没有需要唤醒的对象
if (use_parking_futex) {
return parking_futex.wake(ptr, max_waiters);
} else if (builtin.cpu.arch.isWasm()) {
comptime assert(builtin.cpu.has(.wasm, .atomics));
const woken_count = asm volatile (
\\local.get %[ptr]
\\local.get %[waiters]
\\memory.atomic.notify 0
\\local.set %[ret]
: [ret] "=r" (-> u32),
: [ptr] "r" (ptr),
[waiters] "r" (max_waiters),
);
_ = woken_count; // 未启用链接器标志 'shared-memory' 时可以为 0。
} else switch (native_os) {
.linux => {
const linux = std.os.linux;
switch (linux.errno(linux.futex_3arg(
ptr,
.{ .cmd = .WAKE, .private = true },
@min(max_waiters, std.math.maxInt(i32)),
))) {
.SUCCESS => return, // 成功唤醒
.INVAL => return, // 其他位置对 ptr 进行了无效 futex_wait()
.FAULT => return, // 指针在执行唤醒时失效
else => return recoverableOsBugDetected(), // 因操作系统缺陷而死锁
}
},
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => {
const c = std.c;
const flags: c.UL = .{
.op = .COMPARE_AND_WAIT,
.NO_ERRNO = true,
.WAKE_ALL = max_waiters > 1,
};
while (true) {
const status = c.__ulock_wake(flags, ptr, 0);
if (status >= 0) return;
switch (@as(c.E, @fromBackingInt(@intCast(-status)))) {
.INTR, .CANCELED => continue, // 虚假的 wake()
.FAULT => unreachable, // 根据 darwin pthread_cond_t,__ulock_wake 不会产生 EFAULT
.NOENT => return, // 没有任何对象被唤醒
.ALREADY => unreachable, // 仅用于 UL.Op.WAKE_THREAD
else => unreachable, // 因操作系统缺陷而死锁
}
}
},
.freebsd => {
const rc = std.c._umtx_op(
@intFromPtr(ptr),
@backingInt(std.c.UMTX_OP.WAKE_PRIVATE),
@as(c_ulong, @min(max_waiters, std.math.maxInt(c_int))),
0, // 不存在超时结构
0, // 没有超时结构体指针
);
switch (posix.errno(rc)) {
.SUCCESS => {},
.FAULT => {}, // 即使 ptr 不指向有效内存也没有问题
.INVAL => unreachable, // 参数应当正确
else => unreachable, // 因操作系统缺陷而死锁
}
},
.openbsd => {
const rc = std.c.futex(
ptr,
std.c.FUTEX.WAKE | std.c.FUTEX.PRIVATE_FLAG,
@min(max_waiters, std.math.maxInt(c_int)),
null, // 忽略 timeout
null, // 忽略 uaddr2
);
assert(rc >= 0);
},
.dragonfly => {
// 除非地址无效,否则通常返回 0
_ = std.c.umtx_wakeup(
@ptrCast(ptr),
@min(max_waiters, std.math.maxInt(c_int)),
);
},
else => @compileError("unimplemented: futexWake"),
}
}
/// 如果 `thread` 正在处理 `awaitable`,则取消它。
///
/// `thread` 可能被此函数取消,但仍阻塞在系统调用中。
/// 此时可能需要向线程发送信号以中断调用。此函数会
/// 返回 `true` 表示此情况,此时调用方必须调用 `signalCanceledSyscall`。
fn cancelAwaitable(thread: *Thread, awaitable: AwaitableId) bool {
var status = thread.status.load(.monotonic);
while (true) {
if (status.awaitable != awaitable) return false; // 线程正在处理其他任务
status = switch (status.cancelation) {
.none => thread.status.cmpxchgWeak(
.{ .cancelation = .none, .awaitable = awaitable },
.{ .cancelation = .canceling, .awaitable = awaitable },
.monotonic,
.monotonic,
) orelse return false,
.parked => thread.status.cmpxchgWeak(
.{ .cancelation = .parked, .awaitable = awaitable },
.{ .cancelation = .canceling, .awaitable = awaitable },
.acquire, // 获取 `thread.futex_waiter`
.monotonic,
) orelse {
if (!use_parking_futex and !use_parking_sleep) unreachable;
if (thread.futex_waiter) |futex_waiter| {
parking_futex.removeCanceledWaiter(futex_waiter);
}
if (need_unpark_flag) setUnparkFlag(&thread.unpark_flag);
unpark(&.{if (ParkTid == std.Thread.Id) thread.id else thread.park_tid}, null);
return false;
},
.blocked => thread.status.cmpxchgWeak(
.{ .cancelation = .blocked, .awaitable = awaitable },
.{ .cancelation = .blocked_canceling, .awaitable = awaitable },
.monotonic,
.monotonic,
) orelse return true,
.blocked_alertable => thread.status.cmpxchgWeak(
.{ .cancelation = .blocked_alertable, .awaitable = awaitable },
.{ .cancelation = .blocked_alertable_canceling, .awaitable = awaitable },
.monotonic,
.monotonic,
) orelse {
if (!is_windows) unreachable;
return true;
},
.canceling, .canceled => {
// 任务启动与取消发生竞态时,可能出现此情况:线程
// 已看到 future/group 的取消状态,而我们仍在此尝试向
// 线程发送信号。
return false;
},
.blocked_canceling => unreachable, // `awaitable` 在此之前尚未被取消
.blocked_alertable_canceling => unreachable, // `awaitable` 在此之前尚未被取消
};
}
}
/// 如果 `thread` 仍阻塞在系统调用中,即尚未观察到
/// `cancelAwaitable` 发出的取消请求,则向其发送信号。
///
/// 遗憾的是,信号可能在系统调用真正开始之前到达,导致中断
/// 未能生效。为解决此问题,可能需要发送多次信号。因此,如果此函数
/// 返回 `true`,则应在短暂延迟后再次调用,以便在线程
/// 仍阻塞时重新发送信号。实现参见 `Future.waitForCancelWithSignaling` 和
/// `Group.waitForCancelWithSignaling`:它们使用指数退避,从 1 微秒开始,
/// 每次调用延迟翻倍。实际很少需要发送一个以上的信号。
fn signalCanceledSyscall(thread: *Thread, t: *Threaded, awaitable: AwaitableId) bool {
const status = thread.status.load(.monotonic);
if (status.awaitable != awaitable) {
// 线程已继续运行,并正在执行完全不同的工作。
return false;
}
// 线程标识和/或句柄可非原子读取,因为它们不会变化,
// 且使 `thread` 对我们可见的存储已对它们执行释放。
switch (status.cancelation) {
.blocked_canceling => if (std.Thread.use_pthreads) {
return switch (std.c.pthread_kill(thread.handle, .IO)) {
0 => true,
else => false,
};
} else switch (native_os) {
.linux => {
const pid: posix.pid_t = pid: {
const cached_pid = @atomicLoad(Pid, &t.pid, .monotonic);
if (cached_pid != .unknown) break :pid @backingInt(cached_pid);
const pid = std.os.linux.getpid();
@atomicStore(Pid, &t.pid, @fromBackingInt(@intCast(pid)), .monotonic);
break :pid pid;
};
return switch (std.os.linux.tgkill(pid, @bitCast(thread.id), .IO)) {
0 => true,
else => false,
};
},
.windows => {
var iosb: windows.IO_STATUS_BLOCK = undefined;
return switch (windows.ntdll.NtCancelSynchronousIoFile(thread.handle, null, &iosb)) {
.NOT_FOUND => true, // 这可能表示操作尚未开始
.SUCCESS => false, // 操作系统已确认取消成功
else => false,
};
},
else => return false,
},
.blocked_alertable_canceling => {
if (!is_windows) unreachable;
return switch (windows.ntdll.NtAlertThread(thread.handle)) {
.SUCCESS => true,
else => false,
};
},
else => {
// 线程正在处理 `awaitable`,但不再需要信号通知,
// 因为它已被唤醒并看到取消请求。
return false;
},
}
}
/// 类似 `*Thread`,但比指针少 2 位,因为对齐保证最低有效位始终为 0,
/// 从而可在 `packed struct` 中使用这两位。
const PackedPtr = enum(@Int(.unsigned, @bitSizeOf(usize) - 2)) {
null = 0,
all_ones = std.math.maxInt(@Int(.unsigned, @bitSizeOf(usize) - 2)),
_,
const Split = packed struct(usize) { low: u2, high: PackedPtr };
fn pack(ptr: *Thread) PackedPtr {
const split: Split = @bitCast(@intFromPtr(ptr));
assert(split.low == 0);
return split.high;
}
fn unpack(ptr: PackedPtr) ?*Thread {
const split: Split = .{ .low = 0, .high = ptr };
return @ptrFromInt(@as(usize, @bitCast(split)));
}
};
};
const Syscall = struct {
thread: ?*Thread,
/// 标记进入系统调用区域。其作用域应紧密围绕实际系统调用,
/// 以尽量减少竞态。必须通过 `checkCancel`、`finish`
/// 或 `finish` 的某个封装,将系统调用标记为“已完成”。
fn start() Io.Cancelable!Syscall {
const thread = Thread.current orelse return .{ .thread = null };
switch (thread.cancel_protection) {
.blocked => return .{ .thread = null },
.unblocked => {},
}
switch (thread.status.fetchOr(.{
.cancelation = @fromBackingInt(@intCast(0b011)),
.awaitable = .null,
}, .monotonic).cancelation) {
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
.none => return .{ .thread = thread }, // 新状态为 `.blocked`
.canceling => return error.Canceled, // 新状态为 `.canceled`
.canceled => return .{ .thread = null }, // 新状态为 `.canceled`(不变)
}
}
/// 检查此系统调用是否已取消。当系统调用被某种机制
/// 中断,而该中断可能表示取消,也可能是伪中断时,应调用此函数。
/// 如果系统调用已取消,则将其标记为完成并返回 `error.Canceled`。否则,
/// 不将系统调用标记为完成,调用方应重试。
fn checkCancel(s: Syscall) Io.Cancelable!void {
const thread = s.thread orelse return;
switch (thread.status.fetchOr(.{
.cancelation = @fromBackingInt(@intCast(0b010)),
.awaitable = .null,
}, .monotonic).cancelation) {
.none => unreachable,
.parked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.canceling => unreachable,
.canceled => unreachable,
.blocked => {}, // 新状态为 `.blocked`(不变)
.blocked_canceling => return error.Canceled, // 新状态为 `.canceled`
}
}
/// 将此系统调用标记为已完成。
fn finish(s: Syscall) void {
const thread = s.thread orelse return;
switch (thread.status.fetchXor(.{
.cancelation = @fromBackingInt(@intCast(0b011)),
.awaitable = .null,
}, .monotonic).cancelation) {
.none => unreachable,
.parked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.canceling => unreachable,
.canceled => unreachable,
.blocked => {}, // 新状态为 `.none`
.blocked_canceling => {}, // 新状态为 `.canceling`
}
}
/// 表示需要使用 `NtAlertThread` 中断等待,而不是 `NtCancelSynchronousIoFile`。
///
/// 仅限 Windows,且仅从阻塞状态调用。
///
fn toAlertable(s: Syscall) Io.Cancelable!AlertableSyscall {
comptime assert(is_windows);
const thread = s.thread orelse return .{ .thread = null };
var prev = thread.status.load(.monotonic);
while (true) prev = switch (prev.cancelation) {
.none => unreachable,
.parked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.canceling => unreachable,
.canceled => unreachable,
.blocked => thread.status.cmpxchgWeak(prev, .{
.cancelation = .blocked_alertable,
.awaitable = prev.awaitable,
}, .monotonic, .monotonic) orelse return .{ .thread = thread },
.blocked_canceling => thread.status.cmpxchgWeak(prev, .{
.cancelation = .canceled,
.awaitable = prev.awaitable,
}, .monotonic, .monotonic) orelse return error.Canceled,
};
}
/// 便捷封装:调用 `finish`,然后返回 `err`。
fn fail(s: Syscall, err: anytype) @TypeOf(err) {
s.finish();
return err;
}
/// 便捷封装:先调用 `finish`,再调用 `Threaded.errnoBug`。
fn errnoBug(s: Syscall, err: posix.E) Io.UnexpectedError {
@branchHint(.cold);
s.finish();
return Threaded.errnoBug(err);
}
/// 便捷封装:先调用 `finish`,再调用 `posix.unexpectedErrno`。
fn unexpectedErrno(s: Syscall, err: posix.E) Io.UnexpectedError {
@branchHint(.cold);
s.finish();
return posix.unexpectedErrno(err);
}
/// 便捷封装:先调用 `finish`,再调用 `windows.statusBug`。
fn ntstatusBug(s: Syscall, status: windows.NTSTATUS) Io.UnexpectedError {
@branchHint(.cold);
s.finish();
return windows.statusBug(status);
}
/// 便捷封装:先调用 `finish`,再调用 `windows.unexpectedStatus`。
fn unexpectedNtstatus(s: Syscall, status: windows.NTSTATUS) Io.UnexpectedError {
@branchHint(.cold);
s.finish();
return windows.unexpectedStatus(status);
}
};
const AlertableSyscall = struct {
thread: ?*Thread,
comptime {
assert(is_windows);
}
fn start() Io.Cancelable!AlertableSyscall {
const thread = Thread.current orelse return .{ .thread = null };
switch (thread.cancel_protection) {
.blocked => return .{ .thread = null },
.unblocked => {},
}
const old_status = thread.status.fetchOr(.{
.cancelation = @fromBackingInt(@intCast(0b010)),
.awaitable = .null,
}, .monotonic);
switch (old_status.cancelation) {
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_canceling => unreachable,
.blocked_alertable_canceling => unreachable,
.none => return .{ .thread = thread }, // 新状态为 `.blocked_alertable`
.canceling => {
// 状态未变(仍为 `.canceling`)——返回前改为 `.canceled`。
thread.status.store(.{ .cancelation = .canceled, .awaitable = old_status.awaitable }, .monotonic);
return error.Canceled;
},
.canceled => return .{ .thread = null }, // 新状态为 `.canceled`(不变)
}
}
fn checkCancel(s: AlertableSyscall) Io.Cancelable!void {
comptime assert(is_windows);
const thread = s.thread orelse return;
const old_status = thread.status.fetchOr(.{
.cancelation = @fromBackingInt(@intCast(0b010)),
.awaitable = .null,
}, .monotonic);
switch (old_status.cancelation) {
.none => unreachable,
.parked => unreachable,
.blocked => unreachable,
.blocked_canceling => unreachable,
.canceling => unreachable,
.canceled => unreachable,
.blocked_alertable => {}, // 新状态为 `.blocked_alertable`(未改变)
.blocked_alertable_canceling => {
// 新状态为 `.canceling`,返回前改为 `.canceled`。
thread.status.store(.{ .cancelation = .canceled, .awaitable = old_status.awaitable }, .monotonic);
return error.Canceled;
},
}
}
fn finish(s: AlertableSyscall) void {
comptime assert(is_windows);
const thread = s.thread orelse return;
switch (thread.status.fetchXor(.{
.cancelation = @fromBackingInt(@intCast(0b010)),
.awaitable = .null,
}, .monotonic).cancelation) {
.none => unreachable,
.parked => unreachable,
.blocked => unreachable,
.blocked_canceling => unreachable,
.canceling => unreachable,
.canceled => unreachable,
.blocked_alertable => {}, // 新状态为 `.none`
.blocked_alertable_canceling => {}, // 新状态为 `.canceling`
}
}
fn fail(s: AlertableSyscall, err: anytype) @TypeOf(err) {
s.finish();
return err;
}
fn ntstatusBug(s: AlertableSyscall, status: windows.NTSTATUS) Io.UnexpectedError {
@branchHint(.cold);
s.finish();
return windows.statusBug(status);
}
fn unexpectedNtstatus(s: AlertableSyscall, status: windows.NTSTATUS) Io.UnexpectedError {
@branchHint(.cold);
s.finish();
return windows.unexpectedStatus(status);
}
};
pub fn waitForApcOrAlert() void {
const infinite_timeout: windows.LARGE_INTEGER = std.math.minInt(windows.LARGE_INTEGER);
_ = windows.ntdll.NtDelayExecution(.TRUE, &infinite_timeout);
}
pub const max_iovecs_len = 8;
pub const splat_buffer_size = 64;
/// 此值恰好与 NtWaitForMultipleObjects 接受的
/// 最大句柄数相同。POSIX 系统上的 poll()
/// 也使用此值。
const poll_buffer_len = 64;
pub const default_PATH = "/usr/local/bin:/bin:/usr/bin";
/// 通过重试规避多个内核缺陷。
const max_windows_kernel_bug_retries = 13;
comptime {
if (@TypeOf(posix.IOV_MAX) != void) assert(max_iovecs_len <= posix.IOV_MAX);
}
pub const InitOptions = struct {
/// 影响为线程进行内存映射的字节数。
stack_size: usize = std.Thread.SpawnConfig.default_stack_size,
/// 分派异步任务时的线程池最大大小,不包括主线程。在达到限制之前,若全部线程都忙,调用 `Io.async` 会创建新线程,并永久加入线程池。达到限制之后,若全部线程都忙,调用 `Io.async` 会立即执行任务。
///
/// 默认值为逻辑处理器核心数减一。
///
/// I/O 实例开始使用后,由 `Threaded.mutex` 保护。参见 `setAsyncLimit`。
///
///
///
///
///
async_limit: ?Io.Limit = null,
/// 用于分派并发任务的线程池大小上限,不包括主线程。
/// 达到此上限之前,调用 `Io.concurrent` 会增加线程
/// 池大小。
///
/// 超过此数量后,调用 `Io.concurrent` 返回 `error.ConcurrencyUnavailable`。
concurrent_limit: Io.Limit = .unlimited,
/// 影响以下操作:
/// * OpenBSD 和 Haiku 上的 `processExecutablePath`。
argv0: Argv0 = .empty,
/// 影响以下操作:
/// * `fileIsTty`
/// * OpenBSD 和 Haiku 上的 `processExecutablePath`(读取“PATH”)。
/// * `processSpawn`、`processSpawnPath`、`processReplace`、`processReplacePath`
environ: process.Environ = .empty,
/// 若设为 `true`,则 `File.MemoryMap` API 始终采用回退路径。
disable_memory_mapping: bool = false,
};
/// 相关项:
/// * `init_single_threaded`
pub fn init(
/// 必须线程安全。仅用于以下函数:
/// * `Io.VTable.async`
/// * `Io.VTable.concurrent`
/// * `Io.VTable.groupAsync`
/// * `Io.VTable.groupConcurrent`
/// 如果不使用这些函数,则可在此传入
/// `Allocator.failing`。
gpa: Allocator,
options: InitOptions,
) Threaded {
if (builtin.single_threaded) return .{
.allocator = gpa,
.stack_size = options.stack_size,
.async_limit = options.async_limit orelse init_single_threaded.async_limit,
.cpu_count_error = init_single_threaded.cpu_count_error,
.concurrent_limit = options.concurrent_limit,
.old_sig_io = undefined,
.old_sig_pipe = undefined,
.have_signal_handler = init_single_threaded.have_signal_handler,
.argv0 = options.argv0,
.environ_initialized = options.environ.block.isEmpty(),
.environ = .{ .process_environ = options.environ },
.worker_threads = init_single_threaded.worker_threads,
.disable_memory_mapping = options.disable_memory_mapping,
};
const cpu_count = std.Thread.getCpuCount();
var t: Threaded = .{
.allocator = gpa,
.stack_size = options.stack_size,
.async_limit = options.async_limit orelse if (cpu_count) |n| .limited(n - 1) else |_| .nothing,
.concurrent_limit = options.concurrent_limit,
.cpu_count_error = if (cpu_count) |_| null else |e| e,
.old_sig_io = undefined,
.old_sig_pipe = undefined,
.have_signal_handler = false,
.argv0 = options.argv0,
.environ_initialized = options.environ.block.isEmpty(),
.environ = .{ .process_environ = options.environ },
.worker_threads = .init(null),
.disable_memory_mapping = options.disable_memory_mapping,
};
if (posix.Sigaction != void) {
// 向线程发送 `posix.SIG.IO` 会因此中断阻塞的
// 系统调用,并返回 `posix.E.INTR`。
const act: posix.Sigaction = .{
.handler = .{ .handler = doNothingSignalHandler },
.mask = posix.sigemptyset(),
.flags = 0,
};
if (have_sig_io) posix.sigaction(.IO, &act, &t.old_sig_io);
if (have_sig_pipe) posix.sigaction(.PIPE, &act, &t.old_sig_pipe);
t.have_signal_handler = true;
}
return t;
}
/// 静态初始化,使 `Io.VTable.concurrent` 调用会以
/// `error.ConcurrencyUnavailable` 失败。
///
/// 采用此种初始化时:
/// * 取消请求无效。
/// * 可以安全调用 `deinit`,但没有必要。
pub const init_single_threaded: Threaded = init: {
const env_block: process.Environ.Block = if (is_windows) .global else .empty;
break :init .{
.allocator = .failing,
.stack_size = std.Thread.SpawnConfig.default_stack_size,
.async_limit = .nothing,
.cpu_count_error = null,
.concurrent_limit = .nothing,
.old_sig_io = undefined,
.old_sig_pipe = undefined,
.have_signal_handler = false,
.argv0 = .empty,
.environ_initialized = env_block.isEmpty(),
.environ = .{ .process_environ = .{ .block = env_block } },
.worker_threads = .init(null),
.disable_memory_mapping = false,
};
};
var global_single_threaded_instance: Threaded = .init_single_threaded;
/// 通常,应用程序负责选择 `Io` 实现,库代码应接受 `Io` 参数,而不是访问此声明。多数代码应完全避免引用此声明。
///
/// 不过,在调试等某些情况下,可能希望硬编码对此 `Io` 实现的引用。
///
/// 此实例不支持并发或取消。
///
///
///
///
pub const global_single_threaded: *Threaded = &global_single_threaded_instance;
pub fn setAsyncLimit(t: *Threaded, new_limit: Io.Limit) void {
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
t.async_limit = new_limit;
}
pub fn deinit(t: *Threaded) void {
t.join();
if (posix.Sigaction != void and t.have_signal_handler) {
if (have_sig_io) posix.sigaction(.IO, &t.old_sig_io, null);
if (have_sig_pipe) posix.sigaction(.PIPE, &t.old_sig_pipe, null);
}
t.dl.deinit();
t.null_file.deinit();
t.random_file.deinit();
t.pipe_file.deinit();
t.* = undefined;
}
fn join(t: *Threaded) void {
if (builtin.single_threaded) return;
{
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
t.join_requested = true;
}
condBroadcast(&t.cond);
t.wait_group.wait();
}
fn worker(t: *Threaded) void {
var thread: Thread = .{
.next = undefined,
.id = std.Thread.getCurrentId(),
.handle = handle: {
if (std.Thread.use_pthreads) break :handle std.c.pthread_self();
if (is_windows) break :handle undefined; // 在下方填充
},
.status = .init(.{
.cancelation = .none,
.awaitable = .null,
}),
.cancel_protection = .unblocked,
.futex_waiter = undefined,
.unpark_flag = unpark_flag_init,
.park_tid = if (ParkTid == std.Thread.Id) {} else getParkTid(),
.csprng = .uninitialized,
};
Thread.current = &thread;
if (is_windows) {
assert(windows.ntdll.NtOpenThread(
&thread.handle,
.{
.SPECIFIC = .{
.THREAD = .{
.TERMINATE = true, // 用于 `NtCancelSynchronousIoFile`
.ALERT = true, // 用于 `NtAlertThread`
},
},
},
&.{ .ObjectName = null },
&windows.teb().ClientId,
) == .SUCCESS);
}
defer if (is_windows) {
windows.CloseHandle(thread.handle);
};
{
var head = t.worker_threads.load(.monotonic);
while (true) {
thread.next = head;
head = t.worker_threads.cmpxchgWeak(
head,
&thread,
.release,
.monotonic,
) orelse break;
}
}
defer t.wait_group.finish();
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
while (true) {
while (t.run_queue.popFirst()) |runnable_node| {
mutexUnlock(&t.mutex);
thread.cancel_protection = .unblocked;
const runnable: *Runnable = @fieldParentPtr("node", runnable_node);
runnable.startFn(runnable, &thread, t);
mutexLockUncancelable(&t.mutex);
t.busy_count -= 1;
}
if (t.join_requested) break;
condWait(&t.cond, &t.mutex);
}
}
pub fn io(t: *Threaded) Io {
return .{
.userdata = t,
.vtable = &.{
.crashHandler = crashHandler,
.async = async,
.concurrent = concurrent,
.await = await,
.cancel = cancel,
.groupAsync = groupAsync,
.groupConcurrent = groupConcurrent,
.groupAwait = groupAwait,
.groupCancel = groupCancel,
.recancel = recancel,
.swapCancelProtection = swapCancelProtection,
.checkCancel = checkCancel,
.futexWait = futexWait,
.futexWaitUncancelable = futexWaitUncancelable,
.futexWake = futexWake,
.operate = operate,
.batchAwaitAsync = batchAwaitAsync,
.batchAwaitConcurrent = batchAwaitConcurrent,
.batchCancel = batchCancel,
.dirCreateDir = dirCreateDir,
.dirCreateDirPath = dirCreateDirPath,
.dirCreateDirPathOpen = dirCreateDirPathOpen,
.dirStat = dirStat,
.dirStatFile = dirStatFile,
.dirAccess = dirAccess,
.dirCreateFile = dirCreateFile,
.dirCreateFileAtomic = dirCreateFileAtomic,
.dirOpenFile = dirOpenFile,
.dirOpenDir = dirOpenDir,
.dirClose = dirClose,
.dirRead = dirRead,
.dirRealPath = dirRealPath,
.dirRealPathFile = dirRealPathFile,
.dirDeleteFile = dirDeleteFile,
.dirDeleteDir = dirDeleteDir,
.dirRename = dirRename,
.dirRenamePreserve = dirRenamePreserve,
.dirSymLink = dirSymLink,
.dirReadLink = dirReadLink,
.dirSetOwner = dirSetOwner,
.dirSetFileOwner = dirSetFileOwner,
.dirSetPermissions = dirSetPermissions,
.dirSetFilePermissions = dirSetFilePermissions,
.dirSetTimestamps = dirSetTimestamps,
.dirHardLink = dirHardLink,
.fileStat = fileStat,
.fileLength = fileLength,
.fileClose = fileClose,
.fileWritePositional = fileWritePositional,
.fileWriteFileStreaming = fileWriteFileStreaming,
.fileWriteFilePositional = fileWriteFilePositional,
.fileReadPositional = fileReadPositional,
.fileSeekBy = fileSeekBy,
.fileSeekTo = fileSeekTo,
.fileSync = fileSync,
.fileIsTty = fileIsTty,
.fileEnableAnsiEscapeCodes = fileEnableAnsiEscapeCodes,
.fileSupportsAnsiEscapeCodes = fileSupportsAnsiEscapeCodes,
.fileSetLength = fileSetLength,
.fileSetOwner = fileSetOwner,
.fileSetPermissions = fileSetPermissions,
.fileSetTimestamps = fileSetTimestamps,
.fileLock = fileLock,
.fileTryLock = fileTryLock,
.fileUnlock = fileUnlock,
.fileDowngradeLock = fileDowngradeLock,
.fileRealPath = fileRealPath,
.fileHardLink = fileHardLink,
.fileMemoryMapCreate = fileMemoryMapCreate,
.fileMemoryMapDestroy = fileMemoryMapDestroy,
.fileMemoryMapSetLength = fileMemoryMapSetLength,
.fileMemoryMapRead = fileMemoryMapRead,
.fileMemoryMapWrite = fileMemoryMapWrite,
.processExecutableOpen = processExecutableOpen,
.processExecutablePath = processExecutablePath,
.lockStderr = lockStderr,
.tryLockStderr = tryLockStderr,
.unlockStderr = unlockStderr,
.processCurrentPath = processCurrentPath,
.processSetCurrentDir = processSetCurrentDir,
.processSetCurrentPath = processSetCurrentPath,
.processReplace = processReplace,
.processSpawn = processSpawn,
.childWait = childWait,
.childKill = childKill,
.progressParentFile = progressParentFile,
.inheritParentDir = inheritParentDir,
.inheritParentFile = inheritParentFile,
.now = now,
.clockResolution = clockResolution,
.sleep = sleep,
.random = random,
.randomSecure = randomSecure,
.netListenIp = switch (native_os) {
.windows => netListenIpWindows,
else => netListenIpPosix,
},
.netListenUnix = switch (native_os) {
.windows => netListenUnixWindows,
else => netListenUnixPosix,
},
.netAccept = switch (native_os) {
.windows => netAcceptWindows,
else => netAcceptPosix,
},
.netBindIp = switch (native_os) {
.windows => netBindIpWindows,
else => netBindIpPosix,
},
.netConnectIp = switch (native_os) {
.windows => netConnectIpWindows,
else => netConnectIpPosix,
},
.netConnectUnix = switch (native_os) {
.windows => netConnectUnixWindows,
else => netConnectUnixPosix,
},
.netSocketCreatePair = netSocketCreatePair,
.netClose = netClose,
.netShutdown = switch (native_os) {
.windows => netShutdownWindows,
else => netShutdownPosix,
},
.netWriteFile = netWriteFile,
.netInterfaceNameResolve = netInterfaceNameResolve,
.netInterfaceName = netInterfaceName,
.netLookup = netLookup,
},
};
}
pub const socket_flags_unsupported = is_darwin or native_os == .haiku;
const have_accept4 = !socket_flags_unsupported;
const have_flock_open_flags = @hasField(posix.O, "EXLOCK");
const have_networking = std.options.networking and native_os != .wasi;
const have_flock = @TypeOf(posix.system.flock) != void;
const have_sendmmsg = native_os == .linux;
const have_futex = switch (builtin.cpu.arch) {
.wasm32, .wasm64 => builtin.cpu.has(.wasm, .atomics),
else => true,
};
const have_preadv = switch (native_os) {
.windows, .haiku => false,
else => true,
};
const have_sig_io = posix.SIG != void and @hasField(posix.SIG, "IO");
const have_sig_pipe = posix.SIG != void and @hasField(posix.SIG, "PIPE");
const have_sendfile = if (builtin.link_libc) @TypeOf(std.c.sendfile) != void else native_os == .linux;
const have_copy_file_range = switch (native_os) {
.linux, .freebsd => true,
else => false,
};
const have_fcntl = switch (native_os) {
.linux, .dragonfly, .freebsd, .netbsd, .openbsd, .illumos, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => true,
else => false,
};
const have_fcopyfile = is_darwin;
const have_fchmodat2 = native_os == .linux and
(builtin.os.isAtLeast(.linux, .{ .major = 6, .minor = 6, .patch = 0 }) orelse true) and
(builtin.abi.isAndroid() or !std.c.versionCheck(.{ .major = 2, .minor = 32, .patch = 0 }));
const have_fchmodat_flags = native_os != .linux or
(!builtin.abi.isAndroid() and std.c.versionCheck(.{ .major = 2, .minor = 32, .patch = 0 }));
const have_fchown = switch (native_os) {
.wasi, .windows => false,
else => true,
};
const have_fchmod = switch (native_os) {
.windows => false,
.wasi => builtin.link_libc,
else => true,
};
const have_waitid = switch (native_os) {
.linux => @hasField(std.os.linux.SYS, "waitid"),
else => false,
};
const have_wait4 = switch (native_os) {
.linux => @hasField(std.os.linux.SYS, "wait4"),
.dragonfly, .freebsd, .netbsd, .openbsd, .illumos, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => true,
else => false,
};
const have_mmap = switch (native_os) {
.wasi, .windows => false,
else => true,
};
const have_poll = switch (native_os) {
.wasi, .windows => false,
else => true,
};
const open_sym = if (posix.lfs64_abi) posix.system.open64 else posix.system.open;
const openat_sym = if (posix.lfs64_abi) posix.system.openat64 else posix.system.openat;
const fstat_sym = if (posix.lfs64_abi) posix.system.fstat64 else posix.system.fstat;
const fstatat_sym = if (posix.lfs64_abi) posix.system.fstatat64 else posix.system.fstatat;
const lseek_sym = if (posix.lfs64_abi) posix.system.lseek64 else posix.system.lseek;
const preadv_sym = if (posix.lfs64_abi) posix.system.preadv64 else posix.system.preadv;
const pread_sym = if (posix.lfs64_abi) posix.system.pread64 else posix.system.pread;
const ftruncate_sym = if (posix.lfs64_abi) posix.system.ftruncate64 else posix.system.ftruncate;
const pwritev_sym = if (posix.lfs64_abi) posix.system.pwritev64 else posix.system.pwritev;
const pwrite_sym = if (posix.lfs64_abi) posix.system.pwrite64 else posix.system.pwrite;
const sendfile_sym = if (posix.lfs64_abi) posix.system.sendfile64 else posix.system.sendfile;
const mmap_sym = if (posix.lfs64_abi) posix.system.mmap64 else posix.system.mmap;
const linux_copy_file_range_use_c = std.c.versionCheck(if (builtin.abi.isAndroid()) .{
.major = 34,
.minor = 0,
.patch = 0,
} else .{
.major = 2,
.minor = 27,
.patch = 0,
});
const linux_copy_file_range_sys = if (linux_copy_file_range_use_c) std.c else std.os.linux;
const statx_use_c = std.c.versionCheck(if (builtin.abi.isAndroid())
.{ .major = 30, .minor = 0, .patch = 0 }
else
.{ .major = 2, .minor = 28, .patch = 0 });
const use_libc_getrandom = std.c.versionCheck(if (builtin.abi.isAndroid()) .{
.major = 28,
.minor = 0,
.patch = 0,
} else .{
.major = 2,
.minor = 25,
.patch = 0,
});
const use_dev_urandom = @TypeOf(posix.system.getrandom) == void and native_os == .linux;
fn crashHandler(userdata: ?*anyopaque) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const thread = Thread.current orelse return;
thread.status.store(.{ .cancelation = .canceled, .awaitable = .null }, .monotonic);
thread.cancel_protection = .blocked;
}
fn async(
userdata: ?*anyopaque,
result: []u8,
result_alignment: Alignment,
context: []const u8,
context_alignment: Alignment,
start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) ?*Io.AnyFuture {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (builtin.single_threaded) {
start(context.ptr, result.ptr);
return null;
}
const gpa = t.allocator;
const future = Future.create(gpa, result.len, result_alignment, context, context_alignment, start) catch |err| switch (err) {
error.OutOfMemory => {
start(context.ptr, result.ptr);
return null;
},
};
mutexLockUncancelable(&t.mutex);
const busy_count = t.busy_count;
if (busy_count >= @backingInt(t.async_limit)) {
mutexUnlock(&t.mutex);
future.destroy(gpa);
start(context.ptr, result.ptr);
return null;
}
t.busy_count = busy_count + 1;
const pool_size = t.wait_group.value();
if (pool_size - busy_count == 0) {
t.wait_group.start();
const thread = std.Thread.spawn(.{ .stack_size = t.stack_size }, worker, .{t}) catch {
t.wait_group.finish();
t.busy_count = busy_count;
mutexUnlock(&t.mutex);
future.destroy(gpa);
start(context.ptr, result.ptr);
return null;
};
thread.detach();
}
t.run_queue.prepend(&future.runnable.node);
mutexUnlock(&t.mutex);
condSignal(&t.cond);
return @ptrCast(future);
}
fn concurrent(
userdata: ?*anyopaque,
result_len: usize,
result_alignment: Alignment,
context: []const u8,
context_alignment: Alignment,
start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) Io.ConcurrentError!*Io.AnyFuture {
if (builtin.single_threaded) return error.ConcurrencyUnavailable;
const t: *Threaded = @ptrCast(@alignCast(userdata));
const gpa = t.allocator;
const future = Future.create(gpa, result_len, result_alignment, context, context_alignment, start) catch |err| switch (err) {
error.OutOfMemory => return error.ConcurrencyUnavailable,
};
errdefer future.destroy(gpa);
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
const busy_count = t.busy_count;
if (busy_count >= @backingInt(t.concurrent_limit))
return error.ConcurrencyUnavailable;
t.busy_count = busy_count + 1;
errdefer t.busy_count = busy_count;
const pool_size = t.wait_group.value();
if (pool_size - busy_count == 0) {
t.wait_group.start();
errdefer t.wait_group.finish();
const thread = std.Thread.spawn(.{ .stack_size = t.stack_size }, worker, .{t}) catch
return error.ConcurrencyUnavailable;
thread.detach();
}
t.run_queue.prepend(&future.runnable.node);
condSignal(&t.cond);
return @ptrCast(future);
}
fn groupAsync(
userdata: ?*anyopaque,
type_erased: *Io.Group,
context: []const u8,
context_alignment: Alignment,
start: *const fn (context: *const anyopaque) void,
) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const g: Group = .{ .ptr = type_erased };
if (builtin.single_threaded) return groupAsyncEager(start, context.ptr);
const gpa = t.allocator;
const task = Group.Task.create(gpa, g, context, context_alignment, start) catch |err| switch (err) {
error.OutOfMemory => return groupAsyncEager(start, context.ptr),
};
mutexLockUncancelable(&t.mutex);
const busy_count = t.busy_count;
if (busy_count >= @backingInt(t.async_limit)) {
mutexUnlock(&t.mutex);
task.destroy(gpa);
return groupAsyncEager(start, context.ptr);
}
t.busy_count = busy_count + 1;
const pool_size = t.wait_group.value();
if (pool_size - busy_count == 0) {
t.wait_group.start();
const thread = std.Thread.spawn(.{ .stack_size = t.stack_size }, worker, .{t}) catch {
t.wait_group.finish();
t.busy_count = busy_count;
mutexUnlock(&t.mutex);
task.destroy(gpa);
return groupAsyncEager(start, context.ptr);
};
thread.detach();
}
// TODO: 若将此逻辑改为无锁实现,队列的前插操作必须以 release 语义发布此 `fetchAdd`,
// 以免任务结束时尚未观察到这次操作,
// 从而尝试将计数减至零以下。
_ = g.status().fetchAdd(.{
.num_running = 1,
.have_awaiter = false,
.canceled = false,
}, .monotonic);
t.run_queue.prepend(&task.runnable.node);
mutexUnlock(&t.mutex);
condSignal(&t.cond);
}
fn groupAsyncEager(
start: *const fn (context: *const anyopaque) void,
context: *const anyopaque,
) void {
start(context);
}
fn groupConcurrent(
userdata: ?*anyopaque,
type_erased: *Io.Group,
context: []const u8,
context_alignment: Alignment,
start: *const fn (context: *const anyopaque) void,
) Io.ConcurrentError!void {
if (builtin.single_threaded) return error.ConcurrencyUnavailable;
const t: *Threaded = @ptrCast(@alignCast(userdata));
const g: Group = .{ .ptr = type_erased };
const gpa = t.allocator;
const task = Group.Task.create(gpa, g, context, context_alignment, start) catch |err| switch (err) {
error.OutOfMemory => return error.ConcurrencyUnavailable,
};
errdefer task.destroy(gpa);
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
const busy_count = t.busy_count;
if (busy_count >= @backingInt(t.concurrent_limit))
return error.ConcurrencyUnavailable;
t.busy_count = busy_count + 1;
errdefer t.busy_count = busy_count;
const pool_size = t.wait_group.value();
if (pool_size - busy_count == 0) {
t.wait_group.start();
errdefer t.wait_group.finish();
const thread = std.Thread.spawn(.{ .stack_size = t.stack_size }, worker, .{t}) catch
return error.ConcurrencyUnavailable;
thread.detach();
}
// TODO: 若将此逻辑改为无锁实现,队列的前插操作必须以 release 语义发布此 `fetchAdd`,
// 以免任务结束时尚未观察到这次操作,
// 从而尝试将计数减至零以下。
_ = g.status().fetchAdd(.{
.num_running = 1,
.have_awaiter = false,
.canceled = false,
}, .monotonic);
t.run_queue.prepend(&task.runnable.node);
condSignal(&t.cond);
}
fn groupAwait(userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque) Io.Cancelable!void {
_ = initial_token; // 必须在组完成*之后*加载 `token`。
if (builtin.single_threaded) unreachable; // 无等待对象
const t: *Threaded = @ptrCast(@alignCast(userdata));
const g: Group = .{ .ptr = type_erased };
var num_completed: std.atomic.Value(u32) = .init(0);
g.awaiter().* = &num_completed;
const pre_await_status = g.status().fetchOr(.{
.num_running = 0,
.have_awaiter = true,
.canceled = false,
}, .acq_rel); // 完成时获取结果;释放 `g.awaiter()`
assert(!pre_await_status.have_awaiter);
assert(!pre_await_status.canceled);
if (pre_await_status.num_running == 0) {
// 已经完成。由于组已结束,在返回之前禁止向其中创建更多任务,因此可以非原子地访问 `g.status()`。
//
g.status().raw.have_awaiter = false;
return;
}
while (Thread.futexWait(&num_completed.raw, 0, null)) {
switch (num_completed.load(.acquire)) { // 获取任务结果
0 => continue,
1 => break,
else => unreachable, // group 在 `await` 返回前被复用
}
} else |err| switch (err) {
error.Canceled => {
const pre_cancel_status = g.status().fetchOr(.{
.num_running = 0,
.have_awaiter = false,
.canceled = true,
}, .acq_rel); // 完成时获取结果;释放 `g.awaiter()`
assert(pre_cancel_status.have_awaiter);
assert(!pre_cancel_status.canceled);
// 即使 `pre_cancel_status.num_running == 0`,仍需等待信号,
// 因为此时组内最后一个成员已在尝试修改它。
// 不过,如果已知所有操作完成,*可以*不再向阻塞线程发信号。
const skip_signals = pre_cancel_status.num_running == 0;
g.waitForCancelWithSignaling(t, &num_completed, skip_signals);
// 组已完成,因此在本函数返回前不允许向其中派生更多任务,
// 所以可以非原子地访问 `g.status()`。
g.status().raw.canceled = false;
g.status().raw.have_awaiter = false;
return error.Canceled;
},
}
// 组已完成,因此在本函数返回前不允许向其中派生更多任务,
// 所以可以非原子地访问 `g.status()`。
g.status().raw.have_awaiter = false;
}
fn groupCancel(userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque) void {
_ = initial_token;
if (builtin.single_threaded) unreachable; // 没有可取消的对象
const t: *Threaded = @ptrCast(@alignCast(userdata));
const g: Group = .{ .ptr = type_erased };
var num_completed: std.atomic.Value(u32) = .init(0);
g.awaiter().* = &num_completed;
const pre_cancel_status = g.status().fetchOr(.{
.num_running = 0,
.have_awaiter = true,
.canceled = true,
}, .acq_rel); // 完成时获取结果;释放 `g.awaiter()`
assert(!pre_cancel_status.have_awaiter);
assert(!pre_cancel_status.canceled);
if (pre_cancel_status.num_running == 0) {
// 已经完成。由于组已结束,在返回之前禁止向其中创建更多任务,因此可以非原子地访问 `g.status()`。
//
g.status().raw.have_awaiter = false;
g.status().raw.canceled = false;
return;
}
g.waitForCancelWithSignaling(t, &num_completed, false);
g.status().raw = .{ .num_running = 0, .have_awaiter = false, .canceled = false };
}
fn recancel(userdata: ?*anyopaque) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
recancelInner();
}
fn recancelInner() void {
const thread = Thread.current.?; // 调用了 `recancel`,但此前未取消
switch (thread.status.fetchXor(.{
.cancelation = @fromBackingInt(@intCast(0b001)),
.awaitable = .null,
}, .monotonic).cancelation) {
.canceled => {},
.none => unreachable, // 调用了 `recancel`,但此前未取消
.canceling => unreachable, // 调用了 `recancel`,但已有待处理的取消
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
}
}
fn swapCancelProtection(userdata: ?*anyopaque, new: Io.CancelProtection) Io.CancelProtection {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const thread = Thread.current orelse return .unblocked;
const old = thread.cancel_protection;
thread.cancel_protection = new;
return old;
}
fn checkCancel(userdata: ?*anyopaque) Io.Cancelable!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return Thread.checkCancel();
}
fn await(
userdata: ?*anyopaque,
any_future: *Io.AnyFuture,
result: []u8,
result_alignment: Alignment,
) void {
_ = result_alignment;
if (builtin.single_threaded) unreachable; // 无等待对象
const t: *Threaded = @ptrCast(@alignCast(userdata));
const future: *Future = @ptrCast(@alignCast(any_future));
var num_completed: std.atomic.Value(u32) = .init(0);
future.awaiter = &num_completed;
const pre_await_status = future.status.fetchOr(.{
.tag = .pending_awaited,
.thread = .null,
}, .acq_rel); // 若已完成,则以 acquire 语义获取结果;以 release 语义发布 `future.awaiter`。
switch (pre_await_status.tag) {
.pending => while (Thread.futexWait(&num_completed.raw, 0, null)) {
switch (num_completed.load(.acquire)) { // 获取任务结果
0 => continue,
1 => break,
else => unreachable, // group 在 `await` 返回前被复用
}
} else |err| switch (err) {
error.Canceled => {
const pre_cancel_status = future.status.fetchOr(.{
.tag = .pending_canceled,
.thread = .null,
}, .acq_rel); // 若已完成,则以 acquire 语义获取结果;以 release 语义发布 `future.awaiter`。
const done_status = switch (pre_cancel_status.tag) {
.pending => unreachable, // 状态无效:已经等待过
.pending_awaited => done_status: {
const working_thread = pre_cancel_status.thread.unpack();
future.waitForCancelWithSignaling(t, &num_completed, @alignCast(working_thread));
break :done_status future.status.load(.monotonic);
},
.pending_canceled => unreachable, // `await` 与 `cancel` 发生竞态
.done => done_status: {
// 任务刚刚完成,但仍需等待信号,因为任务线程
// 已经确定自己需要更新 `future.awaiter`。
future.waitForCancelWithSignaling(t, &num_completed, null);
// 此外,已将 `future.status.tag` 覆盖为 `.pending_canceled`,
// 但这对下方逻辑实际上没有影响。
break :done_status pre_cancel_status;
},
};
// 如果 future 未确认取消请求,我们需要将其标记为由当前任务
// 负责处理。由于 `done_status.tag == .done`,取消请求是否已确认
// 编码在 `done_status.thread` 中。
assert(done_status.tag == .done);
switch (done_status.thread) {
.null => recancelInner(), // 取消未被确认,因此归我们处理。
.all_ones => {}, // 取消已确认,因此此任务负责传播取消
_ => unreachable,
}
},
},
.pending_awaited => unreachable, // `await` 与另一个 `await` 发生竞争
.pending_canceled => unreachable, // `await` 与 `cancel` 发生竞态
.done => {},
}
@memcpy(result, future.resultPointer());
future.destroy(t.allocator);
}
fn cancel(
userdata: ?*anyopaque,
any_future: *Io.AnyFuture,
result: []u8,
result_alignment: Alignment,
) void {
_ = result_alignment;
if (builtin.single_threaded) unreachable; // 没有可取消的对象
const t: *Threaded = @ptrCast(@alignCast(userdata));
const future: *Future = @ptrCast(@alignCast(any_future));
var num_completed: std.atomic.Value(u32) = .init(0);
future.awaiter = &num_completed;
const pre_cancel_status = future.status.fetchOr(.{
.tag = .pending_canceled,
.thread = .null,
}, .acq_rel); // 若已完成,则以 acquire 语义获取结果;以 release 语义发布 `future.awaiter`。
switch (pre_cancel_status.tag) {
.pending => {
const working_thread = pre_cancel_status.thread.unpack();
future.waitForCancelWithSignaling(t, &num_completed, @alignCast(working_thread));
},
.pending_awaited => unreachable, // `await` 与另一个 `await` 发生竞争
.pending_canceled => unreachable, // `await` 与 `cancel` 发生竞态
.done => {},
}
@memcpy(result, future.resultPointer());
future.destroy(t.allocator);
}
fn futexWait(userdata: ?*anyopaque, ptr: *const u32, expected: u32, timeout: Io.Timeout) Io.Cancelable!void {
if (builtin.single_threaded) {
assert(timeout != .none); // 死锁。
return;
}
const t: *Threaded = @ptrCast(@alignCast(userdata));
const t_io = io(t);
const timeout_ns: ?u64 = ns: {
const d = timeout.toDurationFromNow(t_io) orelse break :ns null;
break :ns std.math.lossyCast(u64, d.raw.toNanoseconds());
};
return Thread.futexWait(ptr, expected, timeout_ns);
}
fn futexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void {
if (builtin.single_threaded) unreachable; // 死锁。
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
Thread.futexWaitUncancelable(ptr, expected, null);
}
fn futexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void {
if (builtin.single_threaded) return; // 没有待唤醒者。
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
Thread.futexWake(ptr, max_waiters);
}
fn operate(userdata: ?*anyopaque, operation: Io.Operation) Io.Cancelable!Io.Operation.Result {
const t: *Threaded = @ptrCast(@alignCast(userdata));
switch (operation) {
.file_read_streaming => |o| return .{
.file_read_streaming = fileReadStreaming(t, o.file, o.data) catch |err| switch (err) {
error.Canceled => |e| return e,
else => |e| e,
},
},
.file_write_streaming => |o| return .{
.file_write_streaming = fileWriteStreaming(t, o.file, o.header, o.data, o.splat) catch |err| switch (err) {
error.Canceled => |e| return e,
else => |e| e,
},
},
.device_io_control => |*o| return .{ .device_io_control = try deviceIoControl(o) },
.net_receive => |*o| return .{ .net_receive = o: {
if (!have_networking) break :o .{ error.NetworkDown, 0 };
if (is_windows) break :o netReceiveWindows(t, o.socket_handle, o.message_buffer, o.data_buffer, o.flags);
netReceivePosix(o.socket_handle, &o.message_buffer[0], o.data_buffer, o.flags, false) catch |err| switch (err) {
error.Canceled => |e| return e,
error.WouldBlock => unreachable,
else => |e| break :o .{ e, 0 },
};
break :o .{ null, 1 };
} },
.net_send => |*o| return .{
.net_send = o: {
if (!have_networking) break :o .{ error.NetworkDown, 0 };
if (is_windows) break :o netSendWindows(t, o.socket_handle, o.messages, o.flags);
const send_err, const sent = netSendPosix(t, o.socket_handle, o.messages, o.flags, false);
if (send_err) |err| switch (err) {
error.Canceled => |e| if (sent == 0) {
return e;
} else {
// 保留 `error.Canceled` 以待稍后处理,但不要再尝试发送消息。
recancelInner();
break :o .{ null, sent };
},
error.WouldBlock => unreachable,
else => |e| break :o .{ e, sent },
};
break :o .{ null, sent };
},
},
.net_read => |o| return .{
.net_read = netRead(o.socket_handle, o.data, o.control) catch |err| switch (err) {
error.Canceled => |e| return e,
else => |e| e,
},
},
.net_write => |o| return .{
.net_write = (if (is_windows)
netWriteWindows(o.socket_handle, o.header, o.data, o.splat, o.control)
else
netWritePosix(o.socket_handle, o.header, o.data, o.splat, o.control)) catch |err| switch (err) {
error.Canceled => |e| return e,
else => |e| e,
},
},
}
}
fn batchAwaitAsync(userdata: ?*anyopaque, b: *Io.Batch) Io.Cancelable!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (is_windows) {
batchDrainSubmittedWindows(t, b, false) catch |err| switch (err) {
error.ConcurrencyUnavailable => unreachable, // 传入 concurrency=false
else => |e| return e,
};
const alertable_syscall = try AlertableSyscall.start();
while (b.pending.head != .none and b.completed.head == .none) waitForApcOrAlert();
alertable_syscall.finish();
return;
}
if (have_poll) {
var poll_buffer: [poll_buffer_len]posix.pollfd = undefined;
var poll_len: u32 = 0;
{
var index = b.submitted.head;
while (index != .none and poll_len < poll_buffer_len) {
const submission = &b.storage[index.toIndex()].submission;
switch (submission.operation) {
.file_read_streaming => |o| {
poll_buffer[poll_len] = .{
.fd = o.file.handle,
.events = posix.POLL.IN | posix.POLL.ERR,
};
poll_len += 1;
},
.file_write_streaming => |o| {
poll_buffer[poll_len] = .{
.fd = o.file.handle,
.events = posix.POLL.OUT | posix.POLL.ERR,
};
poll_len += 1;
},
.device_io_control => |o| {
poll_buffer[poll_len] = .{
.fd = o.file.handle,
.events = posix.POLL.OUT | posix.POLL.IN | posix.POLL.ERR,
};
poll_len += 1;
},
.net_receive => |*o| {
poll_buffer[poll_len] = .{
.fd = o.socket_handle,
.events = posix.POLL.IN | posix.POLL.ERR,
};
poll_len += 1;
},
.net_send => |*o| {
poll_buffer[poll_len] = .{
.fd = o.socket_handle,
.events = posix.POLL.OUT | posix.POLL.ERR,
};
poll_len += 1;
},
.net_read => |o| {
poll_buffer[poll_len] = .{
.fd = o.socket_handle,
.events = posix.POLL.IN | posix.POLL.ERR,
};
poll_len += 1;
},
.net_write => |o| {
poll_buffer[poll_len] = .{
.fd = o.socket_handle,
.events = posix.POLL.OUT | posix.POLL.ERR,
};
poll_len += 1;
},
}
index = submission.node.next;
}
}
switch (poll_len) {
0 => return,
1 => {},
else => while (true) {
const timeout_ms: i32 = t: {
if (b.completed.head != .none) {
// 环中已有完成操作时调用 batchWait 是合法的。
// 此时需避免在 poll 系统调用中阻塞,
// 但仍可利用此机会
// 查找其他已就绪操作。
break :t 0;
}
break :t std.math.maxInt(i32);
};
const syscall = try Syscall.start();
const rc = posix.system.poll(&poll_buffer, poll_len, timeout_ms);
syscall.finish();
switch (posix.errno(rc)) {
.SUCCESS => {
if (rc == 0) {
if (b.completed.head != .none) {
// 由于队列中已有可用的完成项,
// 这既不是超时,也不是需要
// 重试的情况。
return;
}
continue;
}
var prev_index: Io.Operation.OptionalIndex = .none;
var index = b.submitted.head;
for (poll_buffer[0..poll_len]) |poll_entry| {
const storage = &b.storage[index.toIndex()];
const submission = &storage.submission;
const next_index = submission.node.next;
if (poll_entry.revents != 0) {
const result = try operate(t, submission.operation);
switch (prev_index) {
.none => b.submitted.head = next_index,
else => b.storage[prev_index.toIndex()].submission.node.next = next_index,
}
if (next_index == .none) b.submitted.tail = prev_index;
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
b.completed.tail = index;
} else prev_index = index;
index = next_index;
}
assert(index == .none);
return;
},
.INTR => continue,
else => break,
}
},
}
}
var tail_index = b.completed.tail;
defer b.completed.tail = tail_index;
var index = b.submitted.head;
errdefer b.submitted.head = index;
while (index != .none) {
const storage = &b.storage[index.toIndex()];
const submission = &storage.submission;
const next_index = submission.node.next;
const result = try operate(t, submission.operation);
switch (tail_index) {
.none => b.completed.head = index,
else => b.storage[tail_index.toIndex()].completion.node.next = index,
}
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
tail_index = index;
index = next_index;
}
b.submitted = .{ .head = .none, .tail = .none };
}
fn batchAwaitConcurrent(userdata: ?*anyopaque, b: *Io.Batch, timeout: Io.Timeout) Io.Batch.AwaitConcurrentError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (is_windows) {
const deadline: ?Io.Clock.Timestamp = timeout.toTimestamp(io(t));
try batchDrainSubmittedWindows(t, b, true);
while (b.pending.head != .none and b.completed.head == .none) {
var delay_interval: windows.LARGE_INTEGER = interval: {
const d = deadline orelse break :interval std.math.minInt(windows.LARGE_INTEGER);
break :interval timeoutToWindowsInterval(.{ .deadline = d }).?;
};
const alertable_syscall = try AlertableSyscall.start();
const delay_rc = windows.ntdll.NtDelayExecution(.TRUE, &delay_interval);
alertable_syscall.finish();
switch (delay_rc) {
.SUCCESS, .TIMEOUT => {
// 线程因超时唤醒。虽然允许伪超时,但未传入截止时间时不得返回 `error.Timeout`。
//
//
if (timeout != .none and b.completed.head == .none) return error.Timeout;
},
else => {},
}
}
return;
}
if (native_os == .wasi) {
// TODO 调用 poll_oneoff
return error.ConcurrencyUnavailable;
}
if (!have_poll) return error.ConcurrencyUnavailable;
var poll_buffer: [poll_buffer_len]posix.pollfd = undefined;
var poll_storage: struct {
gpa: Allocator,
batch: *Io.Batch,
slice: []posix.pollfd,
len: u32,
fn add(storage: *@This(), fd: File.Handle, events: @FieldType(posix.pollfd, "events")) Io.ConcurrentError!void {
const len = storage.len;
if (len == poll_buffer_len) {
const slice: []posix.pollfd = if (storage.batch.userdata) |batch_userdata|
@as([*]posix.pollfd, @ptrCast(@alignCast(batch_userdata)))[0..storage.batch.storage.len]
else allocation: {
const allocation = storage.gpa.alloc(posix.pollfd, storage.batch.storage.len) catch
return error.ConcurrencyUnavailable;
storage.batch.userdata = allocation.ptr;
break :allocation allocation;
};
@memcpy(slice[0..poll_buffer_len], storage.slice);
storage.slice = slice;
}
storage.slice[len] = .{
.fd = fd,
.events = events,
};
storage.len = len + 1;
}
} = .{ .gpa = t.allocator, .batch = b, .slice = &poll_buffer, .len = 0 };
{
var index = b.submitted.head;
while (index != .none) {
const storage = &b.storage[index.toIndex()];
const submission = storage.submission;
switch (submission.operation) {
.file_read_streaming => |o| try poll_storage.add(o.file.handle, posix.POLL.IN | posix.POLL.ERR),
.file_write_streaming => |o| try poll_storage.add(o.file.handle, posix.POLL.OUT | posix.POLL.ERR),
.device_io_control => |o| try poll_storage.add(o.file.handle, posix.POLL.IN | posix.POLL.OUT | posix.POLL.ERR),
.net_receive => |*o| nb: {
var data_i: usize = 0;
const result: Io.Operation.Result = .{ .net_receive = for (o.message_buffer, 0..) |*msg, msg_i| {
const remaining_data_buffer = o.data_buffer[data_i..];
netReceivePosix(o.socket_handle, msg, remaining_data_buffer, o.flags, true) catch |err| switch (err) {
error.Canceled => |e| return e,
error.WouldBlock => {
if (msg_i != 0) break .{ null, msg_i };
try poll_storage.add(o.socket_handle, posix.POLL.IN | posix.POLL.ERR);
break :nb;
},
else => |e| break .{ e, 0 },
};
data_i += msg.data.len;
} else .{ null, o.message_buffer.len } };
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
b.completed.tail = index;
},
.net_send => |*o| nb: {
const result: Io.Operation.Result = .{
.net_send = o: {
const send_err, const sent = netSendPosix(t, o.socket_handle, o.messages, o.flags, true);
if (send_err) |err| switch (err) {
error.Canceled => |e| if (sent == 0) {
return e;
} else {
// 保留 `error.Canceled` 以待稍后处理,但不要再尝试发送消息。
recancelInner();
break :o .{ null, sent };
},
error.WouldBlock => {
if (sent != 0) break :o .{ null, sent };
try poll_storage.add(o.socket_handle, posix.POLL.OUT | posix.POLL.ERR);
break :nb;
},
else => |e| break :o .{ e, sent },
};
break :o .{ null, sent };
},
};
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
b.completed.tail = index;
},
.net_read => |o| try poll_storage.add(o.socket_handle, posix.POLL.IN | posix.POLL.ERR),
.net_write => |o| try poll_storage.add(o.socket_handle, posix.POLL.OUT | posix.POLL.ERR),
}
index = submission.node.next;
}
}
switch (poll_storage.len) {
0 => return,
1 => if (timeout == .none and b.completed.head == .none) {
const index = b.submitted.head;
const storage = &b.storage[index.toIndex()];
const result = try operate(t, storage.submission.operation);
b.submitted = .{ .head = .none, .tail = .none };
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
b.completed.tail = index;
return;
},
else => {},
}
const t_io = io(t);
const deadline = timeout.toTimestamp(t_io);
while (true) {
const timeout_ms: i32 = t: {
if (b.completed.head != .none) {
// 环中已有完成操作时调用 batchWait 是合法的。
// 此时需避免在 poll 系统调用中阻塞,
// 但仍可利用此机会
// 查找其他已就绪操作。
break :t 0;
}
const d = deadline orelse break :t -1;
const duration = d.durationFromNow(t_io);
break :t @min(@max(0, duration.raw.toMilliseconds()), std.math.maxInt(i32));
};
const syscall = try Syscall.start();
const rc = posix.system.poll(poll_storage.slice.ptr, poll_storage.len, timeout_ms);
syscall.finish();
switch (posix.errno(rc)) {
.SUCCESS => {
if (rc == 0) {
if (b.completed.head != .none) {
// 由于队列中已有可用的完成项,
// 这既不是超时,也不是需要
// 重试的情况。
return;
}
// 虽然允许虚假超时,但未传入截止时间时
// 绝不能返回 `error.Timeout`。
if (deadline == null) continue;
return error.Timeout;
}
var prev_index: Io.Operation.OptionalIndex = .none;
var index = b.submitted.head;
for (poll_storage.slice[0..poll_storage.len]) |poll_entry| {
const submission = &b.storage[index.toIndex()].submission;
const next_index = submission.node.next;
if (poll_entry.revents != 0) {
const result = try operate(t, submission.operation);
switch (prev_index) {
.none => b.submitted.head = next_index,
else => b.storage[prev_index.toIndex()].submission.node.next = next_index,
}
if (next_index == .none) b.submitted.tail = prev_index;
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
b.completed.tail = index;
b.storage[index.toIndex()] = .{ .completion = .{
.node = .{ .next = .none },
.result = result,
} };
} else prev_index = index;
index = next_index;
}
assert(index == .none);
return;
},
.INTR => continue,
else => return error.ConcurrencyUnavailable,
}
}
}
const WindowsBatchOperationUserdata = extern struct {
file: windows.HANDLE,
iosb: windows.IO_STATUS_BLOCK,
const Erased = Io.Operation.Storage.Pending.Userdata;
comptime {
assert(@sizeOf(WindowsBatchOperationUserdata) <= @sizeOf(Erased));
}
fn toErased(userdata: *WindowsBatchOperationUserdata) *Erased {
return @ptrCast(userdata);
}
fn fromErased(erased: *Erased) *WindowsBatchOperationUserdata {
return @ptrCast(erased);
}
};
fn batchCancel(userdata: ?*anyopaque, b: *Io.Batch) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (is_windows) {
if (b.pending.head == .none) return;
waitForApcOrAlert();
var index = b.pending.head;
while (index != .none) {
const pending = &b.storage[index.toIndex()].pending;
const operation_userdata: *WindowsBatchOperationUserdata = .fromErased(&pending.userdata);
var cancel_iosb: windows.IO_STATUS_BLOCK = undefined;
_ = windows.ntdll.NtCancelIoFileEx(operation_userdata.file, &operation_userdata.iosb, &cancel_iosb);
index = pending.node.next;
}
while (b.pending.head != .none) waitForApcOrAlert();
} else if (b.userdata) |batch_userdata| {
const poll_storage: [*]posix.pollfd = @ptrCast(@alignCast(batch_userdata));
t.allocator.free(poll_storage[0..b.storage.len]);
b.userdata = null;
}
}
fn batchCompleteBlockingWindows(
b: *Io.Batch,
operation_userdata: *WindowsBatchOperationUserdata,
result: Io.Operation.Result,
) void {
const erased_userdata = operation_userdata.toErased();
const pending: *Io.Operation.Storage.Pending = @fieldParentPtr("userdata", erased_userdata);
switch (pending.node.prev) {
.none => b.pending.head = pending.node.next,
else => |prev_index| b.storage[prev_index.toIndex()].pending.node.next = pending.node.next,
}
switch (pending.node.next) {
.none => b.pending.tail = pending.node.prev,
else => |next_index| b.storage[next_index.toIndex()].pending.node.prev = pending.node.prev,
}
const storage: *Io.Operation.Storage = @fieldParentPtr("pending", pending);
const index: Io.Operation.OptionalIndex = .fromIndex(storage - b.storage.ptr);
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
b.completed.tail = index;
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
}
fn batchApc(
apc_context: ?*anyopaque,
iosb: *windows.IO_STATUS_BLOCK,
_: windows.ULONG,
) align(apc_align) callconv(.winapi) void {
const b: *Io.Batch = @ptrCast(@alignCast(apc_context));
const operation_userdata: *WindowsBatchOperationUserdata = @fieldParentPtr("iosb", iosb);
const erased_userdata = operation_userdata.toErased();
const pending: *Io.Operation.Storage.Pending = @fieldParentPtr("userdata", erased_userdata);
switch (pending.node.prev) {
.none => b.pending.head = pending.node.next,
else => |prev_index| b.storage[prev_index.toIndex()].pending.node.next = pending.node.next,
}
switch (pending.node.next) {
.none => b.pending.tail = pending.node.prev,
else => |next_index| b.storage[next_index.toIndex()].pending.node.prev = pending.node.prev,
}
const storage: *Io.Operation.Storage = @fieldParentPtr("pending", pending);
const index: Io.Operation.OptionalIndex = .fromIndex(storage - b.storage.ptr);
switch (iosb.u.Status) {
.CANCELLED => {
const tail_index = b.unused.tail;
switch (tail_index) {
.none => b.unused.head = index,
else => b.storage[tail_index.toIndex()].unused.next = index,
}
storage.* = .{ .unused = .{ .prev = tail_index, .next = .none } };
b.unused.tail = index;
},
else => {
switch (b.completed.tail) {
.none => b.completed.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].completion.node.next = index,
}
b.completed.tail = index;
const result: Io.Operation.Result = switch (pending.tag) {
.file_read_streaming => .{ .file_read_streaming = ntReadFileResult(iosb) },
.file_write_streaming => .{ .file_write_streaming = ntWriteFileResult(iosb) },
.device_io_control => .{ .device_io_control = iosb.* },
.net_receive => unreachable,
.net_send => unreachable,
.net_read => unreachable,
.net_write => unreachable,
};
storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
},
}
}
/// 若 `concurrency` 为 false,则 `error.ConcurrencyUnavailable` 不可达。
fn batchDrainSubmittedWindows(t: *Threaded, b: *Io.Batch, concurrency: bool) (Io.ConcurrentError || Io.Cancelable)!void {
var index = b.submitted.head;
errdefer b.submitted.head = index;
while (index != .none) {
const storage = &b.storage[index.toIndex()];
const submission = storage.submission;
storage.* = .{ .pending = .{
.node = .{ .prev = b.pending.tail, .next = .none },
.tag = submission.operation,
.userdata = undefined,
} };
switch (b.pending.tail) {
.none => b.pending.head = index,
else => |tail_index| b.storage[tail_index.toIndex()].pending.node.next = index,
}
b.pending.tail = index;
const operation_userdata: *WindowsBatchOperationUserdata = .fromErased(&storage.pending.userdata);
errdefer {
operation_userdata.iosb = .{ .u = .{ .Status = .CANCELLED }, .Information = undefined };
batchApc(b, &operation_userdata.iosb, 0);
}
switch (submission.operation) {
.file_read_streaming => |o| o: {
var data_index: usize = 0;
while (o.data.len - data_index != 0 and o.data[data_index].len == 0) data_index += 1;
if (o.data.len - data_index == 0) {
operation_userdata.iosb = .{ .u = .{ .Status = .SUCCESS }, .Information = 0 };
batchApc(b, &operation_userdata.iosb, 0);
break :o;
}
const buffer = o.data[data_index];
const short_buffer_len = std.math.lossyCast(u32, buffer.len);
if (o.file.flags.nonblocking) {
operation_userdata.file = o.file.handle;
switch (windows.ntdll.NtReadFile(
o.file.handle,
null, // 事件
&batchApc,
b,
&operation_userdata.iosb,
buffer.ptr,
short_buffer_len,
null, // 字节偏移量
null, // 键
)) {
.PENDING, .SUCCESS => {},
.CANCELLED => unreachable,
else => |status| {
operation_userdata.iosb.u.Status = status;
batchApc(b, &operation_userdata.iosb, 0);
},
}
} else {
if (concurrency) return error.ConcurrencyUnavailable;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtReadFile(
o.file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&operation_userdata.iosb,
buffer.ptr,
short_buffer_len,
null, // 字节偏移量
null, // 键
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| {
syscall.finish();
operation_userdata.iosb.u.Status = status;
batchApc(b, &operation_userdata.iosb, 0);
break;
},
};
}
},
.file_write_streaming => |o| o: {
const buffer = windowsWriteBuffer(o.header, o.data, o.splat);
if (buffer.len == 0) {
operation_userdata.iosb = .{ .u = .{ .Status = .SUCCESS }, .Information = 0 };
batchApc(b, &operation_userdata.iosb, 0);
break :o;
}
if (o.file.flags.nonblocking) {
operation_userdata.file = o.file.handle;
switch (windows.ntdll.NtWriteFile(
o.file.handle,
null, // 事件
&batchApc,
b,
&operation_userdata.iosb,
buffer.ptr,
@intCast(buffer.len),
null, // 字节偏移量
null, // 键
)) {
.PENDING, .SUCCESS => {},
.CANCELLED => unreachable,
else => |status| {
operation_userdata.iosb.u.Status = status;
batchApc(b, &operation_userdata.iosb, 0);
},
}
} else {
if (concurrency) return error.ConcurrencyUnavailable;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtWriteFile(
o.file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&operation_userdata.iosb,
buffer.ptr,
@intCast(buffer.len),
null, // 字节偏移量
null, // 键
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| {
syscall.finish();
operation_userdata.iosb.u.Status = status;
batchApc(b, &operation_userdata.iosb, 0);
break;
},
};
}
},
.device_io_control => |o| {
const NtControlFile = switch (o.code.DeviceType) {
.FILE_SYSTEM, .NAMED_PIPE => &windows.ntdll.NtFsControlFile,
else => &windows.ntdll.NtDeviceIoControlFile,
};
if (o.file.flags.nonblocking) {
operation_userdata.file = o.file.handle;
switch (NtControlFile(
o.file.handle,
null, // 事件
&batchApc,
b,
&operation_userdata.iosb,
o.code,
if (o.in.len > 0) o.in.ptr else null,
@intCast(o.in.len),
if (o.out.len > 0) o.out.ptr else null,
@intCast(o.out.len),
)) {
.PENDING, .SUCCESS => {},
.CANCELLED => unreachable,
else => |status| {
operation_userdata.iosb.u.Status = status;
batchApc(b, &operation_userdata.iosb, 0);
},
}
} else {
if (concurrency) return error.ConcurrencyUnavailable;
const syscall: Syscall = try .start();
while (true) switch (NtControlFile(
o.file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&operation_userdata.iosb,
o.code,
if (o.in.len > 0) o.in.ptr else null,
@intCast(o.in.len),
if (o.out.len > 0) o.out.ptr else null,
@intCast(o.out.len),
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| {
syscall.finish();
operation_userdata.iosb.u.Status = status;
batchApc(b, &operation_userdata.iosb, 0);
break;
},
};
}
},
.net_receive => |*o| {
// TODO: 与重叠 I/O 或等效机制集成,以避免此错误
if (concurrency) return error.ConcurrencyUnavailable;
batchCompleteBlockingWindows(b, operation_userdata, .{
.net_receive = netReceiveWindows(t, o.socket_handle, o.message_buffer, o.data_buffer, o.flags),
});
},
.net_send => |*o| {
// TODO: 与重叠 I/O 或等效机制集成,以避免此错误
if (concurrency) return error.ConcurrencyUnavailable;
batchCompleteBlockingWindows(b, operation_userdata, .{
.net_send = netSendWindows(t, o.socket_handle, o.messages, o.flags),
});
},
.net_read => |*o| {
// TODO: 与重叠 I/O 或等效机制集成,以避免此错误
if (concurrency) return error.ConcurrencyUnavailable;
batchCompleteBlockingWindows(b, operation_userdata, .{
.net_read = netRead(o.socket_handle, o.data, o.control) catch |err| switch (err) {
error.Canceled => |e| return e,
else => |e| e,
},
});
},
.net_write => |*o| {
// TODO: 与重叠 I/O 或等效机制集成,以避免此错误
if (concurrency) return error.ConcurrencyUnavailable;
batchCompleteBlockingWindows(b, operation_userdata, .{
.net_write = netWriteWindows(o.socket_handle, o.header, o.data, o.splat, o.control) catch |err| switch (err) {
error.Canceled => |e| return e,
else => |e| e,
},
});
},
}
index = submission.node.next;
}
b.submitted = .{ .head = .none, .tail = .none };
}
/// 由于 Windows 仅支持写入一个连续缓冲区,因此返回
/// 第一个缓冲区,同时将长度限制为
/// 32 位无符号整数可表示的范围。
fn windowsWriteBuffer(header: []const u8, data: []const []const u8, splat: usize) []const u8 {
const buffer = b: {
if (header.len != 0) break :b header;
for (data[0 .. data.len - 1]) |buffer| {
if (buffer.len != 0) break :b buffer;
}
if (splat == 0) return &.{};
break :b data[data.len - 1];
};
return buffer[0..std.math.lossyCast(u32, buffer.len)];
}
fn submitComplete(ring: []u32, complete_tail: *Io.Batch.RingIndex, op: u32) void {
const ct = complete_tail.*;
const len: u31 = @intCast(ring.len);
ring[ct.index(len)] = op;
complete_tail.* = ct.next(len);
}
const dirCreateDir = switch (native_os) {
.windows => dirCreateDirWindows,
.wasi => dirCreateDirWasi,
else => dirCreateDirPosix,
};
fn dirCreateDirPosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.mkdirat(dir.handle, sub_path_posix, permissions.toMode()))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.PERM => return syscall.fail(error.PermissionDenied),
.DQUOT => return syscall.fail(error.DiskQuota),
.EXIST => return syscall.fail(error.PathAlreadyExists),
.LOOP => return syscall.fail(error.SymLinkLoop),
.MLINK => return syscall.fail(error.LinkQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NOENT => return syscall.fail(error.FileNotFound),
.NOMEM => return syscall.fail(error.SystemResources),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.NOTDIR => return syscall.fail(error.NotDir),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
// dragonfly:dir_fd 已从文件系统中解除链接时
.NOTCONN => return syscall.fail(error.FileNotFound),
.ILSEQ => return syscall.fail(error.BadPathName),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
.FAULT => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn dirCreateDirWasi(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void {
if (builtin.link_libc) return dirCreateDirPosix(userdata, dir, sub_path, permissions);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.path_create_directory(dir.handle, sub_path.ptr, sub_path.len)) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.PERM => return error.PermissionDenied,
.DQUOT => return error.DiskQuota,
.EXIST => return error.PathAlreadyExists,
.FAULT => |err| return errnoBug(err),
.LOOP => return error.SymLinkLoop,
.MLINK => return error.LinkQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.NOTDIR => return error.NotDir,
.ROFS => return error.ReadOnlyFileSystem,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirCreateDirWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
_ = permissions; // TODO 使用此值
const sub_path_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
const attr: windows.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w.span())) null else dir.handle,
.Attributes = .{ .INHERIT = false },
.ObjectName = @constCast(&windows.UNICODE_STRING.init(sub_path_w.span())),
.SecurityDescriptor = null,
.SecurityQualityOfService = null,
};
var sub_dir_handle: windows.HANDLE = undefined;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var attempt: u5 = 0;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtCreateFile(
&sub_dir_handle,
.{
.GENERIC = .{ .READ = true },
.STANDARD = .{ .SYNCHRONIZE = true },
},
&attr,
&io_status_block,
null,
.{ .NORMAL = true },
.VALID_FLAGS,
.CREATE,
.{
.DIRECTORY_FILE = true,
.NON_DIRECTORY_FILE = false,
.IO = .SYNCHRONOUS_NONALERT,
.OPEN_REPARSE_POINT = false,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
windows.CloseHandle(sub_dir_handle);
return;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.SHARING_VIOLATION => {
// 尝试打开正在运行的可执行文件时会发生此错误。
// 但存在内核缺陷:可执行文件关闭后,在长短不确定的一段时间内仍可能错误返回此错误。
// 这里通过重试规避该内核缺陷。
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.Unexpected;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.DELETE_PENDING => {
// 此错误表示文件系统的该位置原先存在文件,但已被删除。然而,操作系统尚未完成删除操作,因此本次 CreateFile 调用失败。
// 除了等待操作系统完成删除后重试创建之外,没有合理的处理方式。
//
//
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.Unexpected;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.BAD_NETWORK_PATH => return syscall.fail(error.NetworkNotFound), // 未找到 \\server
.BAD_NETWORK_NAME => return syscall.fail(error.NetworkNotFound), // 找到 \\server,但未找到 \\server\share
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.OBJECT_NAME_COLLISION => return syscall.fail(error.PathAlreadyExists),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.OBJECT_PATH_SYNTAX_BAD => |status| return syscall.ntstatusBug(status),
.INVALID_HANDLE => |status| return syscall.ntstatusBug(status),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
fn dirCreateDirPath(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
permissions: Dir.Permissions,
) Dir.CreateDirPathError!Dir.CreatePathStatus {
const t: *Threaded = @ptrCast(@alignCast(userdata));
var it = Dir.path.componentIterator(sub_path);
var status: Dir.CreatePathStatus = .existed;
var component = it.last() orelse return error.BadPathName;
while (true) {
if (dirCreateDir(t, dir, component.path, permissions)) |_| {
status = .created;
} else |err| switch (err) {
error.PathAlreadyExists => {
// 若不是目录,必须返回错误;否则悬空符号链接可能导致无限循环。
//
//
const kind = try filePathKind(t, dir, component.path);
if (kind != .directory) return error.NotDir;
},
error.FileNotFound => |e| {
component = it.previous() orelse return e;
continue;
},
else => |e| return e,
}
component = it.next() orelse return status;
}
}
const dirCreateDirPathOpen = switch (native_os) {
.windows => dirCreateDirPathOpenWindows,
.wasi => dirCreateDirPathOpenWasi,
else => dirCreateDirPathOpenPosix,
};
fn dirCreateDirPathOpenPosix(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
permissions: Dir.Permissions,
options: Dir.OpenOptions,
) Dir.CreateDirPathOpenError!Dir {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const t_io = io(t);
return dirOpenDirPosix(t, dir, sub_path, options) catch |err| switch (err) {
error.FileNotFound => {
_ = try dir.createDirPathStatus(t_io, sub_path, permissions);
return dirOpenDirPosix(t, dir, sub_path, options);
},
else => |e| return e,
};
}
fn dirCreateDirPathOpenWindows(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
permissions: Dir.Permissions,
options: Dir.OpenOptions,
) Dir.CreateDirPathOpenError!Dir {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const w = windows;
_ = permissions; // TODO 应用这些权限
var it = Dir.path.componentIterator(sub_path);
// 如果路径中没有组成部分,则创建一个包含完整路径的虚拟组成部分。
var component: Dir.path.NativeComponentIterator.Component = it.last() orelse .{
.name = "",
.path = sub_path,
};
components: while (true) {
const sub_path_w = try sliceToPrefixedFileW(dir.handle, component.path, .{});
const attr: windows.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w.span())) null else dir.handle,
.ObjectName = @constCast(&sub_path_w.string()),
};
const is_last = it.peekNext() == null;
var result: Dir = .{ .handle = undefined };
var iosb: w.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (w.ntdll.NtCreateFile(
&result.handle,
.{
.SPECIFIC = .{ .FILE_DIRECTORY = .{
.LIST = options.iterate,
.READ_EA = true,
.READ_ATTRIBUTES = true,
.TRAVERSE = true,
} },
.STANDARD = .{
.RIGHTS = .READ,
.SYNCHRONIZE = true,
},
},
&attr,
&iosb,
null,
.{ .NORMAL = true },
.VALID_FLAGS,
if (is_last) .OPEN_IF else .CREATE,
.{
.DIRECTORY_FILE = true,
.IO = .SYNCHRONOUS_NONALERT,
.OPEN_FOR_BACKUP_INTENT = true,
.OPEN_REPARSE_POINT = !options.follow_symlinks,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
component = it.next() orelse return result;
w.CloseHandle(result.handle);
continue :components;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_COLLISION => {
syscall.finish();
assert(!is_last);
// 获取文件状态,若不是目录则返回错误
// 此检查很重要,否则悬空符号链接
// 可能导致无限循环
const fstat = try dirStatFileWindows(t, dir, component.path, .{
.follow_symlinks = options.follow_symlinks,
});
if (fstat.kind != .directory) return error.NotDir;
component = it.next().?;
continue :components;
},
.OBJECT_NAME_NOT_FOUND,
.OBJECT_PATH_NOT_FOUND,
=> {
syscall.finish();
component = it.previous() orelse return error.FileNotFound;
continue :components;
},
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
// 如果目录的“列出文件夹内容”权限设置为“拒绝”,且尝试以可迭代方式打开目录,则可能发生此情况。
//
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.DISK_FULL => return syscall.fail(error.NoSpaceLeft),
.INVALID_PARAMETER => |s| return syscall.ntstatusBug(s),
else => |s| return syscall.unexpectedNtstatus(s),
};
}
}
fn dirCreateDirPathOpenWasi(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
permissions: Dir.Permissions,
options: Dir.OpenOptions,
) Dir.CreateDirPathOpenError!Dir {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const t_io = io(t);
return dirOpenDirWasi(t, dir, sub_path, options) catch |err| switch (err) {
error.FileNotFound => {
_ = try dir.createDirPathStatus(t_io, sub_path, permissions);
return dirOpenDirWasi(t, dir, sub_path, options);
},
else => |e| return e,
};
}
fn dirStat(userdata: ?*anyopaque, dir: Dir) Dir.StatError!Dir.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
return fileStat(t, .{
.handle = dir.handle,
.flags = .{ .nonblocking = false },
});
}
const dirStatFile = switch (native_os) {
.linux => dirStatFileLinux,
.windows => dirStatFileWindows,
.wasi => dirStatFileWasi,
else => dirStatFilePosix,
};
fn dirStatFileLinux(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.StatFileOptions,
) Dir.StatFileError!File.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const linux = std.os.linux;
const sys = if (statx_use_c) std.c else std.os.linux;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const flags: u32 = linux.AT.NO_AUTOMOUNT |
@as(u32, if (!options.follow_symlinks) linux.AT.SYMLINK_NOFOLLOW else 0);
const syscall: Syscall = try .start();
while (true) {
var statx = std.mem.zeroes(linux.Statx);
switch (sys.errno(sys.statx(dir.handle, sub_path_posix, flags, linux_statx_request, &statx))) {
.SUCCESS => {
syscall.finish();
return statFromLinux(&statx);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => |err| return errnoBug(err), // 由上面的 pathToPosix() 处理。
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirStatFilePosix(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.StatFileOptions,
) Dir.StatFileError!File.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const flags: u32 = if (!options.follow_symlinks) posix.AT.SYMLINK_NOFOLLOW else 0;
return posixStatFile(dir.handle, sub_path_posix, flags);
}
fn posixStatFile(dir_fd: posix.fd_t, sub_path: [:0]const u8, flags: u32) Dir.StatFileError!File.Stat {
const syscall: Syscall = try .start();
while (true) {
var stat = std.mem.zeroes(posix.Stat);
switch (posix.errno(fstatat_sym(dir_fd, sub_path, &stat, flags))) {
.SUCCESS => {
syscall.finish();
return statFromPosix(&stat);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOMEM => return error.SystemResources,
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.FAULT => |err| return errnoBug(err),
.NAMETOOLONG => return error.NameTooLong,
.LOOP => return error.SymLinkLoop,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.FileNotFound,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirStatFileWindows(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.StatFileOptions,
) Dir.StatFileError!File.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const file = try dirOpenFileWindows(t, dir, sub_path, .{
.follow_symlinks = options.follow_symlinks,
});
defer windows.CloseHandle(file.handle);
return fileStatWindows(t, file);
}
fn dirStatFileWasi(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.StatFileOptions,
) Dir.StatFileError!File.Stat {
if (builtin.link_libc) return dirStatFilePosix(userdata, dir, sub_path, options);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const wasi = std.os.wasi;
const flags: wasi.lookupflags_t = .{
.SYMLINK_FOLLOW = options.follow_symlinks,
};
var stat: wasi.filestat_t = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (wasi.path_filestat_get(dir.handle, flags, sub_path.ptr, sub_path.len, &stat)) {
.SUCCESS => {
syscall.finish();
return statFromWasi(&stat);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOMEM => return error.SystemResources,
.ACCES => return error.AccessDenied,
.FAULT => |err| return errnoBug(err),
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.FileNotFound,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn filePathKind(t: *Threaded, dir: Dir, sub_path: []const u8) !File.Kind {
if (native_os == .linux) {
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const linux = std.os.linux;
const syscall: Syscall = try .start();
while (true) {
var statx = std.mem.zeroes(linux.Statx);
switch (linux.errno(linux.statx(
dir.handle,
sub_path_posix,
linux.AT.NO_AUTOMOUNT | linux.AT.SYMLINK_NOFOLLOW,
.{ .TYPE = true },
&statx,
))) {
.SUCCESS => {
syscall.finish();
if (!statx.mask.TYPE) return error.Unexpected;
return statxKind(statx.mode);
},
.INTR => {
try syscall.checkCancel();
continue;
},
.NOMEM => return syscall.fail(error.SystemResources),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
const stat = try dirStatFile(t, dir, sub_path, .{ .follow_symlinks = false });
return stat.kind;
}
fn fileLength(userdata: ?*anyopaque, file: File) File.LengthError!u64 {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (native_os == .linux) {
const linux = std.os.linux;
const syscall: Syscall = try .start();
while (true) {
var statx = std.mem.zeroes(linux.Statx);
switch (linux.errno(linux.statx(file.handle, "", linux.AT.EMPTY_PATH, .{ .SIZE = true }, &statx))) {
.SUCCESS => {
syscall.finish();
if (!statx.mask.SIZE) return error.Unexpected;
return statx.size;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.LOOP => |err| return errnoBug(err),
.NAMETOOLONG => |err| return errnoBug(err),
.NOENT => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
.NOTDIR => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
} else if (is_windows) {
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var info: windows.FILE.STANDARD_INFORMATION = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryInformationFile(
file.handle,
&io_status_block,
&info,
@sizeOf(windows.FILE.STANDARD_INFORMATION),
.Standard,
)) {
.SUCCESS => break syscall.finish(),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |s| return syscall.unexpectedNtstatus(s),
};
return @as(u64, @bitCast(info.EndOfFile));
}
const stat = try fileStat(t, file);
return stat.size;
}
const fileStat = switch (native_os) {
.linux => fileStatLinux,
.windows => fileStatWindows,
.wasi => fileStatWasi,
else => fileStatPosix,
};
fn fileStatPosix(userdata: ?*anyopaque, file: File) File.StatError!File.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (posix.Stat == void) return error.Streaming;
const syscall: Syscall = try .start();
while (true) {
var stat = std.mem.zeroes(posix.Stat);
switch (posix.errno(fstat_sym(file.handle, &stat))) {
.SUCCESS => {
syscall.finish();
return statFromPosix(&stat);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOMEM => return error.SystemResources,
.ACCES => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileStatLinux(userdata: ?*anyopaque, file: File) File.StatError!File.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const linux = std.os.linux;
const sys = if (statx_use_c) std.c else std.os.linux;
const syscall: Syscall = try .start();
while (true) {
var statx = std.mem.zeroes(linux.Statx);
switch (sys.errno(sys.statx(file.handle, "", linux.AT.EMPTY_PATH, linux_statx_request, &statx))) {
.SUCCESS => {
syscall.finish();
return statFromLinux(&statx);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.LOOP => |err| return errnoBug(err),
.NAMETOOLONG => |err| return errnoBug(err),
.NOENT => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
.NOTDIR => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileStatWindows(userdata: ?*anyopaque, file: File) File.StatError!File.Stat {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const block_size: u32 = if (t.systemBasicInformation()) |sbi|
@intCast(@max(sbi.PageSize, sbi.AllocationGranularity))
else
std.heap.page_size_max;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var info: windows.FILE.ALL_INFORMATION = undefined;
{
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryInformationFile(
file.handle,
&io_status_block,
&info,
@sizeOf(windows.FILE.ALL_INFORMATION),
.All,
)) {
.SUCCESS => break syscall.finish(),
// 此处缓冲区溢出表示可用信息多于所提供大小的缓冲区
// 能够容纳的信息。将其视为成功,因为相关的可变长度信息
// (名称、卷名等)并非我们关心的内容。
.BUFFER_OVERFLOW => break syscall.finish(),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |s| return syscall.unexpectedNtstatus(s),
};
}
return .{
.inode = info.InternalInformation.IndexNumber,
.size = @as(u64, @bitCast(info.StandardInformation.EndOfFile)),
.permissions = .default_file,
.kind = if (info.BasicInformation.FileAttributes.REPARSE_POINT) reparse_point: {
var tag_info: windows.FILE.ATTRIBUTE_TAG_INFO = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryInformationFile(
file.handle,
&io_status_block,
&tag_info,
@sizeOf(windows.FILE.ATTRIBUTE_TAG_INFO),
.AttributeTag,
)) {
.SUCCESS => break syscall.finish(),
// 文档记载的可能错误仅有 INFO_LENGTH_MISMATCH 和 ACCESS_DENIED。
// https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/d295752f-ce89-4b98-8553-266d37c84f0e
.INFO_LENGTH_MISMATCH => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |s| return syscall.unexpectedNtstatus(s),
};
if (tag_info.ReparseTag.IsSurrogate) break :reparse_point .sym_link;
// 未知的重解析点
break :reparse_point .unknown;
} else if (info.BasicInformation.FileAttributes.DIRECTORY)
.directory
else
.file,
.atime = windows.fromSysTime(info.BasicInformation.LastAccessTime),
.mtime = windows.fromSysTime(info.BasicInformation.LastWriteTime),
.ctime = windows.fromSysTime(info.BasicInformation.ChangeTime),
.nlink = info.StandardInformation.NumberOfLinks,
.block_size = block_size,
};
}
fn systemBasicInformation(t: *Threaded) ?*const windows.SYSTEM.BASIC_INFORMATION {
if (!t.system_basic_information.initialized.load(.acquire)) {
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
switch (windows.ntdll.NtQuerySystemInformation(
.Basic,
&t.system_basic_information.buffer,
@sizeOf(windows.SYSTEM.BASIC_INFORMATION),
null,
)) {
.SUCCESS => {},
else => return null,
}
t.system_basic_information.initialized.store(true, .release);
}
return &t.system_basic_information.buffer;
}
fn fileStatWasi(userdata: ?*anyopaque, file: File) File.StatError!File.Stat {
if (builtin.link_libc) return fileStatPosix(userdata, file);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
var stat: std.os.wasi.filestat_t = undefined;
switch (std.os.wasi.fd_filestat_get(file.handle, &stat)) {
.SUCCESS => {
syscall.finish();
return statFromWasi(&stat);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOMEM => return error.SystemResources,
.ACCES => return error.AccessDenied,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const dirAccess = switch (native_os) {
.windows => dirAccessWindows,
.wasi => dirAccessWasi,
else => dirAccessPosix,
};
fn dirAccessPosix(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.AccessOptions,
) Dir.AccessError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const flags: u32 = @as(u32, if (!options.follow_symlinks) posix.AT.SYMLINK_NOFOLLOW else 0);
const mode: u32 =
@as(u32, if (options.read) posix.R_OK else 0) |
@as(u32, if (options.write) posix.W_OK else 0) |
@as(u32, if (options.execute) posix.X_OK else 0);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.faccessat(dir.handle, sub_path_posix, mode, flags))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
.LOOP => return error.SymLinkLoop,
.TXTBSY => return error.FileBusy,
.NOTDIR => return error.FileNotFound,
.NOENT => return error.FileNotFound,
.NAMETOOLONG => return error.NameTooLong,
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.IO => return error.InputOutput,
.NOMEM => return error.SystemResources,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirAccessWasi(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.AccessOptions,
) Dir.AccessError!void {
if (builtin.link_libc) return dirAccessPosix(userdata, dir, sub_path, options);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const wasi = std.os.wasi;
const flags: wasi.lookupflags_t = .{
.SYMLINK_FOLLOW = options.follow_symlinks,
};
var stat: wasi.filestat_t = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (wasi.path_filestat_get(dir.handle, flags, sub_path.ptr, sub_path.len, &stat)) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOMEM => return error.SystemResources,
.ACCES => return error.AccessDenied,
.FAULT => |err| return errnoBug(err),
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.FileNotFound,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
if (!options.read and !options.write and !options.execute)
return;
var directory: wasi.fdstat_t = undefined;
if (wasi.fd_fdstat_get(dir.handle, &directory) != .SUCCESS)
return error.AccessDenied;
var rights: wasi.rights_t = .{};
if (options.read) {
if (stat.filetype == .DIRECTORY) {
rights.FD_READDIR = true;
} else {
rights.FD_READ = true;
}
}
if (options.write)
rights.FD_WRITE = true;
// 不校验执行权限。
// https://github.com/ziglang/zig/issues/18882
const rights_int: u64 = @bitCast(rights);
const inheriting_int: u64 = @bitCast(directory.fs_rights_inheriting);
if ((rights_int & inheriting_int) != rights_int)
return error.AccessDenied;
}
fn dirAccessWindows(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.AccessOptions,
) Dir.AccessError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
_ = options; // TODO
if (std.mem.eql(u8, sub_path, ".") or std.mem.eql(u8, sub_path, "..")) return;
const sub_path_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
const attr: windows.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w.span())) null else dir.handle,
.ObjectName = @constCast(&sub_path_w.string()),
};
var basic_info: windows.FILE.BASIC_INFORMATION = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryAttributesFile(&attr, &basic_info)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_NAME_INVALID => |err| return syscall.ntstatusBug(err),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.OBJECT_PATH_SYNTAX_BAD => |err| return syscall.ntstatusBug(err),
else => |rc| return syscall.unexpectedNtstatus(rc),
};
}
const dirCreateFile = switch (native_os) {
.windows => dirCreateFileWindows,
.wasi => dirCreateFileWasi,
else => dirCreateFilePosix,
};
fn dirCreateFilePosix(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.CreateFileOptions,
) File.OpenError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
var flags: posix.O = .{
.ACCMODE = if (options.read) .RDWR else .WRONLY,
.CREAT = true,
.TRUNC = options.truncate,
.EXCL = options.exclusive,
};
if (@hasField(posix.O, "LARGEFILE")) flags.LARGEFILE = true;
if (@hasField(posix.O, "CLOEXEC")) flags.CLOEXEC = true;
if (@hasField(posix.O, "RESOLVE_BENEATH")) flags.RESOLVE_BENEATH = options.resolve_beneath;
// 若操作系统支持,则使用 O 锁定标志原子获取锁。
// 注意,openat() 调用成功后,
// 会移除 NONBLOCK 标志。
if (have_flock_open_flags) switch (options.lock) {
.none => {},
.shared => {
flags.SHLOCK = true;
flags.NONBLOCK = options.lock_nonblocking;
},
.exclusive => {
flags.EXLOCK = true;
flags.NONBLOCK = options.lock_nonblocking;
},
};
const fd: posix.fd_t = fd: {
const syscall: Syscall = try .start();
while (true) {
const rc = openat_sym(dir.handle, sub_path_posix, flags, options.permissions.toMode());
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :fd @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => return error.BadPathName,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.FBIG => return error.FileTooBig,
.OVERFLOW => return error.FileTooBig,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.SRCH => return error.FileNotFound, // Linux 上访问 procfs 时。
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.EXIST => return error.PathAlreadyExists,
.BUSY => return error.DeviceBusy,
.OPNOTSUPP => return error.FileLocksUnsupported,
.AGAIN => return error.WouldBlock,
.TXTBSY => return error.FileBusy,
.NXIO => return error.NoDevice,
.ROFS => return error.ReadOnlyFileSystem,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
};
errdefer closeFd(fd);
if (have_flock and !have_flock_open_flags and options.lock != .none) {
const lock_nonblocking: i32 = if (options.lock_nonblocking) posix.LOCK.NB else 0;
const lock_flags = switch (options.lock) {
.none => unreachable,
.shared => posix.LOCK.SH | lock_nonblocking,
.exclusive => posix.LOCK.EX | lock_nonblocking,
};
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.flock(fd, lock_flags))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => |err| return errnoBug(err), // 无效参数
.NOLCK => return error.SystemResources,
.AGAIN => return error.WouldBlock,
.OPNOTSUPP => return error.FileLocksUnsupported,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
if (have_flock_open_flags and options.lock_nonblocking) {
var fl_flags: usize = fl: {
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.fcntl(fd, posix.F.GETFL, @as(u32, 0));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :fl @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |err| {
syscall.finish();
return posix.unexpectedErrno(err);
},
}
}
};
fl_flags &= ~@as(usize, 1 << @bitOffsetOf(posix.O, "NONBLOCK"));
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.fcntl(fd, posix.F.SETFL, fl_flags))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |err| {
syscall.finish();
return posix.unexpectedErrno(err);
},
}
}
}
return .{
.handle = fd,
.flags = .{ .nonblocking = false },
};
}
fn dirCreateFileWindows(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
flags: Dir.CreateFileOptions,
) File.OpenError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (std.mem.eql(u8, sub_path, ".")) return error.IsDir;
if (std.mem.eql(u8, sub_path, "..")) return error.IsDir;
const sub_path_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
const attr: windows.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w.span())) null else dir.handle,
.ObjectName = @constCast(&sub_path_w.string()),
};
const create_disposition: windows.FILE.CREATE_DISPOSITION = if (flags.exclusive)
.CREATE
else if (flags.truncate)
.OVERWRITE_IF
else
.OPEN_IF;
const access_mask: windows.ACCESS_MASK = .{
.STANDARD = .{ .SYNCHRONIZE = true },
.GENERIC = .{
.WRITE = true,
.READ = flags.read,
},
};
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var attempt: u5 = 0;
var handle: windows.HANDLE = undefined;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtCreateFile(
&handle,
access_mask,
&attr,
&io_status_block,
null,
.{ .NORMAL = true },
.VALID_FLAGS, // 共享访问
create_disposition,
.{
.NON_DIRECTORY_FILE = true,
.IO = .SYNCHRONOUS_NONALERT,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
break;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.SHARING_VIOLATION => {
// 尝试打开正在运行的可执行文件时会发生此错误。
// 但存在内核缺陷:可执行文件关闭后,在长短不确定的一段时间内仍可能错误返回此错误。
// 这里通过重试规避该内核缺陷。
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.DELETE_PENDING => {
// 此错误表示文件系统中此位置*曾经*存在
// 文件,但它已被删除。然而,操作系统尚未
// 完成删除操作,因此此 CreateFile
// 调用失败。此处通过休眠并重试,
// 直到错误消失,来模拟内核缺陷已被修复时的行为。
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.BAD_NETWORK_PATH => return syscall.fail(error.NetworkNotFound), // 未找到 \\server
.BAD_NETWORK_NAME => return syscall.fail(error.NetworkNotFound), // 找到 \\server,但未找到 \\server\share
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_BUSY => return syscall.fail(error.PipeBusy),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.NoDevice),
.OBJECT_NAME_COLLISION => return syscall.fail(error.PathAlreadyExists),
.FILE_IS_A_DIRECTORY => return syscall.fail(error.IsDir),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
.VIRUS_INFECTED, .VIRUS_DELETED => return syscall.fail(error.AntivirusInterference),
.DISK_FULL => return syscall.fail(error.NoSpaceLeft),
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.OBJECT_PATH_SYNTAX_BAD => |status| return syscall.ntstatusBug(status),
.INVALID_HANDLE => |status| return syscall.ntstatusBug(status),
else => |status| return syscall.unexpectedNtstatus(status),
};
errdefer windows.CloseHandle(handle);
const exclusive = switch (flags.lock) {
.none => return .{
.handle = handle,
.flags = .{ .nonblocking = false },
},
.shared => false,
.exclusive => true,
};
syscall = try .start();
while (true) switch (windows.ntdll.NtLockFile(
handle,
null,
null,
null,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
null,
.fromBool(flags.lock_nonblocking),
.fromBool(exclusive),
)) {
.SUCCESS => {
syscall.finish();
return .{
.handle = handle,
.flags = .{ .nonblocking = false },
};
},
.INSUFFICIENT_RESOURCES => return syscall.fail(error.SystemResources),
.LOCK_NOT_GRANTED => return syscall.fail(error.WouldBlock),
.ACCESS_VIOLATION => |err| return syscall.ntstatusBug(err), // 无效的 io_status_block 指针
else => |status| return syscall.unexpectedNtstatus(status),
};
}
fn dirCreateFileWasi(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
flags: Dir.CreateFileOptions,
) File.OpenError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const wasi = std.os.wasi;
const lookup_flags: wasi.lookupflags_t = .{};
const oflags: wasi.oflags_t = .{
.CREAT = true,
.TRUNC = flags.truncate,
.EXCL = flags.exclusive,
};
const fdflags: wasi.fdflags_t = .{};
const base: wasi.rights_t = .{
.FD_READ = flags.read,
.FD_WRITE = true,
.FD_DATASYNC = true,
.FD_SEEK = true,
.FD_TELL = true,
.FD_FDSTAT_SET_FLAGS = true,
.FD_SYNC = true,
.FD_ALLOCATE = true,
.FD_ADVISE = true,
.FD_FILESTAT_SET_TIMES = true,
.FD_FILESTAT_SET_SIZE = true,
.FD_FILESTAT_GET = true,
// 只有同时设置对应的 FD_READ 和/或 FD_WRITE 时,
// POLL_FD_READWRITE 才授予额外权限。
.POLL_FD_READWRITE = true,
};
const inheriting: wasi.rights_t = .{};
var fd: posix.fd_t = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (wasi.path_open(dir.handle, lookup_flags, sub_path.ptr, sub_path.len, oflags, base, inheriting, fdflags, &fd)) {
.SUCCESS => {
syscall.finish();
return .{
.handle = fd,
.flags = .{ .nonblocking = false },
};
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => return error.BadPathName,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.FBIG => return error.FileTooBig,
.OVERFLOW => return error.FileTooBig,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.EXIST => return error.PathAlreadyExists,
.BUSY => return error.DeviceBusy,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirCreateFileAtomic(
userdata: ?*anyopaque,
dir: Dir,
dest_path: []const u8,
options: Dir.CreateFileAtomicOptions,
) Dir.CreateFileAtomicError!File.Atomic {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const t_io = io(t);
// Linux 有 O_TMPFILE,但 linkat() 不支持 AT_REPLACE,因此
// 既然最终仍须构造一个临时路径名执行 rename(),
// 它便没有用处。
if (native_os == .linux and !options.replace) tmpfile: {
const flags: posix.O = if (@hasField(posix.O, "TMPFILE")) .{
.ACCMODE = .RDWR,
.TMPFILE = true,
.DIRECTORY = true,
.CLOEXEC = true,
} else if (@hasField(posix.O, "TMPFILE0") and !@hasField(posix.O, "TMPFILE2")) .{
.ACCMODE = .RDWR,
.TMPFILE0 = true,
.TMPFILE1 = true,
.DIRECTORY = true,
.CLOEXEC = true,
} else break :tmpfile;
const dest_dirname = Dir.path.dirname(dest_path);
if (dest_dirname) |dirname| {
// 这样还有一个有益的副作用:预先触发 EISDIR 或
// ENOENT,避免下方的歧义。
if (options.make_path) dir.createDirPath(t_io, dirname) catch |err| switch (err) {
// 这些值在此上下文中均无意义。
error.IsDir,
error.Streaming,
error.DiskQuota,
error.PathAlreadyExists,
error.LinkQuotaExceeded,
error.PipeBusy,
error.FileTooBig,
error.DeviceBusy,
error.FileLocksUnsupported,
error.FileBusy,
=> return error.Unexpected,
else => |e| return e,
};
}
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(dest_dirname orelse ".", &path_buffer);
const syscall: Syscall = try .start();
while (true) {
const rc = openat_sym(dir.handle, sub_path_posix, flags, options.permissions.toMode());
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return .{
.file = .{
.handle = @intCast(rc),
.flags = .{ .nonblocking = false },
},
.file_basename_hex = 0,
.dest_sub_path = dest_path,
.file_open = true,
.file_exists = false,
.close_dir_on_deinit = false,
.dir = dir,
};
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ISDIR, .NOENT, .OPNOTSUPP => {
// 含义不明确的错误码。它可能表示文件系统不支持 O_TMPFILE,因此必须回退到不使用 O_TMPFILE。
//
//
syscall.finish();
break :tmpfile;
},
.INVAL => return syscall.fail(error.BadPathName),
.ACCES => return syscall.fail(error.AccessDenied),
.LOOP => return syscall.fail(error.SymLinkLoop),
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NFILE => return syscall.fail(error.SystemFdQuotaExceeded),
.NODEV => return syscall.fail(error.NoDevice),
.NOMEM => return syscall.fail(error.SystemResources),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.NOTDIR => return syscall.fail(error.NotDir),
.PERM => return syscall.fail(error.PermissionDenied),
.AGAIN => return syscall.fail(error.WouldBlock),
.NXIO => return syscall.fail(error.NoDevice),
.ILSEQ => return syscall.fail(error.BadPathName),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
if (Dir.path.dirname(dest_path)) |dirname| {
const new_dir = if (options.make_path)
dir.createDirPathOpen(t_io, dirname, .{}) catch |err| switch (err) {
// 这些值在此上下文中均无意义。
error.IsDir,
error.Streaming,
error.DiskQuota,
error.PathAlreadyExists,
error.LinkQuotaExceeded,
error.PipeBusy,
error.FileTooBig,
error.FileLocksUnsupported,
error.DeviceBusy,
=> return error.Unexpected,
else => |e| return e,
}
else
try dir.openDir(t_io, dirname, .{});
return atomicFileInit(t_io, Dir.path.basename(dest_path), options.permissions, new_dir, true);
}
return atomicFileInit(t_io, dest_path, options.permissions, dir, false);
}
fn atomicFileInit(
t_io: Io,
dest_basename: []const u8,
permissions: File.Permissions,
dir: Dir,
close_dir_on_deinit: bool,
) Dir.CreateFileAtomicError!File.Atomic {
while (true) {
var random_integer: u64 = undefined;
t_io.random(@ptrCast(&random_integer));
const tmp_sub_path = std.fmt.hex(random_integer);
const file = dir.createFile(t_io, &tmp_sub_path, .{
.permissions = permissions,
.exclusive = true,
}) catch |err| switch (err) {
error.PathAlreadyExists => continue,
error.DeviceBusy => continue,
error.FileBusy => continue,
error.IsDir => return error.Unexpected, // 没有路径分量。
error.FileTooBig => return error.Unexpected, // 执行创建而非打开。
error.FileLocksUnsupported => return error.Unexpected, // 不请求锁。
error.PipeBusy => return error.Unexpected, // 未在打开管道。
else => |e| return e,
};
return .{
.file = file,
.file_basename_hex = random_integer,
.dest_sub_path = dest_basename,
.file_open = true,
.file_exists = true,
.close_dir_on_deinit = close_dir_on_deinit,
.dir = dir,
};
}
}
const dirOpenFile = switch (native_os) {
.windows => dirOpenFileWindows,
.wasi => dirOpenFileWasi,
else => dirOpenFilePosix,
};
fn dirOpenFilePosix(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.OpenFileOptions,
) File.OpenError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
var flags: posix.O = switch (native_os) {
.wasi => .{
.read = options.mode != .write_only,
.write = options.mode != .read_only,
.NOFOLLOW = !options.follow_symlinks,
},
else => .{
.ACCMODE = switch (options.mode) {
.read_only => .RDONLY,
.write_only => .WRONLY,
.read_write => .RDWR,
},
.NOFOLLOW = !options.follow_symlinks,
},
};
if (@hasField(posix.O, "CLOEXEC")) flags.CLOEXEC = true;
if (@hasField(posix.O, "LARGEFILE")) flags.LARGEFILE = true;
if (@hasField(posix.O, "NOCTTY")) flags.NOCTTY = !options.allow_ctty;
if (@hasField(posix.O, "PATH")) flags.PATH = options.path_only;
if (@hasField(posix.O, "RESOLVE_BENEATH")) flags.RESOLVE_BENEATH = options.resolve_beneath;
// 若操作系统支持,则使用 O 锁定选项原子获取锁。注意,openat() 成功后会移除 NONBLOCK 标志。
//
//
if (have_flock_open_flags) switch (options.lock) {
.none => {},
.shared => {
flags.SHLOCK = true;
flags.NONBLOCK = options.lock_nonblocking;
},
.exclusive => {
flags.EXLOCK = true;
flags.NONBLOCK = options.lock_nonblocking;
},
};
const mode: posix.mode_t = 0;
const fd: posix.fd_t = fd: {
const syscall: Syscall = try .start();
while (true) {
const rc = openat_sym(dir.handle, sub_path_posix, flags, mode);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :fd @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => return error.BadPathName,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.FBIG => return error.FileTooBig,
.OVERFLOW => return error.FileTooBig,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.SRCH => return error.FileNotFound, // Linux 打开 procfs 文件时。
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.EXIST => return error.PathAlreadyExists,
.BUSY => return error.DeviceBusy,
.OPNOTSUPP => return error.FileLocksUnsupported,
.AGAIN => return error.WouldBlock,
.TXTBSY => return error.FileBusy,
.NXIO => return error.NoDevice,
.ROFS => return error.ReadOnlyFileSystem,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
};
errdefer closeFd(fd);
if (!options.allow_directory) {
const is_dir = is_dir: {
const stat = fileStat(t, .{
.handle = fd,
.flags = .{ .nonblocking = false },
}) catch |err| switch (err) {
// 是否为目录未知,或无法确定。
error.Streaming => break :is_dir false,
else => |e| return e,
};
break :is_dir stat.kind == .directory;
};
if (is_dir) return error.IsDir;
}
if (have_flock and !have_flock_open_flags and options.lock != .none) {
const lock_nonblocking: i32 = if (options.lock_nonblocking) posix.LOCK.NB else 0;
const lock_flags = switch (options.lock) {
.none => unreachable,
.shared => posix.LOCK.SH | lock_nonblocking,
.exclusive => posix.LOCK.EX | lock_nonblocking,
};
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.flock(fd, lock_flags))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => |err| return errnoBug(err), // 无效参数
.NOLCK => return error.SystemResources,
.AGAIN => return error.WouldBlock,
.OPNOTSUPP => return error.FileLocksUnsupported,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
if (have_flock_open_flags and options.lock_nonblocking) {
var fl_flags: usize = fl: {
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.fcntl(fd, posix.F.GETFL, @as(u32, 0));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :fl @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |err| {
syscall.finish();
return posix.unexpectedErrno(err);
},
}
}
};
fl_flags &= ~@as(usize, 1 << @bitOffsetOf(posix.O, "NONBLOCK"));
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.fcntl(fd, posix.F.SETFL, fl_flags))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |err| {
syscall.finish();
return posix.unexpectedErrno(err);
},
}
}
}
return .{
.handle = fd,
.flags = .{ .nonblocking = false },
};
}
fn dirOpenFileWindows(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
flags: Dir.OpenFileOptions,
) File.OpenError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const sub_path_w_array = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
const sub_path_w = sub_path_w_array.span();
const dir_handle = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w)) null else dir.handle;
return dirOpenFileWtf16(dir_handle, sub_path_w, flags);
}
pub fn dirOpenFileWtf16(
dir_handle: ?windows.HANDLE,
sub_path_w: []const u16,
flags: Dir.OpenFileOptions,
) File.OpenError!File {
const allow_directory = flags.allow_directory and !flags.isWrite();
if (!allow_directory and std.mem.eql(u16, sub_path_w, &.{'.'})) return error.IsDir;
if (!allow_directory and std.mem.eql(u16, sub_path_w, &.{ '.', '.' })) return error.IsDir;
const w = windows;
var io_status_block: w.IO_STATUS_BLOCK = undefined;
var attempt: u5 = 0;
var syscall: Syscall = try .start();
const handle = while (true) {
var result: w.HANDLE = undefined;
switch (w.ntdll.NtCreateFile(
&result,
.{
.STANDARD = .{ .SYNCHRONIZE = true },
.GENERIC = .{
.READ = flags.isRead(),
.WRITE = flags.isWrite(),
},
},
&.{
.RootDirectory = dir_handle,
.ObjectName = @constCast(&w.UNICODE_STRING.init(sub_path_w)),
},
&io_status_block,
null,
.{ .NORMAL = true },
.VALID_FLAGS,
.OPEN,
.{
.IO = .SYNCHRONOUS_NONALERT,
.NON_DIRECTORY_FILE = !allow_directory,
.OPEN_REPARSE_POINT = !flags.follow_symlinks,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
break result;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.BAD_NETWORK_PATH => return syscall.fail(error.NetworkNotFound), // 未找到 \\server
.BAD_NETWORK_NAME => return syscall.fail(error.NetworkNotFound), // 找到 \\server,但未找到 \\server\share
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.SHARING_VIOLATION => {
// 尝试打开正在运行的可执行文件时会发生此错误。
// 但存在内核缺陷:可执行文件关闭后,在长短不确定的一段时间内仍可能错误返回此错误。
// 这里通过重试规避该内核缺陷。
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_BUSY => return syscall.fail(error.PipeBusy),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.NoDevice),
.OBJECT_PATH_SYNTAX_BAD => |err| return syscall.ntstatusBug(err),
.OBJECT_NAME_COLLISION => return syscall.fail(error.PathAlreadyExists),
.FILE_IS_A_DIRECTORY => return syscall.fail(error.IsDir),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
.INVALID_HANDLE => |err| return syscall.ntstatusBug(err),
.DELETE_PENDING => {
// 此错误表示文件系统中此位置*曾经*存在
// 文件,但它已被删除。然而,操作系统尚未
// 完成删除操作,因此此 CreateFile
// 调用失败。此处通过休眠并重试,
// 直到错误消失,来模拟内核缺陷已被修复时的行为。
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.VIRUS_INFECTED, .VIRUS_DELETED => return syscall.fail(error.AntivirusInterference),
else => |rc| return syscall.unexpectedNtstatus(rc),
}
};
errdefer w.CloseHandle(handle);
const exclusive = switch (flags.lock) {
.none => return .{
.handle = handle,
.flags = .{ .nonblocking = false },
},
.shared => false,
.exclusive => true,
};
syscall = try .start();
while (true) switch (w.ntdll.NtLockFile(
handle,
null,
null,
null,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
null,
.fromBool(flags.lock_nonblocking),
.fromBool(exclusive),
)) {
.SUCCESS => break syscall.finish(),
.INSUFFICIENT_RESOURCES => return syscall.fail(error.SystemResources),
.LOCK_NOT_GRANTED => return syscall.fail(error.WouldBlock),
.ACCESS_VIOLATION => |err| return syscall.ntstatusBug(err), // 无效的 io_status_block 指针
else => |status| return syscall.unexpectedNtstatus(status),
};
return .{
.handle = handle,
.flags = .{ .nonblocking = false },
};
}
fn dirOpenFileWasi(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
flags: Dir.OpenFileOptions,
) File.OpenError!File {
if (builtin.link_libc) return dirOpenFilePosix(userdata, dir, sub_path, flags);
const t: *Threaded = @ptrCast(@alignCast(userdata));
const wasi = std.os.wasi;
var base: std.os.wasi.rights_t = .{};
// 仅当相应的 FD_READ 和/或 FD_WRITE 也已设置时,
// POLL_FD_READWRITE 才授予额外权限。
if (flags.isRead()) {
base.FD_READ = true;
base.FD_TELL = true;
base.FD_SEEK = true;
base.FD_FILESTAT_GET = true;
base.POLL_FD_READWRITE = true;
}
if (flags.isWrite()) {
base.FD_WRITE = true;
base.FD_TELL = true;
base.FD_SEEK = true;
base.FD_DATASYNC = true;
base.FD_FDSTAT_SET_FLAGS = true;
base.FD_SYNC = true;
base.FD_ALLOCATE = true;
base.FD_ADVISE = true;
base.FD_FILESTAT_SET_TIMES = true;
base.FD_FILESTAT_SET_SIZE = true;
base.POLL_FD_READWRITE = true;
}
const lookup_flags: wasi.lookupflags_t = .{};
const oflags: wasi.oflags_t = .{};
const inheriting: wasi.rights_t = .{};
const fdflags: wasi.fdflags_t = .{};
var fd: posix.fd_t = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (wasi.path_open(dir.handle, lookup_flags, sub_path.ptr, sub_path.len, oflags, base, inheriting, fdflags, &fd)) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.FBIG => return error.FileTooBig,
.OVERFLOW => return error.FileTooBig,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.BUSY => return error.DeviceBusy,
.NOTCAPABLE => return error.AccessDenied,
.NAMETOOLONG => return error.NameTooLong,
.INVAL => return error.BadPathName,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
errdefer closeFd(fd);
if (!flags.allow_directory) {
const is_dir = is_dir: {
const stat = fileStat(t, .{ .handle = fd, .flags = .{ .nonblocking = false } }) catch |err| switch (err) {
// 是否为目录未知,或无法确定。
error.Streaming => break :is_dir false,
else => |e| return e,
};
break :is_dir stat.kind == .directory;
};
if (is_dir) return error.IsDir;
}
return .{
.handle = fd,
.flags = .{ .nonblocking = false },
};
}
const dirOpenDir = switch (native_os) {
.wasi => dirOpenDirWasi,
.haiku => dirOpenDirHaiku,
else => dirOpenDirPosix,
};
/// 链接 libc 时,此函数也用于 WASI。
fn dirOpenDirPosix(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.OpenOptions,
) Dir.OpenError!Dir {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
const sub_path_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
return dirOpenDirWindows(dir, sub_path_w.span(), options);
}
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
var flags: posix.O = switch (native_os) {
.wasi => .{
.read = true,
.NOFOLLOW = !options.follow_symlinks,
.DIRECTORY = true,
},
else => .{
.ACCMODE = .RDONLY,
.NOFOLLOW = !options.follow_symlinks,
.DIRECTORY = true,
.CLOEXEC = true,
},
};
if (@hasField(posix.O, "PATH") and !options.iterate)
flags.PATH = true;
const mode: posix.mode_t = 0;
const syscall: Syscall = try .start();
while (true) {
const rc = openat_sym(dir.handle, sub_path_posix, flags, mode);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return .{ .handle = @intCast(rc) };
},
.INTR => {
try syscall.checkCancel();
continue;
},
.INVAL => return syscall.fail(error.BadPathName),
.ACCES => return syscall.fail(error.AccessDenied),
.LOOP => return syscall.fail(error.SymLinkLoop),
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NFILE => return syscall.fail(error.SystemFdQuotaExceeded),
.NODEV => return syscall.fail(error.NoDevice),
.NOENT => return syscall.fail(error.FileNotFound),
.NOMEM => return syscall.fail(error.SystemResources),
.NOTDIR => return syscall.fail(error.NotDir),
.PERM => return syscall.fail(error.PermissionDenied),
.NXIO => return syscall.fail(error.NoDevice),
.ILSEQ => return syscall.fail(error.BadPathName),
.FAULT => |err| return syscall.errnoBug(err),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
.BUSY => |err| return syscall.errnoBug(err), // 未传入 O_EXCL
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn dirOpenDirHaiku(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.OpenOptions,
) Dir.OpenError!Dir {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
_ = options;
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system._kern_open_dir(dir.handle, sub_path_posix);
if (rc >= 0) {
syscall.finish();
return .{ .handle = rc };
}
switch (@as(posix.E, @fromBackingInt(@intCast(rc)))) {
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.BUSY => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
pub fn dirOpenDirWindows(
dir: Dir,
sub_path_w: []const u16,
options: Dir.OpenOptions,
) Dir.OpenError!Dir {
const w = windows;
var io_status_block: w.IO_STATUS_BLOCK = undefined;
var result: Dir = .{ .handle = undefined };
const attr: w.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w)) null else dir.handle,
.ObjectName = @constCast(&w.UNICODE_STRING.init(sub_path_w)),
};
const syscall: Syscall = try .start();
while (true) switch (w.ntdll.NtCreateFile(
&result.handle,
// TODO: 如果 options.access_sub_paths 为 false,则移除其中某些标志。
.{
.SPECIFIC = .{ .FILE_DIRECTORY = .{
.LIST = options.iterate,
.READ_EA = true,
.TRAVERSE = true,
.READ_ATTRIBUTES = true,
} },
.STANDARD = .{
.RIGHTS = .READ,
.SYNCHRONIZE = true,
},
},
&attr,
&io_status_block,
null,
.{ .NORMAL = true },
.VALID_FLAGS,
.OPEN,
.{
.DIRECTORY_FILE = true,
.IO = .SYNCHRONOUS_NONALERT,
.OPEN_FOR_BACKUP_INTENT = true,
.OPEN_REPARSE_POINT = !options.follow_symlinks,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
return result;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_NAME_COLLISION => |err| return w.statusBug(err),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
// 如果目录的“列出文件夹内容”权限设置为“拒绝”,且尝试以可迭代方式打开目录,则可能发生此情况。
//
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
else => |rc| return syscall.unexpectedNtstatus(rc),
};
}
fn dirClose(userdata: ?*anyopaque, dirs: []const Dir) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
for (dirs) |dir| {
if (is_windows) {
windows.CloseHandle(dir.handle);
} else {
closeFd(dir.handle);
}
}
}
const dirRead = switch (native_os) {
.linux => dirReadLinux,
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => dirReadDarwin,
.freebsd, .netbsd, .dragonfly, .openbsd => dirReadBsd,
.illumos => dirReadIllumos,
.haiku => dirReadHaiku,
.windows => dirReadWindows,
.wasi => dirReadWasi,
else => dirReadUnimplemented,
};
fn dirReadLinux(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
const linux = std.os.linux;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
if (dr.end - dr.index == 0) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
if (dr.state == .reset) {
posixSeekTo(dr.dir.handle, 0) catch |err| switch (err) {
error.Unseekable => return error.Unexpected,
else => |e| return e,
};
dr.state = .reading;
}
const syscall: Syscall = try .start();
const n = while (true) {
const rc = linux.getdents64(dr.dir.handle, dr.buffer.ptr, @min(dr.buffer.len, std.math.maxInt(c_uint)));
switch (linux.errno(rc)) {
.SUCCESS => {
syscall.finish();
break rc;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // Dir 无效,或打开时未启用迭代能力。
.FAULT => |err| return errnoBug(err),
.NOTDIR => |err| return errnoBug(err),
// 为保持跨平台一致,若遍历过程中
// 目录被删除,则终止遍历。
// 这与除 Linux、WASI 以外的
// UNIX 平台行为一致。
.NOENT => {
dr.state = .finished;
return 0;
},
// 读取 /proc/$PID/net 时可能发生,或者提供的缓冲区太小。此 API 不打算处理这两种情况。
//
//
.INVAL => return error.Unexpected,
.ACCES => return error.AccessDenied, // 没有遍历此目录的权限。
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
if (n == 0) {
dr.state = .finished;
return 0;
}
dr.index = 0;
dr.end = n;
}
// Linux 在名称的空字节后添加填充,对齐头部,
// 从而对齐下一个条目。因此,只检查下一个
// 记录之前的 8 字节即可找到名称末尾。但由于
// 文件名通常很短,最好保持机器码
// 简单。
//
// 此外,我观察到 qemu 用户模式不会对齐此结构体,
// 因此此代码采取保守选择,不假定其对齐。
const linux_entry: *align(1) linux.dirent64 = @ptrCast(&dr.buffer[dr.index]);
const next_index = dr.index + linux_entry.reclen;
dr.index = next_index;
const name_ptr: [*]u8 = &linux_entry.name;
const padded_name = name_ptr[0 .. linux_entry.reclen - @offsetOf(linux.dirent64, "name")];
const name_len = std.mem.findScalar(u8, padded_name, 0).?;
const name = name_ptr[0..name_len :0];
if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..")) continue;
const entry_kind: File.Kind = switch (linux_entry.type) {
linux.DT.BLK => .block_device,
linux.DT.CHR => .character_device,
linux.DT.DIR => .directory,
linux.DT.FIFO => .named_pipe,
linux.DT.LNK => .sym_link,
linux.DT.REG => .file,
linux.DT.SOCK => .unix_domain_socket,
else => .unknown,
};
buffer[buffer_index] = .{
.name = name,
.kind = entry_kind,
.inode = linux_entry.ino,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadDarwin(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const Header = extern struct {
seek: i64,
};
const header: *Header = @ptrCast(dr.buffer.ptr);
const header_end: usize = @sizeOf(Header);
if (dr.index < header_end) {
// 初始化头部。
dr.index = header_end;
dr.end = header_end;
header.* = .{ .seek = 0 };
}
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
if (dr.end - dr.index == 0) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
if (dr.state == .reset) {
posixSeekTo(dr.dir.handle, 0) catch |err| switch (err) {
error.Unseekable => return error.Unexpected,
else => |e| return e,
};
dr.state = .reading;
}
const dents_buffer = dr.buffer[header_end..];
const syscall: Syscall = try .start();
const n: usize = while (true) {
const rc = posix.system.getdirentries(dr.dir.handle, dents_buffer.ptr, dents_buffer.len, &header.seek);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // Dir 无效,或打开时未启用迭代能力。
.FAULT => |err| return errnoBug(err),
.NOTDIR => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
if (n == 0) {
dr.state = .finished;
return 0;
}
dr.index = header_end;
dr.end = header_end + n;
}
const darwin_entry = @as(*align(1) posix.system.dirent, @ptrCast(&dr.buffer[dr.index]));
const next_index = dr.index + darwin_entry.reclen;
dr.index = next_index;
const name = @as([*]u8, @ptrCast(&darwin_entry.name))[0..darwin_entry.namlen];
if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..") or (darwin_entry.ino == 0))
continue;
const entry_kind: File.Kind = switch (darwin_entry.type) {
posix.DT.BLK => .block_device,
posix.DT.CHR => .character_device,
posix.DT.DIR => .directory,
posix.DT.FIFO => .named_pipe,
posix.DT.LNK => .sym_link,
posix.DT.REG => .file,
posix.DT.SOCK => .unix_domain_socket,
posix.DT.WHT => .whiteout,
else => .unknown,
};
buffer[buffer_index] = .{
.name = name,
.kind = entry_kind,
.inode = darwin_entry.ino,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadBsd(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
if (dr.end - dr.index == 0) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
if (dr.state == .reset) {
posixSeekTo(dr.dir.handle, 0) catch |err| switch (err) {
error.Unseekable => return error.Unexpected,
else => |e| return e,
};
dr.state = .reading;
}
const syscall: Syscall = try .start();
const n: usize = while (true) {
const rc = posix.system.getdents(dr.dir.handle, dr.buffer.ptr, dr.buffer.len);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // Dir 无效,或打开时未启用迭代能力
.FAULT => |err| return errnoBug(err),
.NOTDIR => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
// FreeBSD 13.2 引入:目录已解除链接但仍打开。为保持一致,若遍历期间目录被删除,则结束迭代。
//
//
//
.NOENT => {
dr.state = .finished;
return 0;
},
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
if (n == 0) {
dr.state = .finished;
return 0;
}
dr.index = 0;
dr.end = n;
}
const bsd_entry = @as(*align(1) posix.system.dirent, @ptrCast(&dr.buffer[dr.index]));
const next_index = dr.index +
if (@hasField(posix.system.dirent, "reclen")) bsd_entry.reclen else bsd_entry.reclen();
dr.index = next_index;
const name = @as([*]u8, @ptrCast(&bsd_entry.name))[0..bsd_entry.namlen];
const skip_zero_fileno = switch (native_os) {
// fileno=0 用于标记无效条目或已删除文件。
.openbsd, .netbsd => true,
else => false,
};
if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..") or
(skip_zero_fileno and bsd_entry.fileno == 0))
{
continue;
}
const entry_kind: File.Kind = switch (bsd_entry.type) {
posix.DT.BLK => .block_device,
posix.DT.CHR => .character_device,
posix.DT.DIR => .directory,
posix.DT.FIFO => .named_pipe,
posix.DT.LNK => .sym_link,
posix.DT.REG => .file,
posix.DT.SOCK => .unix_domain_socket,
posix.DT.WHT => .whiteout,
else => .unknown,
};
buffer[buffer_index] = .{
.name = name,
.kind = entry_kind,
.inode = bsd_entry.fileno,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadIllumos(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
if (dr.end - dr.index == 0) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
if (dr.state == .reset) {
posixSeekTo(dr.dir.handle, 0) catch |err| switch (err) {
error.Unseekable => return error.Unexpected,
else => |e| return e,
};
dr.state = .reading;
}
const syscall: Syscall = try .start();
const n: usize = while (true) {
const rc = posix.system.getdents(dr.dir.handle, dr.buffer.ptr, dr.buffer.len);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break rc;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // Dir 无效,或打开时未启用迭代能力
.FAULT => |err| return errnoBug(err),
.NOTDIR => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
if (n == 0) {
dr.state = .finished;
return 0;
}
dr.index = 0;
dr.end = n;
}
const entry = @as(*align(1) posix.system.dirent, @ptrCast(&dr.buffer[dr.index]));
const next_index = dr.index + entry.reclen;
dr.index = next_index;
const name = std.mem.sliceTo(@as([*:0]u8, @ptrCast(&entry.name)), 0);
if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..")) continue;
// illumos 的 dirent 不公开类型,因此必须调用 stat 获取。
const stat = try posixStatFile(dr.dir.handle, name, posix.AT.SYMLINK_NOFOLLOW);
buffer[buffer_index] = .{
.name = name,
.kind = stat.kind,
.inode = entry.ino,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadHaiku(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
if (dr.end - dr.index == 0) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
if (dr.state == .reset) {
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system._kern_rewind_dir(dr.dir.handle);
switch (@as(posix.E, @fromBackingInt(@intCast(@min(rc, 0))))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
dr.state = .reading;
}
const syscall: Syscall = try .start();
const n: usize = while (true) {
const rc = posix.system._kern_read_dir(dr.dir.handle, dr.buffer.ptr, dr.buffer.len, @truncate(dr.buffer.len / @sizeOf(posix.system.DirEnt)));
switch (@as(posix.E, @fromBackingInt(@intCast(@min(rc, 0))))) {
.SUCCESS => {
syscall.finish();
break @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
if (n == 0) {
dr.state = .finished;
return 0;
}
dr.index = 0;
// _kern_read_dir 返回条目数,但 Dir.Reader 按字节数设计
dr.end = 0;
var i: usize = 0;
while (i < n) : (i += 1) {
const entry = @as(*align(1) posix.system.DirEnt, @ptrCast(&dr.buffer[dr.end]));
dr.end += entry.reclen;
}
}
const entry = @as(*align(1) posix.system.DirEnt, @ptrCast(&dr.buffer[dr.index]));
const next_index = dr.index + entry.reclen;
dr.index = next_index;
const name = std.mem.sliceTo(@as([*:0]u8, @ptrCast(&entry.name)), 0);
if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..") or entry.ino == 0) continue;
// haiku 的 dirent 不提供类型,因此必须调用 stat 获取。
var stat: std.c.Stat = undefined;
{
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system._kern_read_stat(dr.dir.handle, name, false, &stat, @sizeOf(std.c.Stat));
switch (@as(posix.E, @fromBackingInt(@intCast(@min(rc, 0))))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const entry_kind: File.Kind = switch (stat.mode & posix.S.IFMT) {
posix.S.IFBLK => .block_device,
posix.S.IFCHR => .character_device,
posix.S.IFDIR => .directory,
posix.S.IFIFO => .named_pipe,
posix.S.IFLNK => .sym_link,
posix.S.IFREG => .file,
else => .unknown,
};
buffer[buffer_index] = .{
.name = name,
.kind = entry_kind,
.inode = entry.ino,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadWindows(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const w = windows;
// 我们希望 `dr.buffer` 既用于 NtQueryDirectoryFile 调用(
// 返回 WTF-16 名称),*又*用于将这些 WTF-16 名称转换为 WTF-8 后存储,
// 以便通过 `Dir.Entry.name` 返回。但必须解决
// 以下问题:每个 WTF-16 代码单元最多编码为 3 个 WTF-8 字节,因此
// 存放 WTF-16 名称的内存不一定足以
// 容纳同一名称的 WTF-8 编码;例如 € 编码为一个 WTF-16 代码单元
// (2 字节),而 WTF-8 编码需要 3 字节。
//
// 这里采用的方法是在 `dr.buffer` 中“预留”足够空间,确保
// 至少能存放一个具有最大可能 WTF-8 名称长度的条目,
// 且不会覆盖后续条目。即先确定所需的预留空间,
// 然后仅将 `dr.buffer` 的剩余部分传给 NtQueryDirectoryFile
// 调用。随后便可使用完整的 `dr.buffer` 切片安全地转换 WTF-16 名称,
// 确保每个名称至多覆盖其自身条目的数据。
//
// 最坏情况下,条目名称既达到路径分量的最大长度,又完全由每个 WTF-16 代码单元转换为三个 WTF-8 字节的代码点组成,
// 其布局如下,此时只能返回一个条目:
//
// | 预留空间 | 剩余未预留缓冲区 |
// | 条目 1 | 条目 2 | ... |
// | 条目 1 的 WTF-8 名称 |
//
// 不过,通常可以在可用缓冲区中同时存放多个 WTF-8 名称,
// 因此一次可以填充多个 `Dir.Entry`。
// 布局可能如下,其中名称 1、名称 2 等表示转换后的 WTF-8 名称:
//
// | 预留空间 | 剩余未预留缓冲区 |
// | 条目 1 | 条目 2 | ... |
// | 名称 1 | 名称 2 | 名称 3 | 名称 4 | ... |
//
// 注意:可以预留超过最小需求的空间,以降低“最坏情况”
// 出现的概率。不过,只有路径分量达到最大长度时,最坏情况
// 才会构成问题;因此,即使文件系统中的所有名称
// 均由具有“一个 WTF-16 代码单元对应三个 WTF-8 字节”
// 性质的非 ASCII 字符组成(例如 >= U+0800 且 <= U+FFFF 的代码点),
// 通常也不太可能出现问题,因为大量路径分量
// 同时达到最大长度的情况很少见。
// 安全地以 WTF-8 存储最大长度分量需要 `3 * NAME_MAX` 字节。
// 既然需要存储最大长度分量,就意味着对应 `FileName` 的分量长度
// 达到上限,因此相应已填充的 `FILE_BOTH_DIR_INFORMATION` 的
// 大小必为 `@sizeOf(w.FILE_BOTH_DIR_INFORMATION) + 2 * NAME_MAX` 字节。考虑到
// 可以覆盖已预留内存及此特定 `FILE_BOTH_DIR_INFORMATION` 的
// 完整占用空间,只需额外预留足够内存,
// 使可用空间总计达到 `3 * NAME_MAX` 字节即可。
const max_info_len = @sizeOf(w.FILE_BOTH_DIR_INFORMATION) + w.NAME_MAX * 2;
const info_align = @alignOf(w.FILE_BOTH_DIR_INFORMATION);
const reserve_needed = std.mem.alignForward(usize, Dir.max_name_bytes, info_align) - max_info_len;
const unreserved_start = std.mem.alignForward(usize, reserve_needed, info_align);
const unreserved_buffer = dr.buffer[unreserved_start..];
// 此限制由 `Dir.Reader` 强制执行
assert(unreserved_buffer.len >= max_info_len);
var name_index: usize = 0;
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
if (dr.end - dr.index == 0) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
var io_status_block: w.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
const rc = while (true) switch (w.ntdll.NtQueryDirectoryFile(
dr.dir.handle,
null,
null,
null,
&io_status_block,
unreserved_buffer.ptr,
std.math.lossyCast(w.ULONG, unreserved_buffer.len),
.BothDirectory,
.FALSE,
null,
.fromBool(dr.state == .reset),
)) {
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |rc| {
syscall.finish();
break rc;
},
};
dr.state = .reading;
if (io_status_block.Information == 0) {
dr.state = .finished;
return 0;
}
dr.index = 0;
dr.end = io_status_block.Information;
switch (rc) {
.SUCCESS => {},
.ACCESS_DENIED => return error.AccessDenied, // 再次检查 Dir 是否以支持迭代的方式打开。
else => return w.unexpectedStatus(rc),
}
}
// 尽管官方 API 文档保证 FILE_BOTH_DIR_INFORMATION 正确对齐,
// 实际情况可能并非如此,例如有缺陷的虚拟机/沙箱工具会导致问题。
const dir_info: *align(2) w.FILE_BOTH_DIR_INFORMATION = @ptrCast(@alignCast(&unreserved_buffer[dr.index]));
const backtrack_index = dr.index;
if (dir_info.NextEntryOffset != 0) {
dr.index += dir_info.NextEntryOffset;
} else {
dr.index = dr.end;
}
const name_wtf16le = @as([*]u16, @ptrCast(&dir_info.FileName))[0 .. dir_info.FileNameLength / 2];
if (std.mem.eql(u16, name_wtf16le, &[_]u16{'.'}) or std.mem.eql(u16, name_wtf16le, &[_]u16{ '.', '.' })) {
continue;
}
// 现在就从 `dir_info` 读取相关信息,因为 WTF-8
// 名称可能会覆盖它。
const kind: File.Kind = blk: {
const attrs = dir_info.FileAttributes;
if (attrs.REPARSE_POINT) break :blk .sym_link;
if (attrs.DIRECTORY) break :blk .directory;
break :blk .file;
};
const inode: File.INode = dir_info.FileIndex;
// 若无法继续存放 WTF-8 名称而不覆盖剩余未处理条目,
// 则回退并返回当前已完成的内容。
if (name_index + std.unicode.calcWtf8Len(name_wtf16le) > unreserved_start + dr.index) {
// 无论如何,缓冲区应始终至少容纳一个条目
assert(buffer_index != 0);
dr.index = backtrack_index;
break;
}
const name_buf = dr.buffer[name_index..];
const name_wtf8_len = std.unicode.wtf16LeToWtf8(name_buf, name_wtf16le);
const name_wtf8 = name_buf[0..name_wtf8_len];
name_index += name_wtf8_len;
buffer[buffer_index] = .{
.name = name_wtf8,
.kind = kind,
.inode = inode,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadWasi(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
// 即使链接了 libc,我们也有意使用 fd_readdir,因为其
// 实现与下面完全相同,这样可以避免此处代码
// 变得复杂。
const wasi = std.os.wasi;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const Header = extern struct {
cookie: u64,
};
const header: *align(@alignOf(usize)) Header = @ptrCast(dr.buffer.ptr);
const header_end: usize = @sizeOf(Header);
if (dr.index < header_end) {
// 初始化头部。
dr.index = header_end;
dr.end = header_end;
header.* = .{ .cookie = wasi.DIRCOOKIE_START };
}
var buffer_index: usize = 0;
while (buffer.len - buffer_index != 0) {
// 根据 WASI 规范,最后一个条目可能被截断,因此
// 需要检查剩余缓冲区是否包含完整的 dirent。
if (dr.end - dr.index < @sizeOf(wasi.dirent_t)) {
// 重新填充缓冲区,
// 除非已创建对缓冲数据的引用。
if (buffer_index != 0) break;
if (dr.state == .reset) {
header.* = .{ .cookie = wasi.DIRCOOKIE_START };
dr.state = .reading;
}
const dents_buffer = dr.buffer[header_end..];
var n: usize = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (wasi.fd_readdir(dr.dir.handle, dents_buffer.ptr, dents_buffer.len, header.cookie, &n)) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // Dir 无效,或打开时未启用迭代能力。
.FAULT => |err| return errnoBug(err),
.NOTDIR => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
// 为保持跨平台一致,若遍历过程中
// 目录被删除,则终止遍历。
// 这与除 Linux、WASI 以外的
// UNIX 平台行为一致。
.NOENT => {
dr.state = .finished;
return 0;
},
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
if (n == 0) {
dr.state = .finished;
return 0;
}
dr.index = header_end;
dr.end = header_end + n;
}
const entry: *align(1) wasi.dirent_t = @ptrCast(&dr.buffer[dr.index]);
const entry_size = @sizeOf(wasi.dirent_t);
const name_index = dr.index + entry_size;
if (name_index + entry.namlen > dr.end) {
// 此时名称被截断,因此需要调用 readdir 存储完整名称。
dr.end = dr.index; // 强制在下一轮循环调用 fd_readdir。
continue;
}
const name = dr.buffer[name_index..][0..entry.namlen];
const next_index = name_index + entry.namlen;
dr.index = next_index;
header.cookie = entry.next;
if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, ".."))
continue;
const entry_kind: File.Kind = switch (entry.type) {
.BLOCK_DEVICE => .block_device,
.CHARACTER_DEVICE => .character_device,
.DIRECTORY => .directory,
.SYMBOLIC_LINK => .sym_link,
.REGULAR_FILE => .file,
.SOCKET_STREAM, .SOCKET_DGRAM => .unix_domain_socket,
else => .unknown,
};
buffer[buffer_index] = .{
.name = name,
.kind = entry_kind,
.inode = entry.ino,
};
buffer_index += 1;
}
return buffer_index;
}
fn dirReadUnimplemented(userdata: ?*anyopaque, dir_reader: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
_ = userdata;
_ = dir_reader;
_ = buffer;
return error.Unexpected;
}
const dirRealPathFile = switch (native_os) {
.windows => dirRealPathFileWindows,
else => dirRealPathFilePosix,
};
fn dirRealPathFileWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_name_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
const h_file = handle: {
if (OpenFile(path_name_w.span(), .{
.dir = dir.handle,
.access_mask = .{
.GENERIC = .{ .READ = true },
.STANDARD = .{ .SYNCHRONIZE = true },
},
.creation = .OPEN,
.filter = .any,
})) |handle| {
break :handle handle;
} else |err| switch (err) {
error.WouldBlock => unreachable,
else => |e| return e,
}
};
defer windows.CloseHandle(h_file);
// 可以复用路径缓冲区来存储 WTF-16 表示,
// 因为已不再需要带前缀的路径。
return realPathWindowsBuf(h_file, out_buffer, &path_name_w.data);
}
fn realPathWindows(h_file: windows.HANDLE, out_buffer: []u8) File.RealPathError!usize {
var wide_buf: [windows.PATH_MAX_WIDE]u16 = undefined;
return realPathWindowsBuf(h_file, out_buffer, &wide_buf);
}
fn realPathWindowsBuf(h_file: windows.HANDLE, out_buffer: []u8, wtf16_buffer: []u16) File.RealPathError!usize {
const wide_slice = try GetFinalPathNameByHandle(h_file, .{}, wtf16_buffer);
const len = std.unicode.calcWtf8Len(wide_slice);
if (len > out_buffer.len)
return error.NameTooLong;
return std.unicode.wtf16LeToWtf8(out_buffer, wide_slice);
}
/// 指定 `GetFinalPathNameByHandle` 结果中卷路径的格式。
/// 默认为 DOS 卷名。
pub const GetFinalPathNameByHandleFormat = struct {
volume_name: enum {
/// 格式化为 DOS 卷名
Dos,
/// 格式化为 NT 卷名称
Nt,
} = .Dos,
};
pub const GetFinalPathNameByHandleError = error{
AccessDenied,
FileNotFound,
NameTooLong,
/// 卷不包含可识别的文件系统。文件系统驱动程序
/// 可能未加载,或卷可能已损坏。
UnrecognizedVolume,
} || Io.Cancelable || Io.UnexpectedError;
/// 返回句柄对应的规范化路径。
/// 使用 `GetFinalPathNameByHandleFormat` 指定路径包含 NT 还是 DOS 卷名,例如 `\Device\HarddiskVolume0\foo.txt` 与 `C:\foo.txt`。
/// 若选择 DOS 卷名格式,注意此函数不会给结果路径添加 `\\?\` 前缀。
///
///
pub fn GetFinalPathNameByHandle(
hFile: windows.HANDLE,
fmt: GetFinalPathNameByHandleFormat,
out_buffer: []u16,
) GetFinalPathNameByHandleError![]u16 {
const final_path = QueryObjectName(hFile, out_buffer) catch |err| switch (err) {
// 假定 InvalidHandle 与 FileNotFound 的语义足够接近,
// 无需进一步增加错误集合的复杂度
error.InvalidHandle => return error.FileNotFound,
else => |e| return e,
};
switch (fmt.volume_name) {
.Nt => {
// 返回的路径已采用 .Nt 格式
return final_path;
},
.Dos => {
// 解析字符串,将卷路径与文件路径分离
const device_prefix = std.unicode.utf8ToUtf16LeStringLiteral("\\Device\\");
// 我们不能完全确定 QueryObjectName 在所有
// 上下文和环境中返回路径的结构。
// 此代码用于覆盖已遇到并适当
// 解决的各种情况。但请注意,
// 没有简单方法验证是否已全部处理!
// 如果读者知道方法,请付诸实现。
if (!std.mem.startsWith(u16, final_path, device_prefix)) {
// Wine 似乎会通过 QueryObjectName 返回以 \??\ 开头的 NT 命名空间路径,例如 `\??\Z:\some\path\to\a\file.txt`。
// 此时直接移除前缀,即可转换为绝对路径。
// https://github.com/ziglang/zig/issues/26029
// https://bugs.winehq.org/show_bug.cgi?id=39569
//
return windows.ntToWin32Namespace(final_path, out_buffer) catch |err| switch (err) {
error.NotNtPath => return error.Unexpected,
error.NameTooLong => |e| return e,
};
}
const file_path_begin_index = std.mem.findPos(u16, final_path, device_prefix.len, &[_]u16{'\\'}) orelse unreachable;
const volume_name_u16 = final_path[0..file_path_begin_index];
const device_name_u16 = volume_name_u16[device_prefix.len..];
const file_name_u16 = final_path[file_path_begin_index..];
// MUP 是 Multiple UNC Provider,表示该路径是 UNC
// 路径。此时只需移除 \Device\Mup\,并确保路径以 \\ 开头,
// 即可获取规范的 UNC 路径。
if (std.mem.eql(u16, device_name_u16, std.unicode.utf8ToUtf16LeStringLiteral("Mup"))) {
out_buffer[0] = '\\';
@memmove(out_buffer[1..][0..file_name_u16.len], file_name_u16);
return out_buffer[0 .. 1 + file_name_u16.len];
}
// 获取 DOS 卷名。DOS 卷名实际上是指向
// 实际 NT 卷的符号链接对象。例如:
// (NT) \Device\HarddiskVolume4 => (DOS) \DosDevices\C: == (DOS) C:
const MIN_SIZE = @sizeOf(windows.MOUNTMGR_MOUNT_POINT) + windows.MAX_PATH;
// 为方便起见,将输入缓冲区全部初始化为零,
// 因为 `DeviceIoControl` 配合 `IOCTL_MOUNTMGR_QUERY_POINTS` 时要求如此。
var input_buf: [MIN_SIZE]u8 align(@alignOf(windows.MOUNTMGR_MOUNT_POINT)) = @splat(0);
var output_buf: [MIN_SIZE * 4]u8 align(@alignOf(windows.MOUNTMGR_MOUNT_POINTS)) = undefined;
// 这个看似特殊的路径是 Windows 挂载管理器的文件系统路径。
// 来源:https://stackoverflow.com/questions/3012828/using-ioctl-mountmgr-query-points
// 这是 \\.\MountPointManager 的 NT 命名空间版本。
const mgmt_path_u16 = std.unicode.utf8ToUtf16LeStringLiteral("\\??\\MountPointManager");
const mgmt_handle = OpenFile(mgmt_path_u16, .{
.access_mask = .{ .STANDARD = .{ .SYNCHRONIZE = true } },
.creation = .OPEN,
}) catch |err| switch (err) {
error.IsDir => return error.Unexpected,
error.NotDir => return error.Unexpected,
error.NoDevice => return error.Unexpected,
error.AccessDenied => return error.Unexpected,
error.PipeBusy => return error.Unexpected,
error.FileBusy => return error.Unexpected,
error.PathAlreadyExists => return error.Unexpected,
error.WouldBlock => return error.Unexpected,
error.NetworkNotFound => return error.Unexpected,
error.AntivirusInterference => return error.Unexpected,
error.BadPathName => return error.Unexpected,
else => |e| return e,
};
defer windows.CloseHandle(mgmt_handle);
var input_struct: *windows.MOUNTMGR_MOUNT_POINT = @ptrCast(&input_buf[0]);
input_struct.DeviceNameOffset = @sizeOf(windows.MOUNTMGR_MOUNT_POINT);
input_struct.DeviceNameLength = @intCast(volume_name_u16.len * 2);
@memcpy(input_buf[@sizeOf(windows.MOUNTMGR_MOUNT_POINT)..][0 .. volume_name_u16.len * 2], @as([*]const u8, @ptrCast(volume_name_u16.ptr)));
switch ((try deviceIoControl(&.{
.file = .{ .handle = mgmt_handle, .flags = .{ .nonblocking = false } },
.code = windows.IOCTL.MOUNTMGR.QUERY_POINTS,
.in = &input_buf,
.out = &output_buf,
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.OBJECT_NAME_NOT_FOUND => return error.FileNotFound,
else => |status| return windows.unexpectedStatus(status),
}
const mount_points_struct: *const windows.MOUNTMGR_MOUNT_POINTS = @ptrCast(&output_buf[0]);
const mount_points = @as(
[*]const windows.MOUNTMGR_MOUNT_POINT,
@ptrCast(&mount_points_struct.MountPoints[0]),
)[0..mount_points_struct.NumberOfMountPoints];
for (mount_points) |mount_point| {
const symlink = @as(
[*]const u16,
@ptrCast(@alignCast(&output_buf[mount_point.SymbolicLinkNameOffset])),
)[0 .. mount_point.SymbolicLinkNameLength / 2];
// 查找 `\DosDevices\` 前缀。如果存在多个使用传统 DOS 驱动器字母的符号链接,也无需特别区分,选择第一个即可。
//
var prefix_buf = std.unicode.utf8ToUtf16LeStringLiteral("\\DosDevices\\");
const prefix = prefix_buf[0..prefix_buf.len];
if (std.mem.startsWith(u16, symlink, prefix)) {
const drive_letter = symlink[prefix.len..];
if (out_buffer.len < drive_letter.len + file_name_u16.len) return error.NameTooLong;
@memcpy(out_buffer[0..drive_letter.len], drive_letter);
@memmove(out_buffer[drive_letter.len..][0..file_name_u16.len], file_name_u16);
const total_len = drive_letter.len + file_name_u16.len;
// 验证 DOS 不包含意外的空字节。
assert(std.mem.findScalar(u16, out_buffer[0..total_len], 0) == null);
return out_buffer[0..total_len];
} else if (mountmgrIsVolumeName(symlink)) {
// 如果符号链接是类似 \??\Volume{383da0b0-717f-41b6-8c36-00500992b58d} 的卷 GUID,
// 则该卷挂载为路径,而非驱动器号。需要
// 再次查询挂载管理器,取得该卷的 DOS 路径。
// 49 是 mountmgrIsVolumeName 接受的最大长度
const vol_input_size = @sizeOf(windows.MOUNTMGR_TARGET_NAME) + (49 * 2);
var vol_input_buf: [vol_input_size]u8 align(@alignOf(windows.MOUNTMGR_TARGET_NAME)) = @splat(0);
// 注意:如果路径超过 MAX_PATH,磁盘管理图形界面不接受完整路径,
// 必须用缩短形式指定,例如 C:\FOO~1\BAR~1\<...>。
// 不过,为确保能处理任意路径长度,这里使用 PATH_MAX_WIDE。
const min_output_size = @sizeOf(windows.MOUNTMGR_VOLUME_PATHS) + (windows.PATH_MAX_WIDE * 2);
var vol_output_buf: [min_output_size]u8 align(@alignOf(windows.MOUNTMGR_VOLUME_PATHS)) = undefined;
var vol_input_struct: *windows.MOUNTMGR_TARGET_NAME = @ptrCast(&vol_input_buf[0]);
vol_input_struct.DeviceNameLength = @intCast(symlink.len * 2);
@memcpy(@as([*]windows.WCHAR, &vol_input_struct.DeviceName)[0..symlink.len], symlink);
switch ((try deviceIoControl(&.{
.file = .{ .handle = mgmt_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.MOUNTMGR.QUERY_DOS_VOLUME_PATH,
.in = &vol_input_buf,
.out = &vol_output_buf,
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.UNRECOGNIZED_VOLUME => return error.UnrecognizedVolume,
else => |status| return windows.unexpectedStatus(status),
}
const volume_paths_struct: *const windows.MOUNTMGR_VOLUME_PATHS = @ptrCast(&vol_output_buf[0]);
const volume_path = std.mem.sliceTo(@as(
[*]const u16,
&volume_paths_struct.MultiSz,
)[0 .. volume_paths_struct.MultiSzLength / 2], 0);
if (out_buffer.len < volume_path.len + file_name_u16.len) return error.NameTooLong;
// `out_buffer` 当前包含 `file_name_u16` 的内存,因此可能与
// 返回前希望放置文件名的位置重叠。可能的重叠情况如下:
//
// out_buffer: [filename]
// dest: [___(a)___] [___(b)___]
//
// 情况 (a) 需要向前复制,情况 (b) 需要
// 向后复制。还必须在复制卷路径之前执行此操作,
// 因为卷路径可能覆盖 file_name_u16 的内存。
const file_name_dest = out_buffer[volume_path.len..][0..file_name_u16.len];
@memmove(file_name_dest, file_name_u16);
@memcpy(out_buffer[0..volume_path.len], volume_path);
const total_len = volume_path.len + file_name_u16.len;
// 验证 DOS 不包含意外的空字节。
assert(std.mem.findScalar(u16, out_buffer[0..total_len], 0) == null);
return out_buffer[0..total_len];
}
}
// 如果执行到这里,说明操作系统中出现错误或损坏,因此返回错误!
//
return error.FileNotFound;
},
}
}
test GetFinalPathNameByHandle {
if (builtin.os.tag != .windows)
return;
// 任何文件均可
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const handle = tmp.dir.handle;
var buffer: [windows.PATH_MAX_WIDE]u16 = undefined;
// 使用足够大的大小进行检查
const nt_path = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Nt }, &buffer);
_ = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Dos }, &buffer);
const required_len_in_u16 = nt_path.len + @divExact(@intFromPtr(nt_path.ptr) - @intFromPtr(&buffer), 2) + 1;
// 检查容量不足的情况
try std.testing.expectError(error.NameTooLong, GetFinalPathNameByHandle(handle, .{ .volume_name = .Nt }, buffer[0 .. required_len_in_u16 - 1]));
try std.testing.expectError(error.NameTooLong, GetFinalPathNameByHandle(handle, .{ .volume_name = .Dos }, buffer[0 .. required_len_in_u16 - 1]));
// 使用刚好足够的大小进行检查
_ = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Nt }, buffer[0..required_len_in_u16]);
_ = try GetFinalPathNameByHandle(handle, .{ .volume_name = .Dos }, buffer[0..required_len_in_u16]);
}
/// 等价于 mountmgr.h 中的 MOUNTMGR_IS_VOLUME_NAME 宏
fn mountmgrIsVolumeName(name: []const u16) bool {
return (name.len == 48 or (name.len == 49 and name[48] == std.mem.nativeToLittle(u16, '\\'))) and
name[0] == std.mem.nativeToLittle(u16, '\\') and
(name[1] == std.mem.nativeToLittle(u16, '?') or name[1] == std.mem.nativeToLittle(u16, '\\')) and
name[2] == std.mem.nativeToLittle(u16, '?') and
name[3] == std.mem.nativeToLittle(u16, '\\') and
std.mem.startsWith(u16, name[4..], std.unicode.utf8ToUtf16LeStringLiteral("Volume{")) and
name[19] == std.mem.nativeToLittle(u16, '-') and
name[24] == std.mem.nativeToLittle(u16, '-') and
name[29] == std.mem.nativeToLittle(u16, '-') and
name[34] == std.mem.nativeToLittle(u16, '-') and
name[47] == std.mem.nativeToLittle(u16, '}');
}
test mountmgrIsVolumeName {
@setEvalBranchQuota(2000);
const L = std.unicode.utf8ToUtf16LeStringLiteral;
try std.testing.expect(mountmgrIsVolumeName(L("\\\\?\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}")));
try std.testing.expect(mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}")));
try std.testing.expect(mountmgrIsVolumeName(L("\\\\?\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}\\")));
try std.testing.expect(mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}\\")));
try std.testing.expect(!mountmgrIsVolumeName(L("\\\\.\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}")));
try std.testing.expect(!mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58d}\\foo")));
try std.testing.expect(!mountmgrIsVolumeName(L("\\??\\Volume{383da0b0-717f-41b6-8c36-00500992b58}")));
}
pub const QueryObjectNameError = error{
AccessDenied,
InvalidHandle,
NameTooLong,
Unexpected,
};
pub fn QueryObjectName(handle: windows.HANDLE, out_buffer: []u16) QueryObjectNameError![]u16 {
const out_buffer_aligned = std.mem.alignInSlice(out_buffer, @alignOf(windows.OBJECT.NAME_INFORMATION)) orelse return error.NameTooLong;
const info: *windows.OBJECT.NAME_INFORMATION = @ptrCast(out_buffer_aligned);
// 缓冲区大小以字节为单位指定
const out_buffer_len = std.math.cast(windows.ULONG, out_buffer_aligned.len * 2) orelse std.math.maxInt(windows.ULONG);
// 最后一个参数会返回 full_buffer 所需的长度,此处未公开。
return switch (windows.ntdll.NtQueryObject(handle, .Name, info, out_buffer_len, null)) {
.SUCCESS => {
// 文档说明,对于“未命名”对象,ObQueryNameString 返回的 info.Name 为空;
// 不确定文件句柄是否可能出现此情况
return if (info.Name.isEmpty()) error.Unexpected else info.Name.slice();
},
.ACCESS_DENIED => error.AccessDenied,
.INVALID_HANDLE => error.InvalidHandle,
// 当缓冲区不足以容纳 OBJECT_NAME_INFORMATION 对象(.INFO_LENGTH_MISMATCH),
// 或不足以容纳返回的文件路径(.BUFFER_OVERFLOW、.BUFFER_TOO_SMALL)时触发。
.INFO_LENGTH_MISMATCH, .BUFFER_OVERFLOW, .BUFFER_TOO_SMALL => error.NameTooLong,
else => |e| windows.unexpectedStatus(e),
};
}
test QueryObjectName {
if (builtin.os.tag != .windows)
return;
// 任意文件均可;规范化适用于 NTFS 联接点和符号链接,硬链接仍保留为独立路径。
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const handle = tmp.dir.handle;
var out_buffer: [windows.PATH_MAX_WIDE]u16 = undefined;
const result_path = try QueryObjectName(handle, &out_buffer);
const required_len_in_u16 = result_path.len + @divExact(@intFromPtr(result_path.ptr) - @intFromPtr(&out_buffer), 2) + 1;
// 大小不足
try std.testing.expectError(error.NameTooLong, QueryObjectName(handle, out_buffer[0 .. required_len_in_u16 - 1]));
// 恰好足够的大小
_ = try QueryObjectName(handle, out_buffer[0..required_len_in_u16]);
}
const Wtf16ToPrefixedFileWError = error{
AccessDenied,
FileNotFound,
} || Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;
const Wtf16ToPrefixedFileWOptions = struct {
allow_relative: bool = true,
};
/// 将 `path` 转换为以零结尾的 WTF16。若路径包含任意命名空间前缀,或者不是相对路径,例如根路径、驱动器相对路径等,则结果会带有 NT 风格前缀 `\??\`。
///
/// 类似 RtlDosPathNameToNtPathName_U,但有以下区别:
/// - 不进行堆分配。
/// - 相对路径保持相对形式,除非包含过多 .. 分量;此时若 `dir` 非空,则相对于它解析,否则相对于当前工作目录解析。
/// - 不会特殊处理 COM1、NUL 等特殊设备名称(TODO)。
/// - 不会移除相对路径末尾的点和空格(可能的 TODO)。
///
///
///
///
pub fn wToPrefixedFileW(dir: ?windows.HANDLE, path: [:0]const u16, options: Wtf16ToPrefixedFileWOptions) Wtf16ToPrefixedFileWError!WindowsPathSpace {
const nt_prefix = [_]u16{ '\\', '?', '?', '\\' };
if (windows.hasCommonNtPrefix(u16, path)) {
// TODO: 寻找一种 API 设计,避免 NT 的复制,因为它始终完整且原样返回。
//
var path_space: WindowsPathSpace = undefined;
path_space.data[0..nt_prefix.len].* = nt_prefix;
const len_after_prefix = path.len - nt_prefix.len;
@memcpy(path_space.data[nt_prefix.len..][0..len_after_prefix], path[nt_prefix.len..]);
path_space.len = path.len;
path_space.data[path_space.len] = 0;
return path_space;
} else {
const path_type = Dir.path.getWin32PathType(u16, path);
var path_space: WindowsPathSpace = undefined;
if (path_type == .local_device) switch (getLocalDevicePathType(u16, path)) {
.verbatim => {
path_space.data[0..nt_prefix.len].* = nt_prefix;
const len_after_prefix = path.len - nt_prefix.len;
@memcpy(path_space.data[nt_prefix.len..][0..len_after_prefix], path[nt_prefix.len..]);
path_space.len = path.len;
path_space.data[path_space.len] = 0;
return path_space;
},
.local_device, .fake_verbatim => {
const path_byte_len = windows.ntdll.RtlGetFullPathName_U(
path.ptr,
path_space.data.len * 2,
&path_space.data,
null,
);
if (path_byte_len == 0) {
// TODO: 这可能不是正确的错误
return error.BadPathName;
} else if (path_byte_len / 2 > path_space.data.len) {
return error.NameTooLong;
}
path_space.len = path_byte_len / 2;
// 两个前缀都会被规范化但保留,因此现在
// 只需将它们替换为 NT 前缀
path_space.data[0..nt_prefix.len].* = nt_prefix;
return path_space;
},
};
if (options.allow_relative and path_type == .relative) relative: {
// TODO: 处理 COM1、AUX、NUL、CONIN$、CONOUT$ 等特殊设备名称。
// 见 https://googleprojectzero.blogspot.com/2016/02/the-definitive-guide-on-win32-to-nt.html
// TODO: 考虑去掉路径末尾的所有点和空格
// 字符。RtlDosPathNameToNtPathName_U
// 和 RtlGetFullPathName_U 都会如此处理。严格而言,末尾点和空格
// 是允许的,但这种路径与 Windows 的交互可能不佳,例如
// explorer.exe 无法删除具有此类路径的文件等。
// normalizePath 或许应该执行此操作。
@memcpy(path_space.data[0..path.len], path);
// 尝试规范化;但若父目录过多,
// 则需重新开始,改用 RtlGetFullPathName_U。
path_space.len = windows.normalizePath(u16, path_space.data[0..path.len]) catch |err| switch (err) {
error.TooManyParentDirs => break :relative,
};
path_space.data[path_space.len] = 0;
return path_space;
}
// 此时已知将返回绝对 NT 路径,因此
// 可以无条件为其添加 NT 前缀。
path_space.data[0..nt_prefix.len].* = nt_prefix;
if (path_type == .root_local_device) {
// `\\.` 和 `\\?` 始终精确转换为 `\??\`,因此
// 可以在此停止
path_space.len = nt_prefix.len;
path_space.data[path_space.len] = 0;
return path_space;
}
const path_buf_offset = switch (path_type) {
// UNC 路径始终以 `\\` 开头。不过,最终希望
// 得到类似 `\??\UNC\server\share` 的路径,因此为了使
// RtlGetFullPathName 将 `server` 部分写入最终所需位置,
// 需要提供偏移量,使
// `\\` 部分写入最终 NT 路径中 `UNC\` 的 `C\`
// 所在位置。
.unc_absolute => nt_prefix.len + 2,
else => nt_prefix.len,
};
const buf_len: u32 = @intCast(path_space.data.len - path_buf_offset);
const path_to_get: [:0]const u16 = path_to_get: {
// 若 dir 为 null,则无需调用 GetFinalPathNameByHandle,因为
// RtlGetFullPathName_U 会相对于当前工作目录解析相对路径。
if (path_type != .relative or dir == null) {
break :path_to_get path;
}
// 若句柄与 Io.Dir.cwd() 返回的句柄相同,
// 也可以跳过 GetFinalPathNameByHandle
if (dir.? == Io.Dir.cwd().handle) {
break :path_to_get path;
}
// 此时已知路径是相对路径,且包含过多
// `..` 分量,normalizePath 无法解析,因此需要
// 先转换为绝对路径,再让 RtlGetFullPathName_U
// 将其规范化。具体做法是取得 `dir` 的路径,
// 再将相对路径追加到其后。
var dir_path_buf: [windows.PATH_MAX_WIDE:0]u16 = undefined;
const dir_path = GetFinalPathNameByHandle(dir.?, .{}, &dir_path_buf) catch |err| switch (err) {
// 此映射不正确:调用 GetFinalPathNameByHandle 确实可能返回 error.UnrecognizedVolume,实际环境中也观察到过这种情况。问题在于,wToPrefixedFileW 从来不应执行任何操作系统系统调用接口;它只应将字符串转换为可供 ntdll 系统调用使用的形式。
//
// 解决办法是使此函数在任何情况下都不再调用 GetFinalPathNameByHandle,或者重构调用方,使其无需调用此函数。
//
// 这可能涉及破坏性接口变更。
//
//
//
//
//
//
//
//
//
error.UnrecognizedVolume => return error.Unexpected,
else => |e| return e,
};
if (dir_path.len + 1 + path.len > windows.PATH_MAX_WIDE) {
return error.NameTooLong;
}
// 此处无需担心路径分隔符重复,因为 RtlGetFullPathName_U 会执行规范化。
//
dir_path_buf[dir_path.len] = '\\';
@memcpy(dir_path_buf[dir_path.len + 1 ..][0..path.len], path);
const full_len = dir_path.len + 1 + path.len;
dir_path_buf[full_len] = 0;
break :path_to_get dir_path_buf[0..full_len :0];
};
const path_byte_len = windows.ntdll.RtlGetFullPathName_U(
path_to_get.ptr,
buf_len * 2,
path_space.data[path_buf_offset..].ptr,
null,
);
if (path_byte_len == 0) {
// TODO: 这可能不是正确的错误
return error.BadPathName;
} else if (path_byte_len / 2 > buf_len) {
return error.NameTooLong;
}
path_space.len = path_buf_offset + (path_byte_len / 2);
if (path_type == .unc_absolute) {
// 现在添加 UNC,其中 `C` 应覆盖 FullPathName 的首个 `\`,
// 最终得到 `\??\UNC\<the rest of the path>`。
assert(path_space.data[path_buf_offset] == '\\');
assert(path_space.data[path_buf_offset + 1] == '\\');
const unc = [_]u16{ 'U', 'N', 'C' };
path_space.data[nt_prefix.len..][0..unc.len].* = unc;
}
return path_space;
}
}
const LocalDevicePathType = enum {
/// `\\.\`(路径分隔符可为 `\` 或 `/`)
local_device,
/// `\\?\`
/// 转换为 NT 路径时,前缀之后的所有内容均保持
/// 不变,`\\?\` 替换为 `\??\`。
verbatim,
/// `\\?\`,但并非所有路径分隔符都是 `\`。
/// 这似乎会被识别为前缀,但不遵循“原样”
/// 语义,即若将 `//?/C:/foo` 转换为 NT 路径,
/// 会得到 `\??\C:\foo`:路径会被规范化,//?/ 不会
/// 被视为最终路径的一部分。
fake_verbatim,
};
/// 仅与 Win32 到 NT 路径转换有关。
/// 断言 `path` 的类型为 `Dir.path.Win32PathType.local_device`。
fn getLocalDevicePathType(comptime T: type, path: []const T) LocalDevicePathType {
if (std.debug.runtime_safety) {
assert(Dir.path.getWin32PathType(T, path) == .local_device);
}
const backslash = std.mem.nativeToLittle(T, '\\');
const all_backslash = path[0] == backslash and
path[1] == backslash and
path[3] == backslash;
return switch (path[2]) {
std.mem.nativeToLittle(T, '?') => if (all_backslash) .verbatim else .fake_verbatim,
std.mem.nativeToLittle(T, '.') => .local_device,
else => unreachable,
};
}
pub const Wtf8ToPrefixedFileWError = Wtf16ToPrefixedFileWError;
/// 与 `wToPrefixedFileW` 相同,但接受 WTF-8 编码路径。
/// https://wtf-8.codeberg.page/
pub fn sliceToPrefixedFileW(dir: ?windows.HANDLE, path: []const u8, options: Wtf16ToPrefixedFileWOptions) Wtf8ToPrefixedFileWError!WindowsPathSpace {
var temp_path: WindowsPathSpace = undefined;
temp_path.len = std.unicode.wtf8ToWtf16Le(&temp_path.data, path) catch |err| switch (err) {
error.InvalidWtf8 => return error.BadPathName,
};
temp_path.data[temp_path.len] = 0;
return wToPrefixedFileW(dir, temp_path.span(), options);
}
pub const WindowsPathSpace = struct {
data: [windows.PATH_MAX_WIDE:0]u16,
len: usize,
pub fn span(wps: *const WindowsPathSpace) [:0]const u16 {
return wps.data[0..wps.len :0];
}
pub fn string(wps: *const WindowsPathSpace) windows.UNICODE_STRING {
return .init(wps.span());
}
};
fn dirRealPathFilePosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize {
if (native_os == .wasi) return error.OperationUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
if (builtin.link_libc and dir.handle == posix.AT.FDCWD) {
if (out_buffer.len < posix.PATH_MAX) return error.NameTooLong;
const syscall: Syscall = try .start();
while (true) {
if (std.c.realpath(sub_path_posix, out_buffer.ptr)) |redundant_pointer| {
syscall.finish();
assert(redundant_pointer == out_buffer.ptr);
return std.mem.findScalar(u8, out_buffer, 0) orelse out_buffer.len;
}
const err: posix.E = @fromBackingInt(@intCast(std.c._errno().*));
if (err == .INTR) {
try syscall.checkCancel();
continue;
}
syscall.finish();
switch (err) {
.INVAL => return errnoBug(err),
.BADF => return errnoBug(err),
.FAULT => return errnoBug(err),
.ACCES => return error.AccessDenied,
.NOENT => return error.FileNotFound,
.OPNOTSUPP => return error.OperationUnsupported,
.NOTDIR => return error.NotDir,
.NAMETOOLONG => return error.NameTooLong,
.LOOP => return error.SymLinkLoop,
.IO => return error.InputOutput,
else => return posix.unexpectedErrno(err),
}
}
}
var flags: posix.O = .{};
if (@hasField(posix.O, "NONBLOCK")) flags.NONBLOCK = true;
if (@hasField(posix.O, "CLOEXEC")) flags.CLOEXEC = true;
if (@hasField(posix.O, "PATH")) flags.PATH = true;
const mode: posix.mode_t = 0;
const syscall: Syscall = try .start();
const fd: posix.fd_t = while (true) {
const rc = openat_sym(dir.handle, sub_path_posix, flags, mode);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => return error.BadPathName,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.FBIG => return error.FileTooBig,
.OVERFLOW => return error.FileTooBig,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.SRCH => return error.FileNotFound, // Linux 上访问 procfs 时。
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.EXIST => return error.PathAlreadyExists,
.BUSY => return error.DeviceBusy,
.NXIO => return error.NoDevice,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
defer closeFd(fd);
return realPathPosix(fd, out_buffer);
}
const dirRealPath = switch (native_os) {
.windows => dirRealPathWindows,
else => dirRealPathPosix,
};
fn dirRealPathPosix(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize {
if (native_os == .wasi) return error.OperationUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return realPathPosix(dir.handle, out_buffer);
}
fn dirRealPathWindows(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return realPathWindows(dir.handle, out_buffer);
}
const fileRealPath = switch (native_os) {
.windows => fileRealPathWindows,
else => fileRealPathPosix,
};
fn fileRealPathWindows(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize {
if (native_os == .wasi) return error.OperationUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return realPathWindows(file.handle, out_buffer);
}
fn fileRealPathPosix(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize {
if (native_os == .wasi) return error.OperationUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return realPathPosix(file.handle, out_buffer);
}
fn realPathPosix(fd: posix.fd_t, out_buffer: []u8) File.RealPathError!usize {
if (fd == posix.AT.FDCWD) return processCurrentPathPosix(out_buffer) catch |err| switch (err) {
else => |e| return e,
error.CurrentDirUnlinked => return error.FileNotFound,
error.PathExceedsLimit => return error.NameTooLong,
};
switch (native_os) {
.dragonfly, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => {
var sufficient_buffer: [posix.PATH_MAX]u8 = undefined;
@memset(&sufficient_buffer, 0);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.fcntl(fd, posix.F.GETPATH, &sufficient_buffer))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.BADF => return error.FileNotFound,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NameTooLong,
.RANGE => return error.NameTooLong,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
const n = std.mem.findScalar(u8, &sufficient_buffer, 0) orelse sufficient_buffer.len;
if (n > out_buffer.len) return error.NameTooLong;
@memcpy(out_buffer[0..n], sufficient_buffer[0..n]);
return n;
},
.linux, .serenity, .illumos => {
var procfs_buf: ["/proc/self/path/-2147483648\x00".len]u8 = undefined;
const template = if (native_os == .illumos) "/proc/self/path/{d}" else "/proc/self/fd/{d}";
const proc_path = std.mem.printSentinel(&procfs_buf, template, .{fd}, 0) catch unreachable;
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.readlink(proc_path, out_buffer.ptr, out_buffer.len);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const len: usize = @bitCast(rc);
return len;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.FAULT => |err| return errnoBug(err),
.IO => return error.FileSystem,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.ILSEQ => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
},
.freebsd => {
var k_file: std.c.kinfo_file = undefined;
k_file.structsize = std.c.KINFO_FILE_SIZE;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(std.c.fcntl(fd, std.c.F.KINFO, @intFromPtr(&k_file)))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.BADF => {
syscall.finish();
return error.FileNotFound;
},
else => |err| {
syscall.finish();
return posix.unexpectedErrno(err);
},
}
}
const len = std.mem.findScalar(u8, &k_file.path, 0) orelse k_file.path.len;
if (len == 0) return error.NameTooLong;
@memcpy(out_buffer[0..len], k_file.path[0..len]);
return len;
},
else => return error.OperationUnsupported,
}
comptime unreachable;
}
fn fileHardLink(
userdata: ?*anyopaque,
file: File,
new_dir: Dir,
new_sub_path: []const u8,
options: File.HardLinkOptions,
) File.HardLinkError!void {
_ = userdata;
if (native_os != .linux) return error.OperationUnsupported;
var new_path_buffer: [posix.PATH_MAX]u8 = undefined;
const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);
const flags: u32 = if (options.follow_symlinks)
posix.AT.SYMLINK_FOLLOW | posix.AT.EMPTY_PATH
else
posix.AT.EMPTY_PATH;
return linkat(file.handle, "", new_dir.handle, new_sub_path_posix, flags) catch |err| switch (err) {
error.FileNotFound => {
if (options.follow_symlinks) return error.FileNotFound;
var proc_buf: ["/proc/self/fd/-2147483648\x00".len]u8 = undefined;
const proc_path = std.mem.printSentinel(&proc_buf, "/proc/self/fd/{d}", .{file.handle}, 0) catch
unreachable;
return linkat(posix.AT.FDCWD, proc_path, new_dir.handle, new_sub_path_posix, posix.AT.SYMLINK_FOLLOW);
},
else => |e| return e,
};
}
fn linkat(
old_dir: posix.fd_t,
old_path: [*:0]const u8,
new_dir: posix.fd_t,
new_path: [*:0]const u8,
flags: u32,
) File.HardLinkError!void {
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.linkat(old_dir, old_path, new_dir, new_path, flags))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.DQUOT => return syscall.fail(error.DiskQuota),
.EXIST => return syscall.fail(error.PathAlreadyExists),
.IO => return syscall.fail(error.HardwareFailure),
.LOOP => return syscall.fail(error.SymLinkLoop),
.MLINK => return syscall.fail(error.LinkQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NOENT => return syscall.fail(error.FileNotFound),
.NOMEM => return syscall.fail(error.SystemResources),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.NOTDIR => return syscall.fail(error.NotDir),
.PERM => return syscall.fail(error.PermissionDenied),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
.XDEV => return syscall.fail(error.CrossDevice),
.ILSEQ => return syscall.fail(error.BadPathName),
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
const dirDeleteFile = switch (native_os) {
.windows => dirDeleteFileWindows,
.wasi => dirDeleteFileWasi,
else => dirDeleteFilePosix,
};
fn dirDeleteFileWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void {
return dirDeleteWindows(userdata, dir, sub_path, false) catch |err| switch (err) {
error.DirNotEmpty => unreachable,
else => |e| return e,
};
}
fn dirDeleteFileWasi(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void {
if (builtin.link_libc) return dirDeleteFilePosix(userdata, dir, sub_path);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const wasi = std.os.wasi;
const syscall: Syscall = try .start();
while (true) {
const res = wasi.path_unlink_file(dir.handle, sub_path.ptr, sub_path.len);
switch (res) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES, .PERM => |e| {
const original_error: Dir.DeleteFileError = switch (e) {
.ACCES => error.AccessDenied,
.PERM => error.PermissionDenied,
else => unreachable,
};
var stat: wasi.filestat_t = undefined;
while (true) {
try syscall.checkCancel();
switch (wasi.path_filestat_get(dir.handle, .{}, sub_path.ptr, sub_path.len, &stat)) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => continue,
else => {
syscall.finish();
return original_error;
},
}
}
if (stat.filetype == .DIRECTORY)
return error.IsDir
else
return original_error;
},
else => |e| {
syscall.finish();
switch (e) {
.BUSY => return error.FileBusy,
.FAULT => |err| return errnoBug(err),
.IO => return error.FileSystem,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.ROFS => return error.ReadOnlyFileSystem,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
.INVAL => |err| return errnoBug(err), // 标志无效,或路径名的最后一个分量为 .
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirDeleteFilePosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.unlinkat(dir.handle, sub_path_posix, 0))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
// 某些系统在尝试删除目录时返回权限错误,因此需要专门处理该情况并转换错误。
//
//
.PERM => switch (native_os) {
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .freebsd, .netbsd, .dragonfly, .openbsd, .illumos => {
// 不要跟随符号链接,以匹配 unlinkat 的行为(unlinkat 操作符号链接本身而不跟随它们)。
var st = std.mem.zeroes(posix.Stat);
while (true) {
try syscall.checkCancel();
switch (posix.errno(fstatat_sym(dir.handle, sub_path_posix, &st, posix.AT.SYMLINK_NOFOLLOW))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => continue,
else => {
syscall.finish();
return error.PermissionDenied;
},
}
}
const is_dir = st.mode & posix.S.IFMT == posix.S.IFDIR;
if (is_dir)
return error.IsDir
else
return error.PermissionDenied;
},
else => {
syscall.finish();
return error.PermissionDenied;
},
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.BUSY => return error.FileBusy,
.FAULT => |err| return errnoBug(err),
.IO => return error.FileSystem,
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.ROFS => return error.ReadOnlyFileSystem,
.EXIST => |err| return errnoBug(err),
.NOTEMPTY => |err| return errnoBug(err), // 未传入 AT.REMOVEDIR
.ILSEQ => return error.BadPathName,
.INVAL => |err| return errnoBug(err), // 标志无效,或路径名的最后一个分量为 .
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const dirDeleteDir = switch (native_os) {
.windows => dirDeleteDirWindows,
.wasi => dirDeleteDirWasi,
else => dirDeleteDirPosix,
};
fn dirDeleteDirWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void {
return dirDeleteWindows(userdata, dir, sub_path, true) catch |err| switch (err) {
error.IsDir => unreachable,
else => |e| return e,
};
}
fn dirDeleteWindows(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, remove_dir: bool) (Dir.DeleteDirError || Dir.DeleteFileError)!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const w = windows;
if (std.mem.eql(u8, sub_path, "..")) {
// 存在打开的句柄时,无法移除父目录。
return error.FileBusy;
}
var sub_path_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
if (std.mem.eql(u8, sub_path, ".")) {
// Windows 不识别此项,但它对空字符串有效。
sub_path_w.len = 0;
}
const attr: w.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w.span())) null else dir.handle,
.ObjectName = @constCast(&sub_path_w.string()),
};
var io_status_block: w.IO_STATUS_BLOCK = undefined;
var tmp_handle: w.HANDLE = undefined;
{
const syscall: Syscall = try .start();
while (true) switch (w.ntdll.NtCreateFile(
&tmp_handle,
.{ .STANDARD = .{
.RIGHTS = .{ .DELETE = true },
.SYNCHRONIZE = true,
} },
&attr,
&io_status_block,
null,
.{},
.VALID_FLAGS,
.OPEN,
.{
.DIRECTORY_FILE = remove_dir,
.IO = .SYNCHRONOUS_NONALERT,
.NON_DIRECTORY_FILE = !remove_dir,
.OPEN_REPARSE_POINT = true, // 是否可能需要改为删除目标?
},
null,
0,
)) {
.SUCCESS => break syscall.finish(),
.OBJECT_NAME_INVALID => |err| return syscall.ntstatusBug(err),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.BAD_NETWORK_PATH => return syscall.fail(error.NetworkNotFound), // 未找到 \\server
.BAD_NETWORK_NAME => return syscall.fail(error.NetworkNotFound), // 找到 \\server,但未找到 \\server\share
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.FILE_IS_A_DIRECTORY => return syscall.fail(error.IsDir),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.SHARING_VIOLATION => return syscall.fail(error.FileBusy),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.DELETE_PENDING => return syscall.finish(),
else => |rc| return syscall.unexpectedNtstatus(rc),
};
}
defer w.CloseHandle(tmp_handle);
// FileDispositionInformationEx 各功能的支持条件不同:
// - FILE_DISPOSITION_INFORMATION_EX 要求 >= win10_rs1。
// 不支持时返回 INVALID_INFO_CLASS。
// - 要求 NTFS 文件系统。
// FAT32 等文件系统返回 INVALID_PARAMETER。
// - FILE_DISPOSITION_POSIX_SEMANTICS 要求 >= win10_rs1。
// - FILE_DISPOSITION_IGNORE_READONLY_ATTRIBUTE 要求 >= win10_rs5。
// 不支持某标志时返回 NOT_SUPPORTED。
//
// 此处策略是先尝试 FileDispositionInformationEx;若返回值
// 表明某部分不受支持,则回退到 FileDispositionInformation。
const rc = rc: {
// 若文件系统支持,则使用 posix 语义删除。
var info: w.FILE.DISPOSITION.INFORMATION.EX = .{ .Flags = .{
.DELETE = true,
.POSIX_SEMANTICS = true,
.IGNORE_READONLY_ATTRIBUTE = true,
} };
const syscall: Syscall = try .start();
while (true) switch (w.ntdll.NtSetInformationFile(
tmp_handle,
&io_status_block,
&info,
@sizeOf(w.FILE.DISPOSITION.INFORMATION.EX),
.DispositionEx,
)) {
.CANCELLED => {
try syscall.checkCancel();
continue;
},
// 文件系统不支持 FileDispositionInformationEx
.INVALID_PARAMETER,
// 操作系统不支持 FileDispositionInformationEx
.INVALID_INFO_CLASS,
// 操作系统不支持其中一个标志
.NOT_SUPPORTED,
=> break, // 使用下方回退路径;`syscall` 仍处于活动状态。
// 对于其他所有状态,继续由下面的 switch 处理。
else => |rc| {
syscall.finish();
break :rc rc;
},
};
// 具有文件待删除语义的删除操作,需要等待或移动
// 文件才能使其从此处移除。
var file_dispo: w.FILE.DISPOSITION.INFORMATION = .{ .DeleteFile = .TRUE };
while (true) switch (w.ntdll.NtSetInformationFile(
tmp_handle,
&io_status_block,
&file_dispo,
@sizeOf(w.FILE.DISPOSITION.INFORMATION),
.Disposition,
)) {
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |rc| {
syscall.finish();
break :rc rc;
},
};
};
switch (rc) {
.SUCCESS => {},
.DIRECTORY_NOT_EMPTY => return error.DirNotEmpty,
.INVALID_PARAMETER => |err| return w.statusBug(err),
.CANNOT_DELETE => return error.AccessDenied,
.MEDIA_WRITE_PROTECTED => return error.AccessDenied,
.ACCESS_DENIED => return error.AccessDenied,
else => return w.unexpectedStatus(rc),
}
}
fn dirDeleteDirWasi(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void {
if (builtin.link_libc) return dirDeleteDirPosix(userdata, dir, sub_path);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
const res = std.os.wasi.path_remove_directory(dir.handle, sub_path.ptr, sub_path.len);
switch (res) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.BUSY => return error.FileBusy,
.FAULT => |err| return errnoBug(err),
.IO => return error.FileSystem,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.ROFS => return error.ReadOnlyFileSystem,
.NOTEMPTY => return error.DirNotEmpty,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
.INVAL => |err| return errnoBug(err), // 标志无效,或路径名的最后一个分量为 .
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirDeleteDirPosix(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.unlinkat(dir.handle, sub_path_posix, posix.AT.REMOVEDIR))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.BUSY => return error.FileBusy,
.FAULT => |err| return errnoBug(err),
.IO => return error.FileSystem,
.ISDIR => |err| return errnoBug(err),
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.ROFS => return error.ReadOnlyFileSystem,
.EXIST => |err| return errnoBug(err),
.NOTEMPTY => return error.DirNotEmpty,
.ILSEQ => return error.BadPathName,
.INVAL => |err| return errnoBug(err), // 标志无效,或路径名的最后一个分量为 .
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const dirRename = switch (native_os) {
.windows => dirRenameWindows,
.wasi => dirRenameWasi,
else => dirRenamePosix,
};
fn dirRenameWindows(
userdata: ?*anyopaque,
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
) Dir.RenameError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return dirRenameWindowsInner(old_dir, old_sub_path, new_dir, new_sub_path, true) catch |err| switch (err) {
error.PathAlreadyExists => return error.Unexpected,
error.OperationUnsupported => return error.Unexpected,
else => |e| return e,
};
}
fn dirRenamePreserve(
userdata: ?*anyopaque,
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
) Dir.RenamePreserveError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (is_windows) return dirRenameWindowsInner(old_dir, old_sub_path, new_dir, new_sub_path, false);
if (is_darwin) return dirRenamePreserveDarwin(old_dir, old_sub_path, new_dir, new_sub_path);
if (native_os == .linux) return dirRenamePreserveLinux(old_dir, old_sub_path, new_dir, new_sub_path);
// 创建硬链接,然后删除原文件。
try dirHardLink(t, old_dir, old_sub_path, new_dir, new_sub_path, .{ .follow_symlinks = false });
const prev = swapCancelProtection(t, .blocked);
defer _ = swapCancelProtection(t, prev);
dirDeleteFile(t, old_dir, old_sub_path) catch {};
}
fn dirRenameWindowsInner(
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
replace_if_exists: bool,
) Dir.RenamePreserveError!void {
const w = windows;
const old_path_w_buf = try sliceToPrefixedFileW(old_dir.handle, old_sub_path, .{});
const old_path_w = old_path_w_buf.span();
const new_path_w_buf = try sliceToPrefixedFileW(new_dir.handle, new_sub_path, .{});
const new_path_w = new_path_w_buf.span();
const src_fd = src_fd: {
if (OpenFile(old_path_w, .{
.dir = old_dir.handle,
.access_mask = .{
.GENERIC = .{ .WRITE = true },
.STANDARD = .{
.RIGHTS = .{ .DELETE = true },
.SYNCHRONIZE = true,
},
},
.creation = .OPEN,
.filter = .any, // 此函数应同时支持重命名文件和目录。
.follow_symlinks = false,
})) |handle| {
break :src_fd handle;
} else |err| switch (err) {
error.WouldBlock => unreachable, // 未设置 `.share_access_nonblocking = true` 时不可能发生。
else => |e| return e,
}
};
defer w.CloseHandle(src_fd);
var rc: w.NTSTATUS = undefined;
var attempt: u5 = 0;
// FileRenameInformationEx 的不同功能支持条件不同:
// - FILE_RENAME_INFORMATION_EX 要求 >= win10_rs1
// (不支持时返回 INVALID_INFO_CLASS)
// - 要求 NTFS 文件系统
// (在 FAT32 等文件系统上返回 INVALID_PARAMETER)
// - FILE_RENAME_POSIX_SEMANTICS 要求 >= win10_rs1
// - FILE_RENAME_IGNORE_READONLY_ATTRIBUTE 要求 >= win10_rs5
// (不支持某个标志时返回 NOT_SUPPORTED)
//
// 此处的策略是先尝试使用 FileRenameInformationEx;若返回值表明
// 其中某项功能不受支持,则回退到 FileRenameInformation。
const need_fallback = need_fallback: {
var rename_info: w.FILE.RENAME_INFORMATION = .init(.{
.Flags = .{
.REPLACE_IF_EXISTS = replace_if_exists,
.POSIX_SEMANTICS = true,
.IGNORE_READONLY_ATTRIBUTE = true,
},
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(new_path_w)) null else new_dir.handle,
.FileName = new_path_w,
});
var io_status_block: w.IO_STATUS_BLOCK = undefined;
const rename_info_buf = rename_info.toBuffer();
var syscall: Syscall = try .start();
while (true) {
rc = w.ntdll.NtSetInformationFile(
src_fd,
&io_status_block,
rename_info_buf.ptr,
@intCast(rename_info_buf.len),
.RenameEx,
);
switch (rc) {
// 对于其他所有状态,继续由下面的 switch 处理。
else => {
syscall.finish();
break :need_fallback false;
},
.CANCELLED => try syscall.checkCancel(),
// 文件系统不支持 FileDispositionInformationEx
.INVALID_PARAMETER,
// 操作系统不支持 FileDispositionInformationEx
.INVALID_INFO_CLASS,
// 操作系统不支持其中一个标志
.NOT_SUPPORTED,
=> {
syscall.finish();
break :need_fallback true;
},
.ACCESS_DENIED => {
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) break :need_fallback false;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
},
}
}
};
if (need_fallback) {
var rename_info: w.FILE.RENAME_INFORMATION = .init(.{
.Flags = .{ .REPLACE_IF_EXISTS = replace_if_exists },
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(new_path_w)) null else new_dir.handle,
.FileName = new_path_w,
});
var io_status_block: w.IO_STATUS_BLOCK = undefined;
const rename_info_buf = rename_info.toBuffer();
var syscall: Syscall = try .start();
while (true) {
rc = w.ntdll.NtSetInformationFile(
src_fd,
&io_status_block,
rename_info_buf.ptr,
@intCast(rename_info_buf.len),
.Rename,
);
switch (rc) {
else => {
syscall.finish();
break;
},
.CANCELLED => try syscall.checkCancel(),
.ACCESS_DENIED => {
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) break;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
},
}
}
}
switch (rc) {
.SUCCESS => {},
.INVALID_HANDLE => |err| return w.statusBug(err),
.INVALID_PARAMETER => |err| return w.statusBug(err),
.OBJECT_PATH_SYNTAX_BAD => |err| return w.statusBug(err),
.ACCESS_DENIED => return error.AccessDenied,
.OBJECT_NAME_NOT_FOUND => return error.FileNotFound,
.OBJECT_PATH_NOT_FOUND => return error.FileNotFound,
.NOT_SAME_DEVICE => return error.CrossDevice,
.OBJECT_NAME_COLLISION => return error.PathAlreadyExists,
.DIRECTORY_NOT_EMPTY => return error.DirNotEmpty,
.FILE_IS_A_DIRECTORY => return error.IsDir,
.NOT_A_DIRECTORY => return error.NotDir,
else => return w.unexpectedStatus(rc),
}
}
fn dirRenameWasi(
userdata: ?*anyopaque,
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
) Dir.RenameError!void {
if (builtin.link_libc) return dirRenamePosix(userdata, old_dir, old_sub_path, new_dir, new_sub_path);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.path_rename(old_dir.handle, old_sub_path.ptr, old_sub_path.len, new_dir.handle, new_sub_path.ptr, new_sub_path.len)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.BUSY => return error.FileBusy,
.DQUOT => return error.DiskQuota,
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ISDIR => return error.IsDir,
.LOOP => return error.SymLinkLoop,
.MLINK => return error.LinkQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.EXIST => return error.DirNotEmpty,
.NOTEMPTY => return error.DirNotEmpty,
.ROFS => return error.ReadOnlyFileSystem,
.XDEV => return error.CrossDevice,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirRenamePosix(
userdata: ?*anyopaque,
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
) Dir.RenameError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var old_path_buffer: [posix.PATH_MAX]u8 = undefined;
var new_path_buffer: [posix.PATH_MAX]u8 = undefined;
const old_sub_path_posix = try pathToPosix(old_sub_path, &old_path_buffer);
const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);
return renameat(old_dir.handle, old_sub_path_posix, new_dir.handle, new_sub_path_posix);
}
fn dirRenamePreserveDarwin(
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
) Dir.RenamePreserveError!void {
var old_path_buffer: [posix.PATH_MAX]u8 = undefined;
var new_path_buffer: [posix.PATH_MAX]u8 = undefined;
const old_sub_path_posix = try pathToPosix(old_sub_path, &old_path_buffer);
const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(std.c.renameatx_np(
old_dir.handle,
old_sub_path_posix,
new_dir.handle,
new_sub_path_posix,
.{ .EXCL = true },
))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.BADF => |err| return syscall.errnoBug(err),
.ISDIR => |err| return syscall.errnoBug(err),
.NOTEMPTY => |err| return syscall.errnoBug(err),
.OPNOTSUPP => return syscall.fail(error.OperationUnsupported),
.IO => return syscall.fail(error.HardwareFailure),
.DEADLK => return syscall.fail(error.AccessDenied),
.ACCES => return syscall.fail(error.AccessDenied),
.DQUOT => return syscall.fail(error.DiskQuota),
.EXIST => return syscall.fail(error.PathAlreadyExists),
.LOOP => return syscall.fail(error.LinkQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NOENT => return syscall.fail(error.FileNotFound),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.NOTDIR => return syscall.fail(error.NotDir),
.PERM => return syscall.fail(error.PermissionDenied),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
.XDEV => return syscall.fail(error.CrossDevice),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn dirRenamePreserveLinux(
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
) Dir.RenamePreserveError!void {
const linux = std.os.linux;
var old_path_buffer: [linux.PATH_MAX]u8 = undefined;
var new_path_buffer: [linux.PATH_MAX]u8 = undefined;
const old_sub_path_posix = try pathToPosix(old_sub_path, &old_path_buffer);
const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);
const syscall: Syscall = try .start();
while (true) switch (linux.errno(linux.renameat2(
old_dir.handle,
old_sub_path_posix,
new_dir.handle,
new_sub_path_posix,
.{ .NOREPLACE = true },
))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.PERM => return syscall.fail(error.PermissionDenied),
.BUSY => return syscall.fail(error.FileBusy),
.DQUOT => return syscall.fail(error.DiskQuota),
.ISDIR => return syscall.fail(error.IsDir),
.LOOP => return syscall.fail(error.SymLinkLoop),
.MLINK => return syscall.fail(error.LinkQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NOENT => return syscall.fail(error.FileNotFound),
.NOTDIR => return syscall.fail(error.NotDir),
.NOMEM => return syscall.fail(error.SystemResources),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.EXIST => return syscall.fail(error.PathAlreadyExists),
.NOTEMPTY => return syscall.fail(error.DirNotEmpty),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
.XDEV => return syscall.fail(error.CrossDevice),
.ILSEQ => return syscall.fail(error.BadPathName),
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
};
}
fn renameat(
old_dir: posix.fd_t,
old_sub_path: [*:0]const u8,
new_dir: posix.fd_t,
new_sub_path: [*:0]const u8,
) Dir.RenameError!void {
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.renameat(old_dir, old_sub_path, new_dir, new_sub_path))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.PERM => return syscall.fail(error.PermissionDenied),
.BUSY => return syscall.fail(error.FileBusy),
.DQUOT => return syscall.fail(error.DiskQuota),
.ISDIR => return syscall.fail(error.IsDir),
.IO => return syscall.fail(error.HardwareFailure),
.LOOP => return syscall.fail(error.SymLinkLoop),
.MLINK => return syscall.fail(error.LinkQuotaExceeded),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NOENT => return syscall.fail(error.FileNotFound),
.NOTDIR => return syscall.fail(error.NotDir),
.NOMEM => return syscall.fail(error.SystemResources),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.EXIST => return syscall.fail(error.DirNotEmpty),
.NOTEMPTY => return syscall.fail(error.DirNotEmpty),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
.XDEV => return syscall.fail(error.CrossDevice),
.ILSEQ => return syscall.fail(error.BadPathName),
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
};
}
const dirSymLink = switch (native_os) {
.windows => dirSymLinkWindows,
.wasi => dirSymLinkWasi,
else => dirSymLinkPosix,
};
fn dirSymLinkWindows(
userdata: ?*anyopaque,
dir: Dir,
target_path: []const u8,
sym_link_path: []const u8,
flags: Dir.SymLinkFlags,
) Dir.SymLinkError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const w = windows;
// 目标路径不使用 sliceToPrefixedFileW,因为某些路径在创建符号链接时
// 与转换为 NT 命名空间路径时的处理方式不同。
//
var target_path_w: WindowsPathSpace = undefined;
target_path_w.len = try w.wtf8ToWtf16Le(&target_path_w.data, target_path);
target_path_w.data[target_path_w.len] = 0;
// 不过,需要将所有路径分隔符规范化为 `\`,因为
// 目标路径为相对路径时,必须使用 `\` 作为路径分隔符。
std.mem.replaceScalar(
u16,
target_path_w.data[0..target_path_w.len],
std.mem.nativeToLittle(u16, '/'),
std.mem.nativeToLittle(u16, '\\'),
);
const sym_link_path_w = try sliceToPrefixedFileW(dir.handle, sym_link_path, .{});
const SYMLINK_DATA = extern struct {
ReparseTag: w.IO_REPARSE_TAG,
ReparseDataLength: w.USHORT,
Reserved: w.USHORT,
SubstituteNameOffset: w.USHORT,
SubstituteNameLength: w.USHORT,
PrintNameOffset: w.USHORT,
PrintNameLength: w.USHORT,
Flags: w.ULONG,
};
const symlink_handle = handle: {
if (OpenFile(sym_link_path_w.span(), .{
.access_mask = .{
.GENERIC = .{ .READ = true, .WRITE = true },
.STANDARD = .{ .SYNCHRONIZE = true },
},
.dir = dir.handle,
.creation = .CREATE,
.filter = if (flags.is_directory) .dir_only else .non_directory_only,
})) |handle| {
break :handle handle;
} else |err| switch (err) {
error.IsDir => return error.PathAlreadyExists,
error.NotDir => return error.Unexpected,
error.WouldBlock => return error.Unexpected,
error.PipeBusy => return error.Unexpected,
error.FileBusy => return error.Unexpected,
error.NoDevice => return error.Unexpected,
error.AntivirusInterference => return error.Unexpected,
else => |e| return e,
}
};
defer w.CloseHandle(symlink_handle);
// 文档中的相关部分:
// > 相对链接按以下约定指定:
// > - 相对于根目录:例如,"\Windows\System32" 解析为 "current drive:\Windows\System32"。
// > - 相对于当前工作目录:例如,如果当前工作目录为
// > C:\Windows\System32,则 "C:File.txt" 解析为 "C:\Windows\System32\File.txt"。
// > 注意:如果指定相对于当前工作目录的链接,则实际创建的是绝对
// > 链接,因为当前工作目录是依据用户和线程进行处理的。
// https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw
var is_target_absolute = false;
const final_target_path = target_path: {
if (w.hasCommonNtPrefix(u16, target_path_w.span())) {
// 已经是 NT 路径,无需处理
break :target_path target_path_w.span();
} else {
switch (Dir.path.getWin32PathType(u16, target_path_w.span())) {
// 带根路径需要避免经过 wToPrefixedFileW
// 处理,在此上下文中会将其视为相对路径。
// 注意:符号链接中的带根路径似乎是相对于
// 符号链接所在驱动器,而非当前工作目录所在驱动器。
// 因此,如果符号链接位于 C:\,当前工作目录位于 D:\,
// 该路径仍会相对于
// C:\ 驱动器的根目录解析。
.rooted => break :target_path target_path_w.span(),
// 保留相对路径的相对形式,其余路径都需要添加 NT 前缀。
else => if (!Dir.path.isAbsoluteWindowsWtf16(target_path_w.span()))
break :target_path target_path_w.span(),
}
}
var prefixed_target_path = try wToPrefixedFileW(dir.handle, target_path_w.span(), .{});
// 在添加前缀后执行此操作,以确保将驱动器相对路径视为绝对路径
is_target_absolute = Dir.path.isAbsoluteWindowsWtf16(prefixed_target_path.span());
break :target_path prefixed_target_path.span();
};
// 准备重解析数据缓冲区
var buffer: [w.MAXIMUM_REPARSE_DATA_BUFFER_SIZE]u8 = undefined;
const buf_len = @sizeOf(SYMLINK_DATA) + final_target_path.len * 4;
const header_len = @sizeOf(w.ULONG) + @sizeOf(w.USHORT) * 2;
const target_is_absolute = Dir.path.isAbsoluteWindowsWtf16(final_target_path);
const symlink_data: SYMLINK_DATA = .{
.ReparseTag = .SYMLINK,
.ReparseDataLength = @intCast(buf_len - header_len),
.Reserved = 0,
.SubstituteNameOffset = @intCast(final_target_path.len * 2),
.SubstituteNameLength = @intCast(final_target_path.len * 2),
.PrintNameOffset = 0,
.PrintNameLength = @intCast(final_target_path.len * 2),
.Flags = if (!target_is_absolute) w.SYMLINK_FLAG_RELATIVE else 0,
};
@memcpy(buffer[0..@sizeOf(SYMLINK_DATA)], std.mem.asBytes(&symlink_data));
@memcpy(buffer[@sizeOf(SYMLINK_DATA)..][0 .. final_target_path.len * 2], @as([*]const u8, @ptrCast(final_target_path)));
const paths_start = @sizeOf(SYMLINK_DATA) + final_target_path.len * 2;
@memcpy(buffer[paths_start..][0 .. final_target_path.len * 2], @as([*]const u8, @ptrCast(final_target_path)));
switch ((try deviceIoControl(&.{
.file = .{ .handle = symlink_handle, .flags = .{ .nonblocking = false } },
.code = .SET_REPARSE_POINT,
.in = buffer[0..buf_len],
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.PRIVILEGE_NOT_HELD => return error.PermissionDenied,
.ACCESS_DENIED => return error.AccessDenied,
.INVALID_DEVICE_REQUEST => return error.FileSystem,
else => |status| return w.unexpectedStatus(status),
}
}
fn dirSymLinkWasi(
userdata: ?*anyopaque,
dir: Dir,
target_path: []const u8,
sym_link_path: []const u8,
flags: Dir.SymLinkFlags,
) Dir.SymLinkError!void {
if (builtin.link_libc) return dirSymLinkPosix(userdata, dir, target_path, sym_link_path, flags);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.path_symlink(target_path.ptr, target_path.len, dir.handle, sym_link_path.ptr, sym_link_path.len)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.DQUOT => return error.DiskQuota,
.EXIST => return error.PathAlreadyExists,
.IO => return error.FileSystem,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.ROFS => return error.ReadOnlyFileSystem,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirSymLinkPosix(
userdata: ?*anyopaque,
dir: Dir,
target_path: []const u8,
sym_link_path: []const u8,
flags: Dir.SymLinkFlags,
) Dir.SymLinkError!void {
_ = flags;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var target_path_buffer: [posix.PATH_MAX]u8 = undefined;
var sym_link_path_buffer: [posix.PATH_MAX]u8 = undefined;
const target_path_posix = try pathToPosix(target_path, &target_path_buffer);
const sym_link_path_posix = try pathToPosix(sym_link_path, &sym_link_path_buffer);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.symlinkat(target_path_posix, dir.handle, sym_link_path_posix))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.DQUOT => return error.DiskQuota,
.EXIST => return error.PathAlreadyExists,
.IO => return error.FileSystem,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.ROFS => return error.ReadOnlyFileSystem,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirReadLink(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
switch (native_os) {
.windows => return dirReadLinkWindows(dir, sub_path, buffer),
.wasi => return dirReadLinkWasi(dir, sub_path, buffer),
else => return dirReadLinkPosix(dir, sub_path, buffer),
}
}
fn dirReadLinkWindows(dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize {
// 此缓冲区先用于 `sub_path`,之后临时复用一次,
// 最后再转换回 `buffer`。
var sub_path_w = try sliceToPrefixedFileW(dir.handle, sub_path, .{});
const attr: windows.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w.span())) null else dir.handle,
.ObjectName = @constCast(&sub_path_w.string()),
};
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var result_handle: windows.HANDLE = undefined;
var attempt: u5 = 0;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtCreateFile(
&result_handle,
.{
.SPECIFIC = .{ .FILE = .{
.READ_ATTRIBUTES = true,
} },
.STANDARD = .{ .SYNCHRONIZE = true },
},
&attr,
&io_status_block,
null,
.{ .NORMAL = true },
.VALID_FLAGS,
.OPEN,
.{
.DIRECTORY_FILE = false,
.NON_DIRECTORY_FILE = false,
.IO = .SYNCHRONOUS_NONALERT,
.OPEN_REPARSE_POINT = true,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
break;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.SHARING_VIOLATION => {
// 尝试打开正在运行的可执行文件时会发生此错误。
// 但存在内核缺陷:可执行文件关闭后,在长短不确定的一段时间内仍可能错误返回此错误。
// 这里通过重试规避该内核缺陷。
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.DELETE_PENDING => {
// 此错误表示文件系统中此位置*曾经*存在
// 文件,但它已被删除。然而,操作系统尚未
// 完成删除操作,因此此 CreateFile
// 调用失败。此处通过休眠并重试,
// 直到错误消失,来模拟内核缺陷已被修复时的行为。
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.BAD_NETWORK_PATH => return syscall.fail(error.NetworkNotFound), // 未找到 \\server
.BAD_NETWORK_NAME => return syscall.fail(error.NetworkNotFound), // 找到 \\server,但未找到 \\server\share
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.FileNotFound),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_BUSY => return syscall.fail(error.AccessDenied),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.FileNotFound),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
.VIRUS_INFECTED, .VIRUS_DELETED => return syscall.fail(error.AntivirusInterference),
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.OBJECT_PATH_SYNTAX_BAD => |status| return syscall.ntstatusBug(status),
.INVALID_HANDLE => |status| return syscall.ntstatusBug(status),
else => |status| return syscall.unexpectedNtstatus(status),
};
defer windows.CloseHandle(result_handle);
var reparse_buf: [windows.MAXIMUM_REPARSE_DATA_BUFFER_SIZE]u8 align(@alignOf(windows.REPARSE_DATA_BUFFER)) = undefined;
switch ((try deviceIoControl(&.{
.file = .{ .handle = result_handle, .flags = .{ .nonblocking = false } },
.code = .GET_REPARSE_POINT,
.out = &reparse_buf,
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.NOT_A_REPARSE_POINT => return error.NotLink,
else => |status| return windows.unexpectedStatus(status),
}
const reparse_struct: *const windows.REPARSE_DATA_BUFFER = @ptrCast(@alignCast(&reparse_buf));
const IoReparseTagInt = @typeInfo(windows.IO_REPARSE_TAG).@"struct".backing_integer.?;
const result_w = switch (@as(IoReparseTagInt, @bitCast(reparse_struct.ReparseTag))) {
@as(IoReparseTagInt, @bitCast(windows.IO_REPARSE_TAG.SYMLINK)) => r: {
const buf: *const windows.SYMBOLIC_LINK_REPARSE_BUFFER = @ptrCast(@alignCast(&reparse_struct.DataBuffer[0]));
const offset = buf.SubstituteNameOffset >> 1;
const len = buf.SubstituteNameLength >> 1;
const path_buf = @as([*]const u16, &buf.PathBuffer);
const is_relative = buf.Flags & windows.SYMLINK_FLAG_RELATIVE != 0;
break :r try parseReadLinkPath(path_buf[offset..][0..len], is_relative, &sub_path_w.data);
},
@as(IoReparseTagInt, @bitCast(windows.IO_REPARSE_TAG.MOUNT_POINT)) => r: {
const buf: *const windows.MOUNT_POINT_REPARSE_BUFFER = @ptrCast(@alignCast(&reparse_struct.DataBuffer[0]));
const offset = buf.SubstituteNameOffset >> 1;
const len = buf.SubstituteNameLength >> 1;
const path_buf = @as([*]const u16, &buf.PathBuffer);
break :r try parseReadLinkPath(path_buf[offset..][0..len], false, &sub_path_w.data);
},
else => return error.UnsupportedReparsePointType,
};
const len = std.unicode.calcWtf8Len(result_w);
if (len > buffer.len) return error.NameTooLong;
return std.unicode.wtf16LeToWtf8(buffer, result_w);
}
fn parseReadLinkPath(path: []const u16, is_relative: bool, out_buffer: []u16) error{NameTooLong}![]u16 {
path: {
if (is_relative) break :path;
return windows.ntToWin32Namespace(path, out_buffer) catch |err| switch (err) {
error.NameTooLong => |e| return e,
error.NotNtPath => break :path,
};
}
if (out_buffer.len < path.len) return error.NameTooLong;
const dest = out_buffer[0..path.len];
@memcpy(dest, path);
return dest;
}
fn dirReadLinkWasi(dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize {
if (builtin.link_libc) return dirReadLinkPosix(dir, sub_path, buffer);
var n: usize = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.path_readlink(dir.handle, sub_path.ptr, sub_path.len, buffer.ptr, buffer.len, &n)) {
.SUCCESS => {
syscall.finish();
return n;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.FAULT => |err| return errnoBug(err),
.INVAL => return error.NotLink,
.IO => return error.FileSystem,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirReadLinkPosix(dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize {
var sub_path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &sub_path_buffer);
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.readlinkat(dir.handle, sub_path_posix, buffer.ptr, buffer.len);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const len: usize = @bitCast(rc);
return len;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.FAULT => |err| return errnoBug(err),
.INVAL => return error.NotLink,
.IO => return error.FileSystem,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const dirSetPermissions = switch (native_os) {
.windows => dirSetPermissionsWindows,
else => dirSetPermissionsPosix,
};
fn dirSetPermissionsWindows(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
_ = dir;
_ = permissions;
@panic("TODO implement dirSetPermissionsWindows");
}
fn dirSetPermissionsPosix(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void {
if (@sizeOf(Dir.Permissions) == 0) return;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return setPermissionsPosix(dir.handle, permissions.toMode());
}
fn dirSetFilePermissions(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
permissions: Dir.Permissions,
options: Dir.SetFilePermissionsOptions,
) Dir.SetFilePermissionsError!void {
if (@sizeOf(Dir.Permissions) == 0) return;
if (is_windows) @panic("TODO implement dirSetFilePermissions windows");
const t: *Threaded = @ptrCast(@alignCast(userdata));
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const mode = permissions.toMode();
const flags: u32 = if (!options.follow_symlinks) posix.AT.SYMLINK_NOFOLLOW else 0;
return posixFchmodat(t, dir.handle, sub_path_posix, mode, flags);
}
fn posixFchmodat(
t: *Threaded,
dir_fd: posix.fd_t,
path: [*:0]const u8,
mode: posix.mode_t,
flags: u32,
) Dir.SetFilePermissionsError!void {
// 若可使用 libc 回退,或 `flags` 为空,则无需对 Linux 特殊处理。
// Glibc 直到 2.32 才添加此回退。
if (have_fchmodat_flags or flags == 0) {
const syscall: Syscall = try .start();
while (true) {
const rc = if (have_fchmodat_flags or builtin.link_libc)
posix.system.fchmodat(dir_fd, path, mode, flags)
else
posix.system.fchmodat(dir_fd, path, mode);
switch (posix.errno(rc)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.IO => return error.InputOutput,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.OPNOTSUPP => return error.OperationUnsupported,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
if (@atomicLoad(UseFchmodat2, &t.use_fchmodat2, .monotonic) == .disabled)
return fchmodatFallback(dir_fd, path, mode);
comptime assert(native_os == .linux);
const syscall: Syscall = try .start();
while (true) {
switch (std.os.linux.errno(std.os.linux.fchmodat2(dir_fd, path, mode, flags))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.IO => return error.InputOutput,
.LOOP => return error.SymLinkLoop,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.FileNotFound,
.OPNOTSUPP => return error.OperationUnsupported,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
.NOSYS => {
@atomicStore(UseFchmodat2, &t.use_fchmodat2, .disabled, .monotonic);
return fchmodatFallback(dir_fd, path, mode);
},
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fchmodatFallback(
dir_fd: posix.fd_t,
path: [*:0]const u8,
mode: posix.mode_t,
) Dir.SetFilePermissionsError!void {
comptime assert(native_os == .linux);
// 回退为通过 procfs 更改权限:
//
// 1. 将 `path` 以 `PATH` 描述符打开。
// 2. 对文件描述符执行 stat,并检查它是否不是符号链接。
// 3. 通过 `/proc/self/fd/{fd}` 生成指向该描述符的 procfs 引用。
// 4. 将 procfs 路径及 `mode` 传给 `chmod`。
const path_fd: posix.fd_t = fd: {
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.openat(dir_fd, path, .{
.PATH = true,
.NOFOLLOW = true,
.CLOEXEC = true,
}, @as(posix.mode_t, 0));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :fd @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
};
defer closeFd(path_fd);
const path_mode = mode: {
const sys = if (statx_use_c) std.c else std.os.linux;
const syscall: Syscall = try .start();
while (true) {
var statx = std.mem.zeroes(std.os.linux.Statx);
switch (sys.errno(sys.statx(path_fd, "", posix.AT.EMPTY_PATH, .{ .TYPE = true }, &statx))) {
.SUCCESS => {
syscall.finish();
if (!statx.mask.TYPE) return error.Unexpected;
break :mode statx.mode;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.LOOP => return error.SymLinkLoop,
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
};
// 尽管只请求 TYPE,内核仍可能填充其他位。
if ((path_mode & posix.S.IFMT) == posix.S.IFLNK)
return error.OperationUnsupported;
var procfs_buf: ["/proc/self/fd/-2147483648\x00".len]u8 = undefined;
const proc_path = std.mem.printSentinel(&procfs_buf, "/proc/self/fd/{d}", .{path_fd}, 0) catch unreachable;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.chmod(proc_path, mode))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.NOENT => return error.OperationUnsupported, // procfs 未挂载。
.BADF => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.IO => return error.InputOutput,
.LOOP => return error.SymLinkLoop,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.FileNotFound,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const dirSetOwner = switch (native_os) {
.windows => dirSetOwnerUnsupported,
else => dirSetOwnerPosix,
};
fn dirSetOwnerUnsupported(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void {
_ = userdata;
_ = dir;
_ = owner;
_ = group;
return error.Unexpected;
}
fn dirSetOwnerPosix(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void {
if (!have_fchown) return error.Unexpected; // 不支持的操作系统,不要调用此函数。
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const uid = owner orelse ~@as(posix.uid_t, 0);
const gid = group orelse ~@as(posix.gid_t, 0);
return posixFchown(dir.handle, uid, gid);
}
fn posixFchown(fd: posix.fd_t, uid: posix.uid_t, gid: posix.gid_t) File.SetOwnerError!void {
comptime assert(have_fchown);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.fchown(fd, uid, gid))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // fd 很可能指向未设置 `Dir.OpenOptions.iterate` 打开的目录
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.IO => return error.InputOutput,
.LOOP => return error.SymLinkLoop,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.FileNotFound,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirSetFileOwner(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
owner: ?File.Uid,
group: ?File.Gid,
options: Dir.SetFileOwnerOptions,
) Dir.SetFileOwnerError!void {
if (!have_fchown) return error.Unexpected; // 不支持的操作系统,不要调用此函数。
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
_ = dir;
_ = sub_path_posix;
_ = owner;
_ = group;
_ = options;
@panic("TODO implement dirSetFileOwner");
}
const fileSync = switch (native_os) {
.windows => fileSyncWindows,
.wasi => fileSyncWasi,
else => fileSyncPosix,
};
fn fileSyncWindows(userdata: ?*anyopaque, file: File) File.SyncError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (windows.ntdll.NtFlushBuffersFile(file.handle, &io_status_block)) {
.SUCCESS => break syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_HANDLE => unreachable,
.ACCESS_DENIED => return syscall.fail(error.AccessDenied), // 已执行同步,但系统无法更新访问时间
.UNEXPECTED_NETWORK_ERROR => return syscall.fail(error.InputOutput),
else => |status| return syscall.unexpectedNtstatus(status),
}
}
}
fn fileSyncPosix(userdata: ?*anyopaque, file: File) File.SyncError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.fsync(file.handle))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ROFS => |err| return errnoBug(err),
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.DQUOT => return error.DiskQuota,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileSyncWasi(userdata: ?*anyopaque, file: File) File.SyncError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.fd_sync(file.handle)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ROFS => |err| return errnoBug(err),
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.DQUOT => return error.DiskQuota,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileIsTty(userdata: ?*anyopaque, file: File) Io.Cancelable!bool {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return isTty(file);
}
fn isTty(file: File) Io.Cancelable!bool {
if (is_windows) {
var get_console_mode = windows.CONSOLE.USER_IO.GET_MODE;
switch ((try deviceIoControl(&.{
.file = .{
.handle = windows.peb().ProcessParameters.ConsoleHandle,
.flags = .{ .nonblocking = false },
},
.code = windows.IOCTL.CONDRV.ISSUE_USER_IO,
.in = @ptrCast(&get_console_mode.request(file, 0, .{}, 0, .{})),
})).u.Status) {
.SUCCESS => return true,
.CANCELLED => unreachable,
.INVALID_HANDLE => return isCygwinPty(file),
else => return false,
}
}
if (builtin.link_libc) {
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.isatty(file.handle);
switch (posix.errno(rc - 1)) {
.SUCCESS => {
syscall.finish();
return true;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => {
syscall.finish();
return false;
},
}
}
}
if (native_os == .wasi) {
var statbuf: std.os.wasi.fdstat_t = undefined;
const err = std.os.wasi.fd_fdstat_get(file.handle, &statbuf);
if (err != .SUCCESS)
return false;
// tty 是无法执行定位或查询当前位置的字符设备。
if (statbuf.fs_filetype != .CHARACTER_DEVICE)
return false;
if (statbuf.fs_rights_base.FD_SEEK or statbuf.fs_rights_base.FD_TELL)
return false;
return true;
}
if (native_os == .linux) {
const linux = std.os.linux;
const syscall: Syscall = try .start();
while (true) {
var wsz: posix.winsize = undefined;
const fd: usize = @bitCast(@as(isize, file.handle));
const rc = linux.syscall3(.ioctl, fd, linux.T.IOCGWINSZ, @intFromPtr(&wsz));
switch (linux.errno(rc)) {
.SUCCESS => {
syscall.finish();
return true;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => {
syscall.finish();
return false;
},
}
}
}
@compileError("unimplemented");
}
fn fileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (!is_windows) return if (!try supportsAnsiEscapeCodes(t, file)) error.NotTerminalDevice;
// Windows Terminal 默认启用 VT 序列处理。
const console: File = .{
.handle = windows.peb().ProcessParameters.ConsoleHandle,
.flags = .{ .nonblocking = false },
};
var get_console_mode = windows.CONSOLE.USER_IO.GET_MODE;
switch ((try deviceIoControl(&.{
.file = console,
.code = windows.IOCTL.CONDRV.ISSUE_USER_IO,
.in = @ptrCast(&get_console_mode.request(file, 0, .{}, 0, .{})),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INVALID_HANDLE => return if (!try isCygwinPty(file)) error.NotTerminalDevice,
else => return error.NotTerminalDevice,
}
if (get_console_mode.Data & windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING != 0) return;
// Windows 控制台自 Windows 10 内部版本 14361 起支持 VT 序列处理,但默认禁用。
// https://devblogs.microsoft.com/commandline/tmux-support-arrives-for-bash-on-ubuntu-on-windows/
//
// 注意:微软启用虚拟终端处理的示例还会尝试启用 `DISABLE_NEWLINE_AUTO_RETURN`:
// https://learn.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences#example-of-enabling-virtual-terminal-processing
// 此处避免这样做,因为旧版 Windows 控制台中的该标志会导致 \n(而非 \r\n)出现非预期行为:光标向下移动 1 行,但停留在原列。
// 另外,Windows Terminal 的默认控制台模式未设置 `DISABLE_NEWLINE_AUTO_RETURN`,因此只启用 `ENABLE_VIRTUAL_TERMINAL_PROCESSING` 即可与 Windows Terminal 的模式一致。
//
//
//
//
var set_console_mode = windows.CONSOLE.USER_IO.SET_MODE(
get_console_mode.Data | windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING,
);
switch ((try deviceIoControl(&.{
.file = console,
.code = windows.IOCTL.CONDRV.ISSUE_USER_IO,
.in = @ptrCast(&set_console_mode.request(file, 0, .{}, 0, .{})),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
else => |status| return windows.unexpectedStatus(status),
}
}
fn fileSupportsAnsiEscapeCodes(userdata: ?*anyopaque, file: File) Io.Cancelable!bool {
const t: *Threaded = @ptrCast(@alignCast(userdata));
return supportsAnsiEscapeCodes(t, file);
}
fn supportsAnsiEscapeCodes(t: *Threaded, file: File) Io.Cancelable!bool {
if (is_windows) {
var get_console_mode = windows.CONSOLE.USER_IO.GET_MODE;
return switch ((try deviceIoControl(&.{
.file = .{
.handle = windows.peb().ProcessParameters.ConsoleHandle,
.flags = .{ .nonblocking = false },
},
.code = windows.IOCTL.CONDRV.ISSUE_USER_IO,
.in = @ptrCast(&get_console_mode.request(file, 0, .{}, 0, .{})),
})).u.Status) {
.SUCCESS => get_console_mode.Data & windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING != 0,
.CANCELLED => unreachable,
.INVALID_HANDLE => isCygwinPty(file),
else => false,
};
}
if (native_os == .wasi) {
// 当 fd 为 tty 时,WASI 会净化 stdout,因此 ANSI 转义码不会被解释为实际光标命令;stderr 则始终被净化。
//
//
return false;
}
if (try isTty(file)) {
if (file.handle == posix.STDOUT_FILENO or file.handle == posix.STDERR_FILENO) {
t.scanEnviron();
if (t.environ.string.TERM) |term| {
if (std.mem.eql(u8, term, "dumb")) {
return false;
}
}
}
return true;
}
return false;
}
fn isCygwinPty(file: File) Io.Cancelable!bool {
if (!is_windows) return false;
const handle = file.handle;
// 若这是 MSYS2/cygwin pty,则为名称采用下列格式之一的命名管道:
// msys-[...]-ptyN-[...]
// cygwin-[...]-ptyN-[...]
//
// 示例:msys-1888ae32e00d56aa-pty0-to-master
// 首先仅检查句柄是否为命名管道。这样,对非命名管道句柄就可避免代价更高的 NtQueryInformationFile 调用。
//
//
{
var io_status: windows.IO_STATUS_BLOCK = undefined;
var device_info: windows.FILE.FS_DEVICE_INFORMATION = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryVolumeInformationFile(
handle,
&io_status,
&device_info,
@sizeOf(windows.FILE.FS_DEVICE_INFORMATION),
.Device,
)) {
.SUCCESS => break syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => {
syscall.finish();
return false;
},
};
if (device_info.DeviceType.FileDevice != .NAMED_PIPE) return false;
}
const name_bytes_offset = @offsetOf(windows.FILE.NAME_INFORMATION, "FileName");
// `NAME_MAX` 个 UTF-16 码元(每个 2 字节)
// 此缓冲区可能不足以处理*所有*可能的路径
// (那需要 PATH_MAX_WIDE),但我们仅关心
// 某些路径,并且知道它们的长度必定合理,
// 因此可以使用这个较小的缓冲区,并在
// NtQueryInformationFile 返回任何错误时直接返回 false。
const num_name_bytes = windows.MAX_PATH * 2;
var name_info_bytes: [name_bytes_offset + num_name_bytes]u8 align(@alignOf(windows.FILE.NAME_INFORMATION)) = @splat(0);
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryInformationFile(
handle,
&io_status_block,
&name_info_bytes,
@intCast(name_info_bytes.len),
.Name,
)) {
.SUCCESS => break syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_PARAMETER => unreachable,
else => {
syscall.finish();
return false;
},
};
const name_info: *const windows.FILE.NAME_INFORMATION = @ptrCast(&name_info_bytes);
const name_bytes = name_info_bytes[name_bytes_offset .. name_bytes_offset + name_info.FileNameLength];
const name_wide = std.mem.bytesAsSlice(u16, name_bytes);
// 从 NtQueryInformationFile 获得的名称带有“\”前缀,例如 \msys-1888ae32e00d56aa-pty0-to-master
return (std.mem.startsWith(u16, name_wide, &[_]u16{ '\\', 'm', 's', 'y', 's', '-' }) or
std.mem.startsWith(u16, name_wide, &[_]u16{ '\\', 'c', 'y', 'g', 'w', 'i', 'n', '-' })) and
std.mem.find(u16, name_wide, &[_]u16{ '-', 'p', 't', 'y' }) != null;
}
fn fileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const signed_len: i64 = @bitCast(length);
if (signed_len < 0) return error.FileTooBig; // 避免含义不明确的 EINVAL 错误。
if (is_windows) {
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var eof_info: windows.FILE.END_OF_FILE_INFORMATION = .{
.EndOfFile = signed_len,
};
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtSetInformationFile(
file.handle,
&io_status_block,
&eof_info,
@sizeOf(windows.FILE.END_OF_FILE_INFORMATION),
.EndOfFile,
)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_HANDLE => |err| return syscall.ntstatusBug(err), // 句柄未以写入方式打开。
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
.INVALID_PARAMETER => return syscall.fail(error.FileTooBig),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
if (native_os == .wasi and !builtin.link_libc) {
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.fd_filestat_set_size(file.handle, length)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.PERM => return error.PermissionDenied,
.TXTBSY => return error.FileBusy,
.BADF => |err| return errnoBug(err), // 句柄未以写入方式打开
.INVAL => return error.NonResizable,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(ftruncate_sym(file.handle, signed_len))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.PERM => return error.PermissionDenied,
.TXTBSY => return error.FileBusy,
.BADF => |err| return errnoBug(err), // 句柄未以写入方式打开。
.INVAL => return error.NonResizable, // 例如,/dev/null 会返回此值。
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileSetOwner(userdata: ?*anyopaque, file: File, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void {
if (!have_fchown) return error.Unexpected; // 不支持的操作系统,不要调用此函数。
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const uid = owner orelse ~@as(posix.uid_t, 0);
const gid = group orelse ~@as(posix.gid_t, 0);
return posixFchown(file.handle, uid, gid);
}
fn fileSetPermissions(userdata: ?*anyopaque, file: File, permissions: File.Permissions) File.SetPermissionsError!void {
if (@sizeOf(File.Permissions) == 0) return;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
switch (native_os) {
.windows => {
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var info: windows.FILE.BASIC_INFORMATION = .{
.CreationTime = 0,
.LastAccessTime = 0,
.LastWriteTime = 0,
.ChangeTime = 0,
.FileAttributes = permissions.toAttributes(),
};
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtSetInformationFile(
file.handle,
&io_status_block,
&info,
@sizeOf(windows.FILE.BASIC_INFORMATION),
.Basic,
)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_HANDLE => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
else => |status| return syscall.unexpectedNtstatus(status),
};
},
.wasi => return error.Unexpected, // 不支持的操作系统。
else => return setPermissionsPosix(file.handle, permissions.toMode()),
}
}
fn setPermissionsPosix(fd: posix.fd_t, mode: posix.mode_t) File.SetPermissionsError!void {
comptime assert(have_fchmod);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.fchmod(fd, mode))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.ACCES => return error.AccessDenied,
.IO => return error.InputOutput,
.LOOP => return error.SymLinkLoop,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.FileNotFound,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirSetTimestamps(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.SetTimestampsOptions,
) Dir.SetTimestampsError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
@panic("TODO implement dirSetTimestamps windows");
}
if (native_os == .wasi and !builtin.link_libc) {
@panic("TODO implement dirSetTimestamps wasi");
}
var times_buffer: [2]posix.timespec = undefined;
const times = if (options.modify_timestamp == .now and options.access_timestamp == .now) null else p: {
times_buffer = .{
setTimestampToPosix(options.access_timestamp),
setTimestampToPosix(options.modify_timestamp),
};
break :p ×_buffer;
};
const flags: u32 = if (!options.follow_symlinks) posix.AT.SYMLINK_NOFOLLOW else 0;
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.utimensat(dir.handle, sub_path_posix, times, flags))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.BADF => |err| return syscall.errnoBug(err), // 始终存在竞态条件
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
.ACCES => return syscall.fail(error.AccessDenied),
.PERM => return syscall.fail(error.PermissionDenied),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
else => |err| return syscall.unexpectedErrno(err),
};
}
fn fileSetTimestamps(
userdata: ?*anyopaque,
file: File,
options: File.SetTimestampsOptions,
) File.SetTimestampsError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
const now_sys = if (options.access_timestamp == .now or options.modify_timestamp == .now)
windows.ntdll.RtlGetSystemTimePrecise()
else
undefined;
var iosb: windows.IO_STATUS_BLOCK = undefined;
var info: windows.FILE.BASIC_INFORMATION = .{
.CreationTime = 0,
.LastAccessTime = switch (options.access_timestamp) {
.unchanged => 0,
.now => now_sys,
.new => |ts| windows.toSysTime(ts),
},
.LastWriteTime = switch (options.modify_timestamp) {
.unchanged => 0,
.now => now_sys,
.new => |ts| windows.toSysTime(ts),
},
.ChangeTime = 0,
.FileAttributes = .{},
};
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtSetInformationFile(
file.handle,
&iosb,
&info,
@sizeOf(windows.FILE.BASIC_INFORMATION),
.Basic,
)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => try syscall.checkCancel(),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
if (native_os == .wasi and !builtin.link_libc) {
var atime: std.os.wasi.timestamp_t = 0;
var mtime: std.os.wasi.timestamp_t = 0;
var flags: std.os.wasi.fstflags_t = .{};
switch (options.access_timestamp) {
.unchanged => {},
.now => flags.ATIM_NOW = true,
.new => |ts| {
atime = timestampToPosix(ts.nanoseconds).toTimestamp();
flags.ATIM = true;
},
}
switch (options.modify_timestamp) {
.unchanged => {},
.now => flags.MTIM_NOW = true,
.new => |ts| {
mtime = timestampToPosix(ts.nanoseconds).toTimestamp();
flags.MTIM = true;
},
}
const syscall: Syscall = try .start();
while (true) switch (std.os.wasi.fd_filestat_set_times(file.handle, atime, mtime, flags)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.BADF => |err| return syscall.errnoBug(err), // 文件描述符释放后仍被使用。
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
.ACCES => return syscall.fail(error.AccessDenied),
.PERM => return syscall.fail(error.PermissionDenied),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
else => |err| return syscall.unexpectedErrno(err),
};
}
var times_buffer: [2]posix.timespec = undefined;
const times = if (options.modify_timestamp == .now and options.access_timestamp == .now) null else p: {
times_buffer = .{
setTimestampToPosix(options.access_timestamp),
setTimestampToPosix(options.modify_timestamp),
};
break :p ×_buffer;
};
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.futimens(file.handle, times))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.BADF => |err| return syscall.errnoBug(err), // 始终存在竞态条件
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
.ACCES => return syscall.fail(error.AccessDenied),
.PERM => return syscall.fail(error.PermissionDenied),
.ROFS => return syscall.fail(error.ReadOnlyFileSystem),
else => |err| return syscall.unexpectedErrno(err),
};
}
const windows_lock_range_off: windows.LARGE_INTEGER = 0;
const windows_lock_range_len: windows.LARGE_INTEGER = 1;
fn fileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void {
if (native_os == .wasi) return error.FileLocksUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
const exclusive = switch (lock) {
.none => {
// 解锁以匹配非 Windows 平台的行为
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
while (true) switch (windows.ntdll.NtUnlockFile(
file.handle,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
0,
)) {
.SUCCESS => return,
.CANCELLED => continue,
.RANGE_NOT_LOCKED => return,
.ACCESS_VIOLATION => |err| return windows.statusBug(err), // 无效的 io_status_block 指针
else => |status| return windows.unexpectedStatus(status),
};
},
.shared => false,
.exclusive => true,
};
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtLockFile(
file.handle,
null,
null,
null,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
null,
.FALSE,
.fromBool(exclusive),
)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INSUFFICIENT_RESOURCES => return syscall.fail(error.SystemResources),
.LOCK_NOT_GRANTED => |err| return syscall.ntstatusBug(err), // 传入了 FailImmediately=false
.ACCESS_VIOLATION => |err| return syscall.ntstatusBug(err), // 无效的 io_status_block 指针
else => |status| return syscall.unexpectedNtstatus(status),
};
}
const operation: i32 = switch (lock) {
.none => posix.LOCK.UN,
.shared => posix.LOCK.SH,
.exclusive => posix.LOCK.EX,
};
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.flock(file.handle, operation))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err), // 无效参数
.NOLCK => return error.SystemResources,
.AGAIN => |err| return errnoBug(err),
.OPNOTSUPP => return error.FileLocksUnsupported,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool {
if (native_os == .wasi) return error.FileLocksUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
const exclusive = switch (lock) {
.none => {
// 解锁以匹配非 Windows 平台的行为
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
while (true) switch (windows.ntdll.NtUnlockFile(
file.handle,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
0,
)) {
.SUCCESS => return true,
.CANCELLED => continue,
.RANGE_NOT_LOCKED => return false,
.ACCESS_VIOLATION => |err| return windows.statusBug(err), // 无效的 io_status_block 指针
else => |status| return windows.unexpectedStatus(status),
};
},
.shared => false,
.exclusive => true,
};
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtLockFile(
file.handle,
null,
null,
null,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
null,
.TRUE,
.fromBool(exclusive),
)) {
.SUCCESS => {
syscall.finish();
return true;
},
.LOCK_NOT_GRANTED => {
syscall.finish();
return false;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INSUFFICIENT_RESOURCES => return syscall.fail(error.SystemResources),
.ACCESS_VIOLATION => |err| return syscall.ntstatusBug(err), // 无效的 io_status_block 指针
else => |status| return syscall.unexpectedNtstatus(status),
};
}
const operation: i32 = switch (lock) {
.none => posix.LOCK.UN,
.shared => posix.LOCK.SH | posix.LOCK.NB,
.exclusive => posix.LOCK.EX | posix.LOCK.NB,
};
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.flock(file.handle, operation))) {
.SUCCESS => {
syscall.finish();
return true;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.AGAIN => {
syscall.finish();
return false;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err), // 无效参数
.NOLCK => return error.SystemResources,
.OPNOTSUPP => return error.FileLocksUnsupported,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileUnlock(userdata: ?*anyopaque, file: File) void {
if (native_os == .wasi) return;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
while (true) switch (windows.ntdll.NtUnlockFile(
file.handle,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
0,
)) {
.SUCCESS => return,
.CANCELLED => continue,
.RANGE_NOT_LOCKED => if (is_debug) unreachable else return, // 函数断言未锁定。
.ACCESS_VIOLATION => if (is_debug) unreachable else return, // 无效的 io_status_block 指针
else => if (is_debug) unreachable else return, // 资源释放必须成功。
};
}
while (true) {
switch (posix.errno(posix.system.flock(file.handle, posix.LOCK.UN))) {
.SUCCESS => return,
.CANCELED, .INTR => continue,
.AGAIN => return assert(!is_debug), // 解锁不能阻塞
.BADF => return assert(!is_debug), // 文件描述符在关闭后被使用。
.INVAL => return assert(!is_debug), // 无效参数
.NOLCK => return assert(!is_debug), // 资源释放。
.OPNOTSUPP => return assert(!is_debug), // 我们已经获得锁。
else => return assert(!is_debug), // 资源释放必须成功。
}
}
}
fn fileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void {
if (native_os == .wasi) return;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
// 在 Windows 上,其行为类似信号量加独占标志。
// 实现此函数时,先以共享模式再获取
// 一个锁。这会改变独占标志,但将
// 信号量增至 2。因此随后调用 NtUnlockFile,
// 减小信号量而不修改独占标志。
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtLockFile(
file.handle,
null,
null,
null,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
null,
.TRUE,
.FALSE,
)) {
.SUCCESS => break syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INSUFFICIENT_RESOURCES => |err| return syscall.ntstatusBug(err),
.LOCK_NOT_GRANTED => |err| return syscall.ntstatusBug(err), // 文件未以排他模式加锁。
.ACCESS_VIOLATION => |err| return syscall.ntstatusBug(err), // 无效的 io_status_block 指针
else => |status| return syscall.unexpectedNtstatus(status),
};
while (true) switch (windows.ntdll.NtUnlockFile(
file.handle,
&io_status_block,
&windows_lock_range_off,
&windows_lock_range_len,
0,
)) {
.SUCCESS => return,
.CANCELLED => continue,
.RANGE_NOT_LOCKED => if (is_debug) unreachable else return, // 文件未锁定。
.ACCESS_VIOLATION => if (is_debug) unreachable else return, // 无效的 io_status_block 指针
else => if (is_debug) unreachable else return, // 资源释放必须成功。
};
}
const operation = posix.LOCK.SH | posix.LOCK.NB;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.flock(file.handle, operation))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.AGAIN => |err| return errnoBug(err), // 文件未以排他模式加锁。
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err), // 无效参数
.NOLCK => |err| return errnoBug(err), // 已获取锁。
.OPNOTSUPP => |err| return errnoBug(err), // 已获取锁。
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirOpenDirWasi(
userdata: ?*anyopaque,
dir: Dir,
sub_path: []const u8,
options: Dir.OpenOptions,
) Dir.OpenError!Dir {
if (builtin.link_libc) return dirOpenDirPosix(userdata, dir, sub_path, options);
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const wasi = std.os.wasi;
var base: std.os.wasi.rights_t = .{
.FD_FILESTAT_GET = true,
.FD_FDSTAT_SET_FLAGS = true,
.FD_FILESTAT_SET_TIMES = true,
};
if (options.access_sub_paths) {
base.FD_READDIR = true;
base.PATH_CREATE_DIRECTORY = true;
base.PATH_CREATE_FILE = true;
base.PATH_LINK_SOURCE = true;
base.PATH_LINK_TARGET = true;
base.PATH_OPEN = true;
base.PATH_READLINK = true;
base.PATH_RENAME_SOURCE = true;
base.PATH_RENAME_TARGET = true;
base.PATH_FILESTAT_GET = true;
base.PATH_FILESTAT_SET_SIZE = true;
base.PATH_FILESTAT_SET_TIMES = true;
base.PATH_SYMLINK = true;
base.PATH_REMOVE_DIRECTORY = true;
base.PATH_UNLINK_FILE = true;
}
const lookup_flags: wasi.lookupflags_t = .{ .SYMLINK_FOLLOW = options.follow_symlinks };
const oflags: wasi.oflags_t = .{ .DIRECTORY = true };
const fdflags: wasi.fdflags_t = .{};
var fd: posix.fd_t = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (wasi.path_open(dir.handle, lookup_flags, sub_path.ptr, sub_path.len, oflags, base, base, fdflags, &fd)) {
.SUCCESS => {
syscall.finish();
return .{ .handle = fd };
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.FAULT => |err| return errnoBug(err),
.INVAL => return error.BadPathName,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.ACCES => return error.AccessDenied,
.LOOP => return error.SymLinkLoop,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.NoDevice,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.NOTCAPABLE => return error.AccessDenied,
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn dirHardLink(
userdata: ?*anyopaque,
old_dir: Dir,
old_sub_path: []const u8,
new_dir: Dir,
new_sub_path: []const u8,
options: Dir.HardLinkOptions,
) Dir.HardLinkError!void {
if (is_windows) return error.OperationUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (native_os == .wasi and !builtin.link_libc) {
const flags: std.os.wasi.lookupflags_t = .{
.SYMLINK_FOLLOW = options.follow_symlinks,
};
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.path_link(
old_dir.handle,
flags,
old_sub_path.ptr,
old_sub_path.len,
new_dir.handle,
new_sub_path.ptr,
new_sub_path.len,
)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.DQUOT => return error.DiskQuota,
.EXIST => return error.PathAlreadyExists,
.FAULT => |err| return errnoBug(err),
.IO => return error.HardwareFailure,
.LOOP => return error.SymLinkLoop,
.MLINK => return error.LinkQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.NOTDIR => return error.NotDir,
.PERM => return error.PermissionDenied,
.ROFS => return error.ReadOnlyFileSystem,
.XDEV => return error.CrossDevice,
.INVAL => |err| return errnoBug(err),
.ILSEQ => return error.BadPathName,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
var old_path_buffer: [posix.PATH_MAX]u8 = undefined;
var new_path_buffer: [posix.PATH_MAX]u8 = undefined;
const old_sub_path_posix = try pathToPosix(old_sub_path, &old_path_buffer);
const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);
const flags: u32 = if (options.follow_symlinks) posix.AT.SYMLINK_FOLLOW else 0;
return linkat(old_dir.handle, old_sub_path_posix, new_dir.handle, new_sub_path_posix, flags);
}
fn fileClose(userdata: ?*anyopaque, files: []const File) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
for (files) |file| {
if (is_windows) {
windows.CloseHandle(file.handle);
} else {
closeFd(file.handle);
}
}
}
fn fileReadStreaming(userdata: ?*anyopaque, file: File, data: []const []u8) File.ReadStreamingError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) return fileReadStreamingWindows(file, data);
return fileReadStreamingPosix(file, data);
}
fn fileReadStreamingPosix(file: File, data: []const []u8) File.ReadStreamingError!usize {
var iovecs_buffer: [max_iovecs_len]posix.iovec = undefined;
var i: usize = 0;
for (data) |buf| {
if (iovecs_buffer.len - i == 0) break;
if (buf.len != 0) {
iovecs_buffer[i] = .{ .base = buf.ptr, .len = buf.len };
i += 1;
}
}
if (i == 0) return 0;
const dest = iovecs_buffer[0..i];
assert(dest[0].len > 0);
if (native_os == .wasi and !builtin.link_libc) {
const syscall: Syscall = try .start();
while (true) {
var nread: usize = undefined;
switch (std.os.wasi.fd_read(file.handle, dest.ptr, dest.len, &nread)) {
.SUCCESS => {
syscall.finish();
if (nread == 0) return error.EndOfStream;
return nread;
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.BADF => return syscall.fail(error.IsDir), // 对目录执行文件操作。
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.NOTCONN => return syscall.fail(error.SocketUnconnected),
.CONNRESET => return syscall.fail(error.ConnectionResetByPeer),
.NOTCAPABLE => return syscall.fail(error.AccessDenied),
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.readv(file.handle, dest.ptr, @intCast(dest.len));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
if (rc == 0) return error.EndOfStream;
return @intCast(rc);
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.BADF => {
syscall.finish();
if (native_os == .wasi) return error.IsDir; // 对目录执行文件操作。
return error.NotOpenForReading;
},
.AGAIN => return syscall.fail(error.WouldBlock),
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.NOTCONN => return syscall.fail(error.SocketUnconnected),
.CONNRESET => return syscall.fail(error.ConnectionResetByPeer),
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn fileReadStreamingWindows(file: File, data: []const []u8) File.ReadStreamingError!usize {
var iosb: windows.IO_STATUS_BLOCK = undefined;
var index: usize = 0;
while (data.len - index != 0 and data[index].len == 0) index += 1;
if (data.len - index == 0) return 0;
const buffer = data[index];
const short_buffer_len = std.math.lossyCast(u32, buffer.len);
if (file.flags.nonblocking) {
var done: bool = false;
switch (windows.ntdll.NtReadFile(
file.handle,
null, // 事件
flagApc,
&done, // APC 上下文
&iosb,
buffer.ptr,
short_buffer_len,
null, // 字节偏移量
null, // 键
)) {
// 必须等待 APC 例程。
.PENDING, .SUCCESS => while (!done) {
// 一旦到达此处,就必须等操作完成后才能从
// 函数返回,从而释放对 iosb 的引用。
const alertable_syscall = AlertableSyscall.start() catch |err| switch (err) {
error.Canceled => |e| {
var cancel_iosb: windows.IO_STATUS_BLOCK = undefined;
_ = windows.ntdll.NtCancelIoFileEx(file.handle, &iosb, &cancel_iosb);
while (!done) waitForApcOrAlert();
return e;
},
};
waitForApcOrAlert();
alertable_syscall.finish();
},
else => |status| iosb.u.Status = status,
}
} else {
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtReadFile(
file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&iosb,
buffer.ptr,
short_buffer_len,
null, // 字节偏移量
null, // 键
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| {
syscall.finish();
iosb.u.Status = status;
break;
},
};
}
return ntReadFileResult(&iosb);
}
fn flagApc(userdata: ?*anyopaque, _: *windows.IO_STATUS_BLOCK, _: windows.ULONG) align(apc_align) callconv(.winapi) void {
const flag: *bool = @ptrCast(userdata);
flag.* = true;
}
fn ntReadFileResult(io_status_block: *const windows.IO_STATUS_BLOCK) !usize {
switch (io_status_block.u.Status) {
.PENDING => unreachable,
.CANCELLED => unreachable,
.SUCCESS => return io_status_block.Information,
.END_OF_FILE, .PIPE_BROKEN, .PIPE_CLOSING => return error.EndOfStream,
.INVALID_HANDLE => return error.NotOpenForReading,
.INVALID_DEVICE_REQUEST => return error.IsDir,
.FILE_LOCK_CONFLICT => return error.LockViolation,
.ACCESS_DENIED => return error.AccessDenied,
else => |status| return windows.unexpectedStatus(status),
}
}
fn ntWriteFileResult(io_status_block: *const windows.IO_STATUS_BLOCK) !usize {
switch (io_status_block.u.Status) {
.PENDING => unreachable,
.CANCELLED => unreachable,
.SUCCESS => return io_status_block.Information,
.INVALID_USER_BUFFER => return error.SystemResources,
.NO_MEMORY => return error.SystemResources,
.QUOTA_EXCEEDED => return error.SystemResources,
.PIPE_BROKEN, .PIPE_CLOSING => return error.BrokenPipe,
.INVALID_HANDLE => return error.NotOpenForWriting,
.FILE_LOCK_CONFLICT => return error.LockViolation,
.ACCESS_DENIED => return error.AccessDenied,
.WORKING_SET_QUOTA => return error.SystemResources,
.DISK_FULL => return error.NoSpaceLeft,
else => |status| return windows.unexpectedStatus(status),
}
}
fn fileReadPositionalPosix(file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize {
var iovecs_buffer: [max_iovecs_len]posix.iovec = undefined;
var i: usize = 0;
for (data) |buf| {
if (iovecs_buffer.len - i == 0) break;
if (buf.len != 0) {
iovecs_buffer[i] = .{ .base = buf.ptr, .len = buf.len };
i += 1;
}
}
if (i == 0) return 0;
const dest = iovecs_buffer[0..i];
assert(dest[0].len > 0);
if (native_os == .wasi and !builtin.link_libc) {
const syscall: Syscall = try .start();
while (true) {
var nread: usize = undefined;
switch (std.os.wasi.fd_pread(file.handle, dest.ptr, dest.len, offset, &nread)) {
.SUCCESS => {
syscall.finish();
return nread;
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.NOTCONN => |err| return syscall.errnoBug(err), // 不是套接字
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err), // 段错误
.AGAIN => |err| return syscall.errnoBug(err),
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.BADF => return syscall.fail(error.IsDir),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
.NOTCAPABLE => return syscall.fail(error.AccessDenied),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
if (have_preadv) {
const syscall: Syscall = try .start();
while (true) {
const rc = if (native_os == .haiku)
posix.system.readv_pos(file.handle, @bitCast(offset), dest.ptr, @intCast(dest.len))
else
preadv_sym(file.handle, dest.ptr, @intCast(dest.len), @bitCast(offset));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return @bitCast(rc);
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.AGAIN => return syscall.fail(error.WouldBlock),
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.NOTCONN => |err| return syscall.errnoBug(err), // 不是套接字
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.BADF => {
syscall.finish();
if (native_os == .wasi) return error.IsDir; // 对目录执行文件操作。
return error.NotOpenForReading;
},
else => |err| return syscall.unexpectedErrno(err),
}
}
}
const syscall: Syscall = try .start();
while (true) {
const rc = pread_sym(file.handle, dest[0].base, @intCast(dest[0].len), @bitCast(offset));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return @bitCast(rc);
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.AGAIN => return syscall.fail(error.WouldBlock),
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.NOTCONN => |err| return syscall.errnoBug(err), // 不是套接字
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.BADF => {
syscall.finish();
if (native_os == .wasi) return error.IsDir; // 对目录执行文件操作。
return error.NotOpenForReading;
},
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn fileReadPositional(userdata: ?*anyopaque, file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) return fileReadPositionalWindows(file, data, offset);
return fileReadPositionalPosix(file, data, offset);
}
fn fileReadPositionalWindows(file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize {
var index: usize = 0;
while (index < data.len and data[index].len == 0) index += 1;
if (index == data.len) return 0;
const buffer = data[index];
return readFilePositionalWindows(file, buffer, offset);
}
fn readFilePositionalWindows(file: File, buffer: []u8, offset: u64) File.ReadPositionalError!usize {
var iosb: windows.IO_STATUS_BLOCK = undefined;
const short_buffer_len = std.math.lossyCast(u32, buffer.len);
const signed_offset: windows.LARGE_INTEGER = @intCast(offset);
if (file.flags.nonblocking) {
var done: bool = false;
switch (windows.ntdll.NtReadFile(
file.handle,
null, // 事件
flagApc,
&done, // APC 上下文
&iosb,
buffer.ptr,
short_buffer_len,
&signed_offset,
null, // 键
)) {
// 必须等待 APC 例程。
.PENDING, .SUCCESS => while (!done) {
// 一旦到达此处,就必须等操作完成后才能从
// 函数返回,从而释放对 iosb 的引用。
const alertable_syscall = AlertableSyscall.start() catch |err| switch (err) {
error.Canceled => |e| {
var cancel_iosb: windows.IO_STATUS_BLOCK = undefined;
_ = windows.ntdll.NtCancelIoFileEx(file.handle, &iosb, &cancel_iosb);
while (!done) waitForApcOrAlert();
return e;
},
};
waitForApcOrAlert();
alertable_syscall.finish();
},
else => |status| iosb.u.Status = status,
}
} else {
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtReadFile(
file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&iosb,
buffer.ptr,
short_buffer_len,
&signed_offset,
null, // 键
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => try syscall.checkCancel(),
else => |status| {
syscall.finish();
iosb.u.Status = status;
break;
},
};
}
return ntReadFileResult(&iosb) catch |err| switch (err) {
error.EndOfStream => 0,
else => |e| e,
};
}
fn fileSeekBy(userdata: ?*anyopaque, file: File, offset: i64) File.SeekError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
var iosb: windows.IO_STATUS_BLOCK = undefined;
var info: windows.FILE.POSITION_INFORMATION = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtQueryInformationFile(
file.handle,
&iosb,
&info,
@sizeOf(windows.FILE.POSITION_INFORMATION),
.Position,
)) {
.SUCCESS => break,
.CANCELLED => try syscall.checkCancel(),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.Unseekable),
else => |status| return syscall.unexpectedNtstatus(status),
};
info.CurrentByteOffset = @bitCast((if (offset >= 0) std.math.add(
u64,
@bitCast(info.CurrentByteOffset),
@intCast(offset),
) else std.math.sub(
u64,
@bitCast(info.CurrentByteOffset),
@intCast(-offset),
)) catch |err| switch (err) {
error.Overflow => return syscall.fail(error.Unseekable),
});
while (true) switch (windows.ntdll.NtSetInformationFile(
file.handle,
&iosb,
&info,
@sizeOf(windows.FILE.POSITION_INFORMATION),
.Position,
)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => try syscall.checkCancel(),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.Unseekable),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
if (native_os == .wasi and !builtin.link_libc) {
var new_offset: std.os.wasi.filesize_t = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.fd_seek(file.handle, offset, .CUR, &new_offset)) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.SPIPE => return error.Unseekable,
.NXIO => return error.Unseekable,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
if (posix.SEEK == void) return error.Unseekable;
if (native_os == .linux and !builtin.link_libc and @sizeOf(posix.system.syscall_arg_t) == 4) {
var result: i64 = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.llseek(file.handle, offset, &result, posix.SEEK.CUR))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.SPIPE => return error.Unseekable,
.NXIO => return error.Unseekable,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(lseek_sym(file.handle, offset, posix.SEEK.CUR))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.SPIPE => return error.Unseekable,
.NXIO => return error.Unseekable,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileSeekTo(userdata: ?*anyopaque, file: File, offset: u64) File.SeekError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
var iosb: windows.IO_STATUS_BLOCK = undefined;
var info: windows.FILE.POSITION_INFORMATION = .{ .CurrentByteOffset = @bitCast(offset) };
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtSetInformationFile(
file.handle,
&iosb,
&info,
@sizeOf(windows.FILE.POSITION_INFORMATION),
.Position,
)) {
.SUCCESS => return syscall.finish(),
.CANCELLED => try syscall.checkCancel(),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.Unseekable),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
if (native_os == .wasi and !builtin.link_libc) {
const syscall: Syscall = try .start();
while (true) {
var new_offset: std.os.wasi.filesize_t = undefined;
switch (std.os.wasi.fd_seek(file.handle, @bitCast(offset), .SET, &new_offset)) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.SPIPE => return error.Unseekable,
.NXIO => return error.Unseekable,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
if (posix.SEEK == void) return error.Unseekable;
return posixSeekTo(file.handle, offset);
}
fn posixSeekTo(fd: posix.fd_t, offset: u64) File.SeekError!void {
if (native_os == .linux and !builtin.link_libc and @sizeOf(posix.system.syscall_arg_t) == 4) {
const syscall: Syscall = try .start();
while (true) {
var result: i64 = undefined;
switch (posix.errno(posix.system.llseek(fd, @bitCast(offset), &result, posix.SEEK.SET))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.SPIPE => return error.Unseekable,
.NXIO => return error.Unseekable,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(lseek_sym(fd, @bitCast(offset), posix.SEEK.SET))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
.SPIPE => return error.Unseekable,
.NXIO => return error.Unseekable,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn processExecutableOpen(userdata: ?*anyopaque, flags: Dir.OpenFileOptions) process.OpenExecutableError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
switch (native_os) {
.wasi => return error.OperationUnsupported,
.linux, .serenity => return dirOpenFilePosix(t, .{ .handle = posix.AT.FDCWD }, "/proc/self/exe", flags),
.windows => {
// 若 ImagePathName 是符号链接,则它包含符号链接自身的路径,
// 而非该链接指向的路径。但由于这里会打开
// 文件,可以让 openFileW 调用代为跟随符号链接。
const image_path_name = windows.peb().ProcessParameters.ImagePathName.sliceZ();
const prefixed_path_w = try wToPrefixedFileW(null, image_path_name, .{});
return dirOpenFileWtf16(null, prefixed_path_w.span(), flags);
},
.driverkit,
.ios,
.maccatalyst,
.macos,
.tvos,
.visionos,
.watchos,
=> {
// _NSGetExecutablePath() 返回的路径可能是指向
// 可执行文件的符号链接。此处会打开它,因此没有影响。
var symlink_path_buf: [posix.PATH_MAX + 1]u8 = undefined;
var n: u32 = symlink_path_buf.len;
const rc = std.c._NSGetExecutablePath(&symlink_path_buf, &n);
if (rc != 0) return error.NameTooLong;
const symlink_path = std.mem.sliceTo(&symlink_path_buf, 0);
return dirOpenFilePosix(t, .cwd(), symlink_path, flags);
},
else => {
var buffer: [Dir.max_path_bytes]u8 = undefined;
const n = try processExecutablePath(t, &buffer);
buffer[n] = 0;
const executable_path = buffer[0..n :0];
return dirOpenFilePosix(t, .cwd(), executable_path, flags);
},
}
}
fn processExecutablePath(userdata: ?*anyopaque, out_buffer: []u8) process.ExecutablePathError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
switch (native_os) {
.driverkit,
.ios,
.maccatalyst,
.macos,
.tvos,
.visionos,
.watchos,
=> {
// _NSGetExecutablePath() 返回的路径可能是指向可执行文件的符号链接。
//
var symlink_path_buf: [posix.PATH_MAX + 1]u8 = undefined;
var n: u32 = symlink_path_buf.len;
const rc = std.c._NSGetExecutablePath(&symlink_path_buf, &n);
if (rc != 0) return error.NameTooLong;
const symlink_path = std.mem.sliceTo(&symlink_path_buf, 0);
return Io.Dir.realPathFileAbsolute(io(t), symlink_path, out_buffer) catch |err| switch (err) {
error.NetworkNotFound => unreachable, // 仅限 Windows
error.FileBusy => unreachable, // 仅限 Windows
else => |e| return e,
};
},
.linux, .serenity => return Io.Dir.readLinkAbsolute(io(t), "/proc/self/exe", out_buffer) catch |err| switch (err) {
error.UnsupportedReparsePointType => unreachable, // 仅限 Windows
error.NetworkNotFound => unreachable, // 仅限 Windows
error.FileBusy => unreachable, // 仅限 Windows
else => |e| return e,
},
.illumos => return Io.Dir.readLinkAbsolute(io(t), "/proc/self/path/a.out", out_buffer) catch |err| switch (err) {
error.UnsupportedReparsePointType => unreachable, // 仅限 Windows
error.NetworkNotFound => unreachable, // 仅限 Windows
error.FileBusy => unreachable, // 仅限 Windows
else => |e| return e,
},
.freebsd, .dragonfly => {
var mib: [4]c_int = .{ posix.CTL.KERN, posix.KERN.PROC, posix.KERN.PROC_PATHNAME, -1 };
var out_len: usize = out_buffer.len;
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.sysctl(&mib, mib.len, out_buffer.ptr, &out_len, null, 0))) {
.SUCCESS => {
syscall.finish();
return out_len - 1; // 丢弃结尾 NUL
},
.INTR => {
try syscall.checkCancel();
continue;
},
.PERM => return syscall.fail(error.PermissionDenied),
.NOMEM => return syscall.fail(error.SystemResources),
.FAULT => |err| return syscall.errnoBug(err),
.NOENT => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
};
},
.netbsd => {
var mib = [4]c_int{ posix.CTL.KERN, posix.KERN.PROC_ARGS, -1, posix.KERN.PROC_PATHNAME };
var out_len: usize = out_buffer.len;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.sysctl(&mib, mib.len, out_buffer.ptr, &out_len, null, 0))) {
.SUCCESS => {
syscall.finish();
return out_len - 1; // 丢弃结尾 NUL
},
.INTR => {
try syscall.checkCancel();
continue;
},
.PERM => return syscall.fail(error.PermissionDenied),
.NOMEM => return syscall.fail(error.SystemResources),
.FAULT => |err| return syscall.errnoBug(err),
.NOENT => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
},
.openbsd, .haiku => {
// 在这些操作系统上,能做的最佳判断方式
// 是检查第一个进程参数。
const argv0 = std.mem.span(t.argv0.value orelse return error.OperationUnsupported);
if (std.mem.findScalar(u8, argv0, '/') != null) {
// argv[0] 是路径(相对或绝对):直接使用 realpath(3)。
var resolved_buf: [std.c.PATH_MAX]u8 = undefined;
const syscall: Syscall = try .start();
while (true) {
if (std.c.realpath(argv0, &resolved_buf)) |p| {
assert(p == &resolved_buf);
break syscall.finish();
} else switch (@as(std.c.E, @fromBackingInt(@intCast(std.c._errno().*)))) {
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.INVAL => |err| return errnoBug(err), // pathname 参数为空指针
.IO => return error.InputOutput,
.LOOP => return error.SymLinkLoop,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.NOMEM => |err| return errnoBug(err), // 可用存储空间不足,无法进行分配
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
const resolved = std.mem.sliceTo(&resolved_buf, 0);
if (resolved.len > out_buffer.len)
return error.NameTooLong;
@memcpy(out_buffer[0..resolved.len], resolved);
return resolved.len;
} else if (argv0.len != 0) {
// argv[0] 非空且不是路径:搜索 PATH
t.scanEnviron();
const PATH = t.environ.string.PATH orelse return error.FileNotFound;
var it = std.mem.tokenizeScalar(u8, PATH, ':');
it: while (it.next()) |dir| {
var resolved_path_buf: [std.c.PATH_MAX]u8 = undefined;
const resolved_path = std.mem.printSentinel(&resolved_path_buf, "{s}/{s}", .{
dir, argv0,
}, 0) catch continue;
var resolved_buf: [std.c.PATH_MAX]u8 = undefined;
const syscall: Syscall = try .start();
while (true) {
if (std.c.realpath(resolved_path, &resolved_buf)) |p| {
assert(p == &resolved_buf);
break syscall.finish();
} else switch (@as(std.c.E, @fromBackingInt(@intCast(std.c._errno().*)))) {
.INTR => {
try syscall.checkCancel();
continue;
},
.NAMETOOLONG => {
syscall.finish();
return error.NameTooLong;
},
.NOMEM => {
syscall.finish();
return error.SystemResources;
},
.IO => {
syscall.finish();
return error.InputOutput;
},
.ACCES, .LOOP, .NOENT, .NOTDIR => {
syscall.finish();
continue :it;
},
else => |err| {
syscall.finish();
return posix.unexpectedErrno(err);
},
}
}
const resolved = std.mem.sliceTo(&resolved_buf, 0);
if (resolved.len > out_buffer.len)
return error.NameTooLong;
@memcpy(out_buffer[0..resolved.len], resolved);
return resolved.len;
}
}
return error.FileNotFound;
},
.windows => {
// 若 ImagePathName 是符号链接,则其内容是符号链接本身的
// 路径,而非所指目标路径。我们需要符号链接所指的路径,
// 因此必须获取 realpath。
var path_name_w_buf = try wToPrefixedFileW(
null,
windows.peb().ProcessParameters.ImagePathName.sliceZ(),
.{},
);
const h_file = handle: {
if (OpenFile(path_name_w_buf.span(), .{
.dir = null,
.access_mask = .{
.GENERIC = .{ .READ = true },
.STANDARD = .{ .SYNCHRONIZE = true },
},
.creation = .OPEN,
.filter = .any,
})) |handle| {
break :handle handle;
} else |err| switch (err) {
error.WouldBlock => unreachable,
error.FileBusy => unreachable,
else => |e| return e,
}
};
defer windows.CloseHandle(h_file);
const wide_slice = try GetFinalPathNameByHandle(h_file, .{}, &path_name_w_buf.data);
const len = std.unicode.calcWtf8Len(wide_slice);
if (len > out_buffer.len)
return error.NameTooLong;
const end_index = std.unicode.wtf16LeToWtf8(out_buffer, wide_slice);
return end_index;
},
else => return error.OperationUnsupported,
}
}
fn fileWritePositional(
userdata: ?*anyopaque,
file: File,
header: []const u8,
data: []const []const u8,
splat: usize,
offset: u64,
) File.WritePositionalError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
if (header.len != 0) {
return writeFilePositionalWindows(file, header, offset);
}
for (data[0 .. data.len - 1]) |buf| {
if (buf.len == 0) continue;
return writeFilePositionalWindows(file, buf, offset);
}
const pattern = data[data.len - 1];
if (pattern.len == 0 or splat == 0) return 0;
return writeFilePositionalWindows(file, pattern, offset);
}
var iovecs: [max_iovecs_len]posix.iovec_const = undefined;
var iovlen: iovlen_t = 0;
addBuf(&iovecs, &iovlen, header);
for (data[0 .. data.len - 1]) |bytes| addBuf(&iovecs, &iovlen, bytes);
const pattern = data[data.len - 1];
var splat_backup_buffer: [splat_buffer_size]u8 = undefined;
if (iovecs.len - iovlen != 0) switch (splat) {
0 => {},
1 => addBuf(&iovecs, &iovlen, pattern),
else => switch (pattern.len) {
0 => {},
1 => {
const splat_buffer = &splat_backup_buffer;
const memset_len = @min(splat_buffer.len, splat);
const buf = splat_buffer[0..memset_len];
@memset(buf, pattern[0]);
addBuf(&iovecs, &iovlen, buf);
var remaining_splat = splat - buf.len;
while (remaining_splat > splat_buffer.len and iovecs.len - iovlen != 0) {
assert(buf.len == splat_buffer.len);
addBuf(&iovecs, &iovlen, splat_buffer);
remaining_splat -= splat_buffer.len;
}
addBuf(&iovecs, &iovlen, splat_buffer[0..@min(remaining_splat, splat_buffer.len)]);
},
else => for (0..@min(splat, iovecs.len - iovlen)) |_| {
addBuf(&iovecs, &iovlen, pattern);
},
},
};
if (iovlen == 0) return 0;
if (native_os == .wasi and !builtin.link_libc) {
var n_written: usize = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.fd_pwrite(file.handle, &iovecs, iovlen, offset, &n_written)) {
.SUCCESS => {
syscall.finish();
return n_written;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.AGAIN => |err| return errnoBug(err),
.BADF => return error.NotOpenForWriting,
.DESTADDRREQ => |err| return errnoBug(err), // 从未调用 `connect`。
.DQUOT => return error.DiskQuota,
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.PERM => return error.PermissionDenied,
.PIPE => return error.BrokenPipe,
.NOTCAPABLE => return error.AccessDenied,
.NXIO => return error.Unseekable,
.SPIPE => return error.Unseekable,
.OVERFLOW => return error.Unseekable,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const syscall: Syscall = try .start();
while (true) {
const rc = if (native_os == .haiku)
posix.system.writev_pos(file.handle, @bitCast(offset), &iovecs, @intCast(iovlen))
else
pwritev_sym(file.handle, &iovecs, @intCast(iovlen), @bitCast(offset));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.DESTADDRREQ => |err| return syscall.errnoBug(err), // 从未调用 `connect`。
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字句柄。
.BADF => return syscall.fail(error.NotOpenForWriting),
.AGAIN => return syscall.fail(error.WouldBlock),
.DQUOT => return syscall.fail(error.DiskQuota),
.FBIG => return syscall.fail(error.FileTooBig),
.IO => return syscall.fail(error.InputOutput),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.PERM => return syscall.fail(error.PermissionDenied),
.PIPE => return syscall.fail(error.BrokenPipe),
.BUSY => return syscall.fail(error.DeviceBusy),
.TXTBSY => return syscall.fail(error.FileBusy),
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn writeFilePositionalWindows(file: File, buffer: []const u8, offset: u64) File.WritePositionalError!usize {
assert(buffer.len != 0);
var iosb: windows.IO_STATUS_BLOCK = undefined;
const short_buffer_len = std.math.lossyCast(u32, buffer.len);
const signed_offset: windows.LARGE_INTEGER = @intCast(offset);
if (file.flags.nonblocking) {
var done: bool = false;
switch (windows.ntdll.NtWriteFile(
file.handle,
null, // 事件
flagApc,
&done, // APC 上下文
&iosb,
buffer.ptr,
short_buffer_len,
&signed_offset,
null, // 键
)) {
// 必须等待 APC 例程。
.PENDING, .SUCCESS => while (!done) {
// 一旦到达此处,就必须等操作完成后才能从
// 函数返回,从而释放对 iosb 的引用。
const alertable_syscall = AlertableSyscall.start() catch |err| switch (err) {
error.Canceled => |e| {
var cancel_iosb: windows.IO_STATUS_BLOCK = undefined;
_ = windows.ntdll.NtCancelIoFileEx(file.handle, &iosb, &cancel_iosb);
while (!done) waitForApcOrAlert();
return e;
},
};
waitForApcOrAlert();
alertable_syscall.finish();
},
else => |status| iosb.u.Status = status,
}
} else {
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtWriteFile(
file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&iosb,
buffer.ptr,
short_buffer_len,
&signed_offset,
null, // 键
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => try syscall.checkCancel(),
else => |status| {
syscall.finish();
iosb.u.Status = status;
return ntWriteFileResult(&iosb);
},
};
}
return ntWriteFileResult(&iosb);
}
fn fileWriteStreaming(
userdata: ?*anyopaque,
file: File,
header: []const u8,
data: []const []const u8,
splat: usize,
) File.Writer.Error!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
const buffer = windowsWriteBuffer(header, data, splat);
if (buffer.len == 0) return 0;
return fileWriteStreamingWindows(file, buffer);
}
var iovecs: [max_iovecs_len]posix.iovec_const = undefined;
var iovlen: iovlen_t = 0;
addBuf(&iovecs, &iovlen, header);
for (data[0 .. data.len - 1]) |bytes| addBuf(&iovecs, &iovlen, bytes);
const pattern = data[data.len - 1];
var splat_backup_buffer: [splat_buffer_size]u8 = undefined;
if (iovecs.len - iovlen != 0) switch (splat) {
0 => {},
1 => addBuf(&iovecs, &iovlen, pattern),
else => switch (pattern.len) {
0 => {},
1 => {
const splat_buffer = &splat_backup_buffer;
const memset_len = @min(splat_buffer.len, splat);
const buf = splat_buffer[0..memset_len];
@memset(buf, pattern[0]);
addBuf(&iovecs, &iovlen, buf);
var remaining_splat = splat - buf.len;
while (remaining_splat > splat_buffer.len and iovecs.len - iovlen != 0) {
assert(buf.len == splat_buffer.len);
addBuf(&iovecs, &iovlen, splat_buffer);
remaining_splat -= splat_buffer.len;
}
addBuf(&iovecs, &iovlen, splat_buffer[0..@min(remaining_splat, splat_buffer.len)]);
},
else => for (0..@min(splat, iovecs.len - iovlen)) |_| {
addBuf(&iovecs, &iovlen, pattern);
},
},
};
if (iovlen == 0) return 0;
if (native_os == .wasi and !builtin.link_libc) {
var n_written: usize = undefined;
const syscall: Syscall = try .start();
while (true) {
switch (std.os.wasi.fd_write(file.handle, &iovecs, iovlen, &n_written)) {
.SUCCESS => {
syscall.finish();
return n_written;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.AGAIN => |err| return errnoBug(err),
.BADF => return error.NotOpenForWriting, // 可能存在竞态条件。
.DESTADDRREQ => |err| return errnoBug(err), // 从未调用 `connect`。
.DQUOT => return error.DiskQuota,
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.PERM => return error.PermissionDenied,
.PIPE => return error.BrokenPipe,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.writev(file.handle, &iovecs, @intCast(iovlen));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.AGAIN => return error.WouldBlock,
.BADF => return error.NotOpenForWriting, // 可能存在竞态条件。
.DESTADDRREQ => |err| return errnoBug(err), // 从未调用 `connect`。
.DQUOT => return error.DiskQuota,
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOSPC => return error.NoSpaceLeft,
.PERM => return error.PermissionDenied,
.PIPE => return error.BrokenPipe,
.CONNRESET => |err| return errnoBug(err), // 不是套接字句柄。
.BUSY => return error.DeviceBusy,
.ACCES => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn fileWriteStreamingWindows(file: File, buffer: []const u8) File.Writer.Error!usize {
assert(buffer.len != 0);
var iosb: windows.IO_STATUS_BLOCK = undefined;
if (file.flags.nonblocking) {
var done: bool = false;
switch (windows.ntdll.NtWriteFile(
file.handle,
null, // 事件
flagApc,
&done, // APC 上下文
&iosb,
buffer.ptr,
@intCast(buffer.len),
null, // 字节偏移量
null, // 键
)) {
// 必须等待 APC 例程。
.PENDING, .SUCCESS => while (!done) {
// 一旦执行到这里,就必须等到操作完成后才可返回,从而释放对 io_status_block 的引用。
//
const alertable_syscall = AlertableSyscall.start() catch |err| switch (err) {
error.Canceled => |e| {
var cancel_iosb: windows.IO_STATUS_BLOCK = undefined;
_ = windows.ntdll.NtCancelIoFileEx(file.handle, &iosb, &cancel_iosb);
while (!done) waitForApcOrAlert();
return e;
},
};
waitForApcOrAlert();
alertable_syscall.finish();
},
else => |status| iosb.u.Status = status,
}
} else {
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtWriteFile(
file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&iosb,
buffer.ptr,
@intCast(buffer.len),
null, // 字节偏移量
null, // 键
)) {
.PENDING => unreachable, // 不可恢复:File 的非阻塞标志错误
.CANCELLED => try syscall.checkCancel(),
else => |status| {
syscall.finish();
iosb.u.Status = status;
break;
},
};
}
return ntWriteFileResult(&iosb);
}
fn fileWriteFileStreaming(
userdata: ?*anyopaque,
file: File,
header: []const u8,
file_reader: *File.Reader,
limit: Io.Limit,
) File.Writer.WriteFileError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const reader_buffered = file_reader.interface.buffered();
if (reader_buffered.len >= @backingInt(limit)) {
const n = try fileWriteStreaming(t, file, header, &.{limit.slice(reader_buffered)}, 1);
file_reader.interface.toss(n -| header.len);
return n;
}
const file_limit = @backingInt(limit) - reader_buffered.len;
const out_fd = file.handle;
const in_fd = file_reader.file.handle;
if (file_reader.size) |size| {
if (size - file_reader.pos == 0) {
if (reader_buffered.len != 0) {
const n = try fileWriteStreaming(t, file, header, &.{limit.slice(reader_buffered)}, 1);
file_reader.interface.toss(n -| header.len);
return n;
} else {
return error.EndOfStream;
}
}
}
if (native_os == .freebsd) sf: {
// 尝试在 FreeBSD 上使用 sendfile。
if (@atomicLoad(UseSendfile, &t.use_sendfile, .monotonic) == .disabled) break :sf;
const offset = std.math.cast(std.c.off_t, file_reader.pos) orelse break :sf;
var hdtr_data: std.c.sf_hdtr = undefined;
var headers: [2]posix.iovec_const = undefined;
var headers_i: u8 = 0;
if (header.len != 0) {
headers[headers_i] = .{ .base = header.ptr, .len = header.len };
headers_i += 1;
}
if (reader_buffered.len != 0) {
headers[headers_i] = .{ .base = reader_buffered.ptr, .len = reader_buffered.len };
headers_i += 1;
}
const hdtr: ?*std.c.sf_hdtr = if (headers_i == 0) null else b: {
hdtr_data = .{
.headers = &headers,
.hdr_cnt = headers_i,
.trailers = null,
.trl_cnt = 0,
};
break :b &hdtr_data;
};
var sbytes: std.c.off_t = 0;
const nbytes: usize = @min(file_limit, std.math.maxInt(usize));
const flags = 0;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(std.c.sendfile(in_fd, out_fd, offset, nbytes, hdtr, &sbytes, flags))) {
.SUCCESS => {
syscall.finish();
break;
},
.INVAL, .OPNOTSUPP, .NOTSOCK, .NOSYS => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseSendfile, &t.use_sendfile, .disabled, .monotonic);
return 0;
},
.INTR, .BUSY => {
if (sbytes == 0) {
try syscall.checkCancel();
continue;
} else {
// 即使正在取消,也已经产生副作用,因此最好将这些副作用报告给调用方。
//
//
syscall.finish();
break;
}
},
.AGAIN => {
syscall.finish();
if (sbytes == 0) return error.WouldBlock;
break;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.NOTCONN => return error.BrokenPipe,
.IO => return error.InputOutput,
.PIPE => return error.BrokenPipe,
.NOBUFS => return error.SystemResources,
.BADF => |err| errnoBug(err),
.FAULT => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
// 让调用代码有机会先观察错误,
// 再尝试其他方式。
@atomicStore(UseSendfile, &t.use_sendfile, .disabled, .monotonic);
return 0;
},
}
}
if (sbytes == 0) {
file_reader.size = file_reader.pos;
return error.EndOfStream;
}
const ubytes: usize = @intCast(sbytes);
file_reader.interface.toss(ubytes -| header.len);
return ubytes;
}
if (is_darwin) sf: {
// 在 macOS 上尝试使用 sendfile。
if (@atomicLoad(UseSendfile, &t.use_sendfile, .monotonic) == .disabled) break :sf;
const offset = std.math.cast(std.c.off_t, file_reader.pos) orelse break :sf;
var hdtr_data: std.c.sf_hdtr = undefined;
var headers: [2]posix.iovec_const = undefined;
var headers_i: u8 = 0;
if (header.len != 0) {
headers[headers_i] = .{ .base = header.ptr, .len = header.len };
headers_i += 1;
}
if (reader_buffered.len != 0) {
headers[headers_i] = .{ .base = reader_buffered.ptr, .len = reader_buffered.len };
headers_i += 1;
}
const hdtr: ?*std.c.sf_hdtr = if (headers_i == 0) null else b: {
hdtr_data = .{
.headers = &headers,
.hdr_cnt = headers_i,
.trailers = null,
.trl_cnt = 0,
};
break :b &hdtr_data;
};
const max_count = std.math.maxInt(i32); // 避免 EINVAL。
var len: std.c.off_t = @min(file_limit, max_count);
const flags = 0;
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(std.c.sendfile(in_fd, out_fd, offset, &len, hdtr, flags))) {
.SUCCESS => {
syscall.finish();
break;
},
.OPNOTSUPP, .NOTSOCK, .NOSYS => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseSendfile, &t.use_sendfile, .disabled, .monotonic);
return 0;
},
.INTR => {
if (len == 0) {
try syscall.checkCancel();
continue;
} else {
// 即使正在取消,也已经产生副作用,因此最好将这些副作用报告给调用方。
//
//
syscall.finish();
break;
}
},
.AGAIN => {
syscall.finish();
if (len == 0) return error.WouldBlock;
break;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.NOTCONN => return error.BrokenPipe,
.IO => return error.InputOutput,
.PIPE => return error.BrokenPipe,
.BADF => |err| errnoBug(err),
.FAULT => |err| errnoBug(err),
.INVAL => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
// 让调用代码有机会先观察错误,
// 再尝试其他方式。
@atomicStore(UseSendfile, &t.use_sendfile, .disabled, .monotonic);
return 0;
},
}
}
if (len == 0) {
file_reader.size = file_reader.pos;
return error.EndOfStream;
}
const u_len: usize = @bitCast(len);
file_reader.interface.toss(u_len -| header.len);
return u_len;
}
if (native_os == .linux) sf: {
// 尝试在 Linux 上使用 sendfile。
if (@atomicLoad(UseSendfile, &t.use_sendfile, .monotonic) == .disabled) break :sf;
// Linux sendfile 不支持头部。
if (header.len != 0 or reader_buffered.len != 0) {
const n = try fileWriteStreaming(t, file, header, &.{limit.slice(reader_buffered)}, 1);
file_reader.interface.toss(n -| header.len);
return n;
}
const max_count = 0x7ffff000; // 避免 EINVAL。
var off: std.os.linux.off_t = undefined;
const off_ptr: ?*std.os.linux.off_t, const count: usize = switch (file_reader.mode) {
.positional => o: {
const size = file_reader.getSize() catch |err| switch (err) {
error.Canceled => |e| return e,
else => break :sf,
};
off = std.math.cast(std.os.linux.off_t, file_reader.pos) orelse return error.ReadFailed;
break :o .{ &off, @min(@backingInt(limit), size - file_reader.pos, max_count) };
},
.streaming => .{ null, limit.minInt(max_count) },
.streaming_simple, .positional_simple => break :sf,
.failure => return error.ReadFailed,
};
const syscall: Syscall = try .start();
const n: usize = while (true) {
const rc = sendfile_sym(out_fd, in_fd, off_ptr, count);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break @intCast(rc);
},
.NOSYS, .INVAL => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseSendfile, &t.use_sendfile, .disabled, .monotonic);
return 0;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.NOTCONN => return error.BrokenPipe, // `out_fd` 是未连接的套接字
.AGAIN => return error.WouldBlock,
.IO => return error.InputOutput,
.PIPE => return error.BrokenPipe,
.NOMEM => return error.SystemResources,
.NXIO, .SPIPE => {
file_reader.mode = file_reader.mode.toStreaming();
const pos = file_reader.pos;
if (pos != 0) {
file_reader.pos = 0;
file_reader.seekBy(@intCast(pos)) catch {
file_reader.mode = .failure;
return error.ReadFailed;
};
}
return 0;
},
.BADF => |err| errnoBug(err), // 始终存在竞态条件。
.FAULT => |err| errnoBug(err), // 段错误。
.OVERFLOW => |err| errnoBug(err), // 避免传入过大的 `count`。
else => |err| posix.unexpectedErrno(err),
});
// 让调用代码有机会先观察错误,
// 再尝试其他方式。
@atomicStore(UseSendfile, &t.use_sendfile, .disabled, .monotonic);
return 0;
},
}
};
if (n == 0) {
file_reader.size = file_reader.pos;
return error.EndOfStream;
}
file_reader.pos += n;
return n;
}
if (have_copy_file_range) cfr: {
if (@atomicLoad(UseCopyFileRange, &t.use_copy_file_range, .monotonic) == .disabled) break :cfr;
if (header.len != 0 or reader_buffered.len != 0) {
const n = try fileWriteStreaming(t, file, header, &.{limit.slice(reader_buffered)}, 1);
file_reader.interface.toss(n -| header.len);
return n;
}
var len: usize = @backingInt(limit);
var off_in: i64 = undefined;
const off_in_ptr: ?*i64 = switch (file_reader.mode) {
.positional_simple, .streaming_simple => return error.Unimplemented,
.positional => p: {
len = @min(len, std.math.maxInt(usize) - file_reader.pos);
off_in = @intCast(file_reader.pos);
break :p &off_in;
},
.streaming => null,
.failure => return error.ReadFailed,
};
const n: usize = switch (native_os) {
.linux => n: {
const syscall: Syscall = try .start();
while (true) {
const rc = linux_copy_file_range_sys.copy_file_range(in_fd, off_in_ptr, out_fd, null, len, 0);
switch (linux_copy_file_range_sys.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :n @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
.OPNOTSUPP, .INVAL, .NOSYS => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.OVERFLOW => |err| errnoBug(err), // 避免传入过大的计数。
.PERM => return error.PermissionDenied,
.BUSY => return error.DeviceBusy,
.TXTBSY => return error.FileBusy,
// copy_file_range 仍可能有效,但不适用于
// 这一对文件描述符。
.XDEV => return error.Unimplemented,
.ISDIR => |err| errnoBug(err),
.BADF => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
}
}
},
.freebsd => n: {
const syscall: Syscall = try .start();
while (true) {
const rc = std.c.copy_file_range(in_fd, off_in_ptr, out_fd, null, @backingInt(limit), 0);
switch (std.c.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :n @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
.OPNOTSUPP, .INVAL, .NOSYS => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.INTEGRITY => return error.CorruptedData,
.NOSPC => return error.NoSpaceLeft,
.ISDIR => |err| errnoBug(err),
.BADF => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
}
}
},
else => comptime unreachable,
};
if (n == 0) {
file_reader.size = file_reader.pos;
return error.EndOfStream;
}
file_reader.pos += n;
return n;
}
return error.Unimplemented;
}
fn netWriteFile(
userdata: ?*anyopaque,
socket_handle: net.Socket.Handle,
header: []const u8,
file_reader: *File.Reader,
limit: Io.Limit,
) net.Stream.Writer.WriteFileError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
_ = socket_handle;
_ = header;
_ = file_reader;
_ = limit;
// TODO 实现 netWriteFile
return error.Unimplemented;
}
fn fileWriteFilePositional(
userdata: ?*anyopaque,
file: File,
header: []const u8,
file_reader: *File.Reader,
limit: Io.Limit,
offset: u64,
) File.WriteFilePositionalError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const reader_buffered = file_reader.interface.buffered();
if (reader_buffered.len >= @backingInt(limit)) {
const n = try fileWritePositional(t, file, header, &.{limit.slice(reader_buffered)}, 1, offset);
file_reader.interface.toss(n -| header.len);
return n;
}
const out_fd = file.handle;
const in_fd = file_reader.file.handle;
if (file_reader.size) |size| {
if (size - file_reader.pos == 0) {
if (reader_buffered.len != 0) {
const n = try fileWritePositional(t, file, header, &.{limit.slice(reader_buffered)}, 1, offset);
file_reader.interface.toss(n -| header.len);
return n;
} else {
return error.EndOfStream;
}
}
}
if (have_copy_file_range) cfr: {
if (@atomicLoad(UseCopyFileRange, &t.use_copy_file_range, .monotonic) == .disabled) break :cfr;
if (header.len != 0 or reader_buffered.len != 0) {
const n = try fileWritePositional(t, file, header, &.{limit.slice(reader_buffered)}, 1, offset);
file_reader.interface.toss(n -| header.len);
return n;
}
var len: usize = @min(@backingInt(limit), std.math.maxInt(usize) - offset);
var off_in: i64 = undefined;
const off_in_ptr: ?*i64 = switch (file_reader.mode) {
.positional_simple, .streaming_simple => return error.Unimplemented,
.positional => p: {
len = @min(len, std.math.maxInt(usize) - file_reader.pos);
off_in = @intCast(file_reader.pos);
break :p &off_in;
},
.streaming => null,
.failure => return error.ReadFailed,
};
var off_out: i64 = @intCast(offset);
const n: usize = switch (native_os) {
.linux => n: {
const syscall: Syscall = try .start();
while (true) {
const rc = linux_copy_file_range_sys.copy_file_range(in_fd, off_in_ptr, out_fd, &off_out, len, 0);
switch (linux_copy_file_range_sys.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :n @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
.OPNOTSUPP, .INVAL, .NOSYS => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.NOMEM => return error.SystemResources,
.NOSPC => return error.NoSpaceLeft,
.OVERFLOW => |err| errnoBug(err), // 避免传入过大的计数。
.NXIO => return error.Unseekable,
.SPIPE => return error.Unseekable,
.PERM => return error.PermissionDenied,
.TXTBSY => return error.FileBusy,
// copy_file_range 仍可能有效,但不适用于
// 这一对文件描述符。
.XDEV => return error.Unimplemented,
.ISDIR => |err| errnoBug(err),
.BADF => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
}
}
},
.freebsd => n: {
const syscall: Syscall = try .start();
while (true) {
const rc = std.c.copy_file_range(in_fd, off_in_ptr, out_fd, &off_out, @backingInt(limit), 0);
switch (std.c.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :n @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
.OPNOTSUPP, .INVAL, .NOSYS => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.FBIG => return error.FileTooBig,
.IO => return error.InputOutput,
.INTEGRITY => return error.CorruptedData,
.NOSPC => return error.NoSpaceLeft,
.OVERFLOW => return error.Unseekable,
.NXIO => return error.Unseekable,
.SPIPE => return error.Unseekable,
.ISDIR => |err| errnoBug(err),
.BADF => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
@atomicStore(UseCopyFileRange, &t.use_copy_file_range, .disabled, .monotonic);
return 0;
},
}
}
},
else => comptime unreachable,
};
if (n == 0) {
file_reader.size = file_reader.pos;
return error.EndOfStream;
}
file_reader.pos += n;
return n;
}
if (is_darwin) fcf: {
if (@atomicLoad(UseFcopyfile, &t.use_fcopyfile, .monotonic) == .disabled) break :fcf;
if (file_reader.pos != 0) break :fcf;
if (offset != 0) break :fcf;
if (limit != .unlimited) break :fcf;
const size = file_reader.getSize() catch |err| switch (err) {
error.Canceled => |e| return e,
else => break :fcf,
};
if (header.len != 0 or reader_buffered.len != 0) {
const n = try fileWritePositional(t, file, header, &.{limit.slice(reader_buffered)}, 1, offset);
file_reader.interface.toss(n -| header.len);
return n;
}
const syscall: Syscall = try .start();
while (true) {
const rc = std.c.fcopyfile(in_fd, out_fd, null, .{ .DATA = true });
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.OPNOTSUPP => {
// 在尝试其他操作之前,
// 给予调用代码观察状态的机会。
syscall.finish();
@atomicStore(UseFcopyfile, &t.use_fcopyfile, .disabled, .monotonic);
return 0;
},
else => |e| {
syscall.finish();
assert(error.Unexpected == switch (e) {
.NOMEM => return error.SystemResources,
.INVAL => |err| errnoBug(err),
else => |err| posix.unexpectedErrno(err),
});
return 0;
},
}
}
file_reader.pos = size;
return size;
}
return error.Unimplemented;
}
fn nowPosix(clock: Io.Clock) Io.Timestamp {
const clock_id: posix.clockid_t = clockToPosix(clock);
var timespec: posix.timespec = undefined;
switch (posix.errno(posix.system.clock_gettime(clock_id, ×pec))) {
.SUCCESS => return timestampFromPosix(×pec),
else => return .zero,
}
}
fn now(userdata: ?*anyopaque, clock: Io.Clock) Io.Timestamp {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return switch (native_os) {
.windows => nowWindows(clock),
.wasi => nowWasi(clock),
else => nowPosix(clock),
};
}
fn clockResolution(userdata: ?*anyopaque, clock: Io.Clock) Io.Clock.ResolutionError!Io.Duration {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
return switch (native_os) {
.windows => switch (clock) {
.awake, .boot, .real => {
// 无需缓存 QPF,因为其内部只是读取 KUSER_SHARED_DATA 内存,
// 该只读信息页由内核更新,并映射到所有进程:
// https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/ns-ntddk-kuser_shared_data
// https://www.geoffchappell.com/studies/windows/km/ntoskrnl/inc/api/ntexapi_x/kuser_shared_data/index.htm
var qpf: windows.LARGE_INTEGER = undefined;
if (!windows.ntdll.RtlQueryPerformanceFrequency(&qpf).toBool()) {
recoverableOsBugDetected();
return .zero;
}
// 10Mhz,即每 100ns 一个 qpc 时钟滴答,是足够常见的 QPF 值,因此可针对它优化。
// https://github.com/microsoft/STL/blob/785143a0c73f030238ef618890fd4d6ae2b3a3a0/stl/inc/chrono#L694-L701
const common_qpf = 10_000_000;
if (qpf == common_qpf) return .fromNanoseconds(std.time.ns_per_s / common_qpf);
// 使用定点运算转换为纳秒。
const scale = @as(u64, std.time.ns_per_s << 32) / @as(u32, @intCast(qpf));
const result = scale >> 32;
return .fromNanoseconds(result);
},
.cpu_process, .cpu_thread => return error.ClockUnavailable,
},
.wasi => {
if (builtin.link_libc) return clockResolutionPosix(clock);
var ns: std.os.wasi.timestamp_t = undefined;
return switch (std.os.wasi.clock_res_get(clockToWasi(clock), &ns)) {
.SUCCESS => .fromNanoseconds(ns),
.INVAL => return error.ClockUnavailable,
else => |err| return posix.unexpectedErrno(err),
};
},
else => return clockResolutionPosix(clock),
};
}
fn clockResolutionPosix(clock: Io.Clock) Io.Clock.ResolutionError!Io.Duration {
const clock_id: posix.clockid_t = clockToPosix(clock);
var timespec: posix.timespec = undefined;
return switch (posix.errno(posix.system.clock_getres(clock_id, ×pec))) {
.SUCCESS => .fromNanoseconds(nanosecondsFromPosix(×pec)),
.INVAL => return error.ClockUnavailable,
else => |err| return posix.unexpectedErrno(err),
};
}
fn nowWindows(clock: Io.Clock) Io.Timestamp {
switch (clock) {
.real => {
// RtlGetSystemTimePrecise() 的精度为 100 纳秒,
// 使用 NTFS/Windows 纪元,即 1601-01-01。
const epoch_ns = std.time.epoch.windows * std.time.ns_per_s;
return .{ .nanoseconds = @as(i96, windows.ntdll.RtlGetSystemTimePrecise()) * 100 + epoch_ns };
},
.awake, .boot => {
// 无需缓存 QPF,因为其内部只是读取 KUSER_SHARED_DATA 内存,
// 该只读信息页由内核更新,并映射到所有进程:
// https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/ns-ntddk-kuser_shared_data
// https://www.geoffchappell.com/studies/windows/km/ntoskrnl/inc/api/ntexapi_x/kuser_shared_data/index.htm
const qpf: u64 = qpf: {
var qpf: windows.LARGE_INTEGER = undefined;
assert(windows.ntdll.RtlQueryPerformanceFrequency(&qpf).toBool());
break :qpf @bitCast(qpf);
};
// Windows 上的 QPC 在 XP/2000 及之后不会失败,并包含挂起时间。
const qpc: u64 = qpc: {
var qpc: windows.LARGE_INTEGER = undefined;
assert(windows.ntdll.RtlQueryPerformanceCounter(&qpc).toBool());
break :qpc @bitCast(qpc);
};
// 10Mhz,即每 100ns 一个 qpc 时钟滴答,是足够常见的 QPF 值,因此可针对它优化。
// https://github.com/microsoft/STL/blob/785143a0c73f030238ef618890fd4d6ae2b3a3a0/stl/inc/chrono#L694-L701
const common_qpf = 10_000_000;
if (qpf == common_qpf) return .{ .nanoseconds = qpc * (std.time.ns_per_s / common_qpf) };
// 使用定点运算转换为纳秒。
const scale = @as(u64, std.time.ns_per_s << 32) / @as(u32, @intCast(qpf));
const result = (@as(u96, qpc) * scale) >> 32;
return .{ .nanoseconds = @intCast(result) };
},
.cpu_process => {
const handle = windows.GetCurrentProcess();
var times: windows.KERNEL_USER_TIMES = undefined;
// https://github.com/reactos/reactos/blob/master/ntoskrnl/ps/query.c#L442-L485
if (windows.ntdll.NtQueryInformationProcess(
handle,
.Times,
×,
@sizeOf(windows.KERNEL_USER_TIMES),
null,
) != .SUCCESS) return .zero;
const sum = @as(i96, times.UserTime) + @as(i96, times.KernelTime);
return .{ .nanoseconds = sum * 100 };
},
.cpu_thread => {
const handle = windows.GetCurrentThread();
var times: windows.KERNEL_USER_TIMES = undefined;
// https://github.com/reactos/reactos/blob/master/ntoskrnl/ps/query.c#L2971-L3019
if (windows.ntdll.NtQueryInformationThread(
handle,
.Times,
×,
@sizeOf(windows.KERNEL_USER_TIMES),
null,
) != .SUCCESS) return .zero;
const sum = @as(i96, times.UserTime) + @as(i96, times.KernelTime);
return .{ .nanoseconds = sum * 100 };
},
}
}
fn nowWasi(clock: Io.Clock) Io.Timestamp {
var ns: std.os.wasi.timestamp_t = undefined;
const err = std.os.wasi.clock_time_get(clockToWasi(clock), 1, &ns);
if (err != .SUCCESS) return .zero;
return .fromNanoseconds(ns);
}
fn sleep(userdata: ?*anyopaque, timeout: Io.Timeout) Io.Cancelable!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (use_parking_sleep) return parking_sleep.sleep(timeout);
if (native_os == .wasi) return sleepWasi(t, timeout);
if (@TypeOf(posix.system.clock_nanosleep) != void) return sleepPosix(timeout);
return sleepNanosleep(t, timeout);
}
fn sleepPosix(timeout: Io.Timeout) Io.Cancelable!void {
const clock_id: posix.clockid_t = clockToPosix(switch (timeout) {
.none => .awake,
.duration => |d| d.clock,
.deadline => |d| d.clock,
});
const deadline_nanoseconds: i96 = switch (timeout) {
.none => std.math.maxInt(i96),
.duration => |duration| duration.raw.nanoseconds,
.deadline => |deadline| deadline.raw.nanoseconds,
};
var timespec: posix.timespec = timestampToPosix(deadline_nanoseconds);
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.clock_nanosleep(clock_id, .{ .ABSTIME = switch (timeout) {
.none, .duration => false,
.deadline => true,
} }, ×pec, ×pec);
// POSIX 标准的 libc clock_nanosleep() 直接返回*正数* errno 值。
switch (if (builtin.link_libc) @as(posix.E, @fromBackingInt(@intCast(rc))) else posix.errno(rc)) {
.INTR => {
try syscall.checkCancel();
continue;
},
// 处理 SUCCESS、时钟不可用及意外错误。
// 用户在到达此处之前有机会检查时钟分辨率,
// 该检查会报告 0,因此这仍是合法的
// 休眠时长。
else => {
syscall.finish();
return;
},
}
}
}
fn sleepWasi(t: *Threaded, timeout: Io.Timeout) Io.Cancelable!void {
const t_io = io(t);
const w = std.os.wasi;
const clock: w.subscription_clock_t = if (timeout.toDurationFromNow(t_io)) |d| .{
.id = clockToWasi(d.clock),
.timeout = std.math.lossyCast(u64, d.raw.nanoseconds),
.precision = 0,
.flags = 0,
} else .{
.id = .MONOTONIC,
.timeout = std.math.maxInt(u64),
.precision = 0,
.flags = 0,
};
const in: w.subscription_t = .{
.userdata = 0,
.u = .{
.tag = .CLOCK,
.u = .{ .clock = clock },
},
};
var event: w.event_t = undefined;
var nevents: usize = undefined;
const syscall: Syscall = try .start();
_ = w.poll_oneoff(&in, &event, 1, &nevents);
syscall.finish();
}
fn sleepNanosleep(t: *Threaded, timeout: Io.Timeout) Io.Cancelable!void {
const t_io = io(t);
const sec_type = @typeInfo(posix.timespec).@"struct".field_types[0];
const nsec_type = @typeInfo(posix.timespec).@"struct".field_types[1];
var timespec: posix.timespec = t: {
const d = timeout.toDurationFromNow(t_io) orelse break :t .{
.sec = std.math.maxInt(sec_type),
.nsec = std.math.maxInt(nsec_type),
};
break :t timestampToPosix(d.raw.toNanoseconds());
};
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.nanosleep(×pec, ×pec))) {
.INTR => {
try syscall.checkCancel();
continue;
},
// 此分支同时处理成功及非预期错误。
else => return syscall.finish(),
}
}
}
fn netListenIpPosix(
userdata: ?*anyopaque,
address: *const IpAddress,
options: IpAddress.ListenOptions,
) IpAddress.ListenError!net.Socket {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const family = posixAddressFamily(address);
const socket_fd = try openSocketPosix(family, .{ .mode = options.mode, .protocol = options.protocol });
errdefer closeFd(socket_fd);
if (options.reuse_address) {
try setSocketOptionPosix(socket_fd, posix.SOL.SOCKET, posix.SO.REUSEADDR, 1);
if (@hasDecl(posix.SO, "REUSEPORT"))
try setSocketOptionPosix(socket_fd, posix.SOL.SOCKET, posix.SO.REUSEPORT, 1);
}
var storage: PosixAddress = undefined;
var addr_len = addressToPosix(address, &storage);
try posixBind(socket_fd, &storage.any, addr_len);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.listen(socket_fd, options.kernel_backlog))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ADDRINUSE => return syscall.fail(error.AddressInUse),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
else => |err| return syscall.unexpectedErrno(err),
}
}
try posixGetSockName(socket_fd, &storage.any, &addr_len);
return .{ .handle = socket_fd, .address = addressFromPosix(&storage) };
}
fn netListenIpWindows(
userdata: ?*anyopaque,
address: *const IpAddress,
options: IpAddress.ListenOptions,
) IpAddress.ListenError!net.Socket {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const family = posixAddressFamily(address);
const socket_handle = try openSocketAfd(family, .{ .mode = options.mode, .protocol = options.protocol });
errdefer windows.CloseHandle(socket_handle);
if (options.reuse_address) try setSocketOptionAfd(socket_handle, ws2_32.SOL.SOCKET, ws2_32.SO.REUSEADDR, true);
const bound_address = try bindSocketIpAfd(socket_handle, address, .Passive);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.START_LISTEN,
.in = @ptrCast(&windows.AFD.LISTEN_INFO{
.UseSAN = .FALSE,
.MaximumConnectionQueue = options.kernel_backlog,
.UseDelayedAcceptance = .FALSE,
}),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
return .{ .handle = socket_handle, .address = bound_address };
}
fn netListenUnixPosix(
userdata: ?*anyopaque,
address: *const net.UnixAddress,
options: net.UnixAddress.ListenOptions,
) net.UnixAddress.ListenError!net.Socket.Handle {
if (!net.has_unix_sockets) return error.AddressFamilyUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const socket_fd = openSocketPosix(posix.AF.UNIX, .{ .mode = .stream }) catch |err| switch (err) {
error.ProtocolUnsupportedBySystem => return error.AddressFamilyUnsupported,
error.ProtocolUnsupportedByAddressFamily => return error.AddressFamilyUnsupported,
error.SocketModeUnsupported => return error.AddressFamilyUnsupported,
error.OptionUnsupported => return error.Unexpected,
else => |e| return e,
};
errdefer closeFd(socket_fd);
var storage: UnixAddress = undefined;
const addr_len = addressUnixToPosix(address, &storage);
try posixBindUnix(socket_fd, &storage.any, addr_len);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.listen(socket_fd, options.kernel_backlog))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ADDRINUSE => return syscall.fail(error.AddressInUse),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
else => |err| return syscall.unexpectedErrno(err),
}
}
return socket_fd;
}
fn netListenUnixWindows(
userdata: ?*anyopaque,
address: *const net.UnixAddress,
options: net.UnixAddress.ListenOptions,
) net.UnixAddress.ListenError!net.Socket.Handle {
if (!net.has_unix_sockets) return error.AddressFamilyUnsupported;
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const is_abstract = address.isAbstract();
const wps = if (!is_abstract) sliceToPrefixedFileW(null, address.path, .{
.allow_relative = false,
}) catch |err| switch (err) {
error.NameTooLong, error.BadPathName => return error.AddressUnavailable,
else => |e| return e,
} else undefined;
const socket_handle = openSocketAfd(ws2_32.AF.UNIX, .{ .mode = .stream }) catch |err| switch (err) {
error.ProtocolUnsupportedByAddressFamily => return error.AddressFamilyUnsupported,
else => |e| return e,
};
errdefer windows.CloseHandle(socket_handle);
if (!is_abstract) try socketOptionAfd(socket_handle, .special, 0, ws2_32.SO.UNIX_PATH, @constCast(
@as([]const u8, @ptrCast(&windows.AFD.SOCKOPT_INFO.UNIX_PATH{
.Path = wps.data,
}))[0 .. @offsetOf(windows.AFD.SOCKOPT_INFO.UNIX_PATH, "Path") + @sizeOf(windows.WCHAR) * wps.len],
));
try bindSocketUnixAfd(socket_handle, address);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.START_LISTEN,
.in = @ptrCast(&windows.AFD.LISTEN_INFO{
.UseSAN = .FALSE,
.MaximumConnectionQueue = options.kernel_backlog,
.UseDelayedAcceptance = .FALSE,
}),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
return socket_handle;
}
fn posixBindUnix(
fd: posix.socket_t,
addr: *const posix.sockaddr,
addr_len: posix.socklen_t,
) !void {
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.bind(fd, addr, addr_len))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.ADDRINUSE => return error.AddressInUse,
.AFNOSUPPORT => return error.AddressFamilyUnsupported,
.ADDRNOTAVAIL => return error.AddressUnavailable,
.NOMEM => return error.SystemResources,
.LOOP => return error.SymLinkLoop,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.ROFS => return error.ReadOnlyFileSystem,
.PERM => return error.PermissionDenied,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => |err| return errnoBug(err), // 无效参数
.NOTSOCK => |err| return errnoBug(err), // 无效的 `sockfd`
.FAULT => |err| return errnoBug(err), // 无效的 `addr` 指针
.NAMETOOLONG => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn posixBind(
socket_fd: posix.socket_t,
addr: *const posix.sockaddr,
addr_len: posix.socklen_t,
) !void {
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.bind(socket_fd, addr, addr_len))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => return error.AccessDenied,
.ADDRINUSE => return error.AddressInUse,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.INVAL => |err| return errnoBug(err), // 无效参数
.NOTSOCK => |err| return errnoBug(err), // 无效的 `sockfd`
.AFNOSUPPORT => return error.AddressFamilyUnsupported,
.ADDRNOTAVAIL => return error.AddressUnavailable,
.FAULT => |err| return errnoBug(err), // 无效的 `addr` 指针
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn posixConnect(
socket_fd: posix.socket_t,
addr: *const posix.sockaddr,
addr_len: posix.socklen_t,
) !void {
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.connect(socket_fd, addr, addr_len))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ADDRNOTAVAIL => return syscall.fail(error.AddressUnavailable),
.AFNOSUPPORT => return syscall.fail(error.AddressFamilyUnsupported),
.AGAIN, .INPROGRESS => return syscall.fail(error.WouldBlock),
.ALREADY => return syscall.fail(error.ConnectionPending),
.CONNREFUSED => return syscall.fail(error.ConnectionRefused),
.CONNRESET => return syscall.fail(error.ConnectionResetByPeer),
.HOSTUNREACH => return syscall.fail(error.HostUnreachable),
.NETUNREACH => return syscall.fail(error.NetworkUnreachable),
.TIMEDOUT => return syscall.fail(error.Timeout),
.ACCES => return syscall.fail(error.AccessDenied),
.NETDOWN => return syscall.fail(error.NetworkDown),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
.CONNABORTED => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.ISCONN => |err| return syscall.errnoBug(err),
.NOENT => |err| return syscall.errnoBug(err),
.NOTSOCK => |err| return syscall.errnoBug(err),
.PERM => |err| return syscall.errnoBug(err),
.PROTOTYPE => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
};
}
fn posixConnectUnix(
fd: posix.socket_t,
addr: *const posix.sockaddr,
addr_len: posix.socklen_t,
) !void {
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.connect(fd, addr, addr_len))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.AFNOSUPPORT => return error.AddressFamilyUnsupported,
.AGAIN => return error.WouldBlock,
.INPROGRESS => return error.WouldBlock,
.ACCES => return error.AccessDenied,
.LOOP => return error.SymLinkLoop,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.ROFS => return error.ReadOnlyFileSystem,
.PERM => return error.PermissionDenied,
.CONNREFUSED => return error.ConnectionRefused,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.CONNABORTED => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.ISCONN => |err| return errnoBug(err),
.NOTSOCK => |err| return errnoBug(err),
.PROTOTYPE => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn posixGetSockName(
socket_fd: posix.fd_t,
addr: *posix.sockaddr,
addr_len: *posix.socklen_t,
) !void {
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.getsockname(socket_fd, addr, addr_len))) {
.SUCCESS => {
syscall.finish();
break;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.FAULT => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err), // 无效参数
.NOTSOCK => |err| return errnoBug(err), // 始终存在竞态条件
.NOBUFS => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn setSocketOptionPosix(fd: posix.fd_t, level: i32, opt_name: u32, option: u32) !void {
const o: []const u8 = @ptrCast(&option);
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.setsockopt(fd, level, opt_name, o.ptr, @intCast(o.len)))) {
.SUCCESS => {
syscall.finish();
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOTSOCK => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn setSocketOptionAfd(socket: net.Socket.Handle, level: i32, opt_name: u32, opt_val: anytype) !void {
try socketOptionAfd(socket, .set, level, opt_name, @ptrCast(@constCast(&opt_val)));
}
fn socketOptionAfd(socket: net.Socket.Handle, mode: windows.AFD.SOCKOPT_INFO.Mode, level: i32, opt_name: u32, opt_val: []u8) !void {
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.SOCKOPT,
.in = @ptrCast(&windows.AFD.SOCKOPT_INFO{
.mode = mode,
.level = level,
.optname = opt_name,
.optval = opt_val.ptr,
.optlen = opt_val.len,
}),
})).u.Status) {
.SUCCESS => return,
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
}
fn netConnectIpPosix(
userdata: ?*anyopaque,
address: *const IpAddress,
options: IpAddress.ConnectOptions,
) IpAddress.ConnectError!net.Socket {
if (!have_networking) return error.NetworkDown;
if (options.timeout != .none) @panic("TODO implement netConnectIpPosix with timeout");
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const family = posixAddressFamily(address);
const socket_fd = try openSocketPosix(family, .{ .mode = options.mode, .protocol = options.protocol });
errdefer closeFd(socket_fd);
var storage: PosixAddress = undefined;
var addr_len = addressToPosix(address, &storage);
try posixConnect(socket_fd, &storage.any, addr_len);
try posixGetSockName(socket_fd, &storage.any, &addr_len);
return .{ .handle = socket_fd, .address = addressFromPosix(&storage) };
}
fn netConnectIpWindows(
userdata: ?*anyopaque,
address: *const IpAddress,
options: IpAddress.ConnectOptions,
) IpAddress.ConnectError!net.Socket {
if (!have_networking) return error.NetworkDown;
if (options.timeout != .none) @panic("TODO implement netConnectIpWindows with timeout");
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const family = posixAddressFamily(address);
const socket_handle = try openSocketAfd(family, .{ .mode = options.mode, .protocol = options.protocol });
errdefer windows.CloseHandle(socket_handle);
try setSocketOptionAfd(socket_handle, ws2_32.SOL.SOCKET, ws2_32.SO.REUSE_UNICASTPORT, true);
const bound_address = bindSocketIpAfd(socket_handle, &switch (address.*) {
.ip4 => .{ .ip4 = .unspecified(0) },
.ip6 => .{ .ip6 = .unspecified(0) },
}, .Active) catch |err| switch (err) {
error.AddressInUse => return error.Unexpected,
else => |e| return e,
};
const Storage = extern struct { Reserved0: [3]usize = @splat(0), Address: PosixAddress };
var storage: Storage = .{ .Address = undefined };
const addr_len = addressToPosix(address, &storage.Address);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.CONNECT,
.in = @as([]const u8, @ptrCast(&storage))[0 .. @offsetOf(Storage, "Address") + addr_len],
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.CONNECTION_REFUSED => return error.ConnectionRefused,
else => |status| return windows.unexpectedStatus(status),
}
return .{ .handle = socket_handle, .address = bound_address };
}
fn netConnectUnixPosix(
userdata: ?*anyopaque,
address: *const net.UnixAddress,
) net.UnixAddress.ConnectError!net.Socket.Handle {
if (!net.has_unix_sockets) return error.AddressFamilyUnsupported;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const socket_fd = openSocketPosix(posix.AF.UNIX, .{ .mode = .stream }) catch |err| switch (err) {
error.ProtocolUnsupportedByAddressFamily => return error.AddressFamilyUnsupported,
error.OptionUnsupported => return error.Unexpected,
else => |e| return e,
};
errdefer closeFd(socket_fd);
var storage: UnixAddress = undefined;
const addr_len = addressUnixToPosix(address, &storage);
try posixConnectUnix(socket_fd, &storage.any, addr_len);
return socket_fd;
}
fn netConnectUnixWindows(
userdata: ?*anyopaque,
address: *const net.UnixAddress,
) net.UnixAddress.ConnectError!net.Socket.Handle {
if (!net.has_unix_sockets) return error.AddressFamilyUnsupported;
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const is_abstract = address.isAbstract();
const wps = if (!is_abstract) sliceToPrefixedFileW(null, address.path, .{
.allow_relative = false,
}) catch |err| switch (err) {
error.NameTooLong, error.BadPathName => return error.FileNotFound,
else => |e| return e,
} else undefined;
const socket_handle = openSocketAfd(ws2_32.AF.UNIX, .{ .mode = .stream }) catch |err| switch (err) {
error.ProtocolUnsupportedByAddressFamily => return error.AddressFamilyUnsupported,
else => |e| return e,
};
errdefer windows.CloseHandle(socket_handle);
if (!is_abstract) try socketOptionAfd(socket_handle, .special, 0, ws2_32.SO.UNIX_PATH, @constCast(
@as([]const u8, @ptrCast(&windows.AFD.SOCKOPT_INFO.UNIX_PATH{
.Path = wps.data,
}))[0 .. @offsetOf(windows.AFD.SOCKOPT_INFO.UNIX_PATH, "Path") + @sizeOf(windows.WCHAR) * wps.len],
));
bindSocketUnixAfd(socket_handle, &(net.UnixAddress.init("") catch |err| switch (err) {
error.NameTooLong => unreachable,
})) catch |err| switch (err) {
error.AddressInUse => return error.Unexpected,
else => |e| return e,
};
const Storage = extern struct { Reserved0: [3]usize = @splat(0), Address: UnixAddress };
var storage: Storage = .{ .Address = undefined };
const addr_len = addressUnixToPosix(address, &storage.Address);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.CONNECT,
.in = @as([]const u8, @ptrCast(&storage))[0 .. @offsetOf(Storage, "Address") + addr_len],
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
return socket_handle;
}
fn netBindIpPosix(
userdata: ?*anyopaque,
address: *const IpAddress,
options: IpAddress.BindOptions,
) IpAddress.BindError!net.Socket {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const family = posixAddressFamily(address);
const socket_fd = try openSocketPosix(family, options);
errdefer closeFd(socket_fd);
var storage: PosixAddress = undefined;
var addr_len = addressToPosix(address, &storage);
try posixBind(socket_fd, &storage.any, addr_len);
if (options.allow_broadcast) try setSocketOptionPosix(socket_fd, std.posix.SOL.SOCKET, std.posix.SO.BROADCAST, 1);
try posixGetSockName(socket_fd, &storage.any, &addr_len);
return .{ .handle = socket_fd, .address = addressFromPosix(&storage) };
}
fn netBindIpWindows(
userdata: ?*anyopaque,
address: *const IpAddress,
options: IpAddress.BindOptions,
) IpAddress.BindError!net.Socket {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const family = posixAddressFamily(address);
const socket_handle = try openSocketAfd(family, options);
errdefer windows.CloseHandle(socket_handle);
const bound_address = try bindSocketIpAfd(socket_handle, address, .Active);
if (options.allow_broadcast) try setSocketOptionAfd(socket_handle, ws2_32.SOL.SOCKET, ws2_32.SO.BROADCAST, true);
return .{ .handle = socket_handle, .address = bound_address };
}
fn openSocketPosix(
family: posix.sa_family_t,
options: IpAddress.BindOptions,
) error{
AddressFamilyUnsupported,
ProtocolUnsupportedBySystem,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
SystemResources,
ProtocolUnsupportedByAddressFamily,
SocketModeUnsupported,
OptionUnsupported,
Unexpected,
Canceled,
}!posix.socket_t {
const mode, const protocol = try posixSocketModeProtocol(family, options.mode, options.protocol);
const flags: u32 = mode | if (socket_flags_unsupported) 0 else posix.SOCK.CLOEXEC;
const syscall: Syscall = try .start();
const socket_fd = while (true) {
const rc = posix.system.socket(family, flags, protocol);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const fd: posix.fd_t = @intCast(rc);
errdefer closeFd(fd);
if (socket_flags_unsupported) try setCloexec(fd);
break fd;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.AFNOSUPPORT => return syscall.fail(error.AddressFamilyUnsupported),
.INVAL => return syscall.fail(error.ProtocolUnsupportedBySystem),
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NFILE => return syscall.fail(error.SystemFdQuotaExceeded),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.PROTONOSUPPORT => return syscall.fail(error.ProtocolUnsupportedByAddressFamily),
.PROTOTYPE => return syscall.fail(error.SocketModeUnsupported),
else => |err| return syscall.unexpectedErrno(err),
}
};
errdefer closeFd(socket_fd);
if (options.ip6_only) |ip6_only| {
if (posix.IPV6 == void) return error.OptionUnsupported;
try setSocketOptionPosix(socket_fd, posix.IPPROTO.IPV6, posix.IPV6.V6ONLY, @intFromBool(ip6_only));
}
return socket_fd;
}
fn setCloexec(fd: posix.fd_t) error{ Canceled, Unexpected }!void {
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.fcntl(fd, posix.F.SETFD, @as(usize, posix.FD_CLOEXEC)))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |err| return syscall.unexpectedErrno(err),
};
}
fn netSocketCreatePair(
userdata: ?*anyopaque,
options: net.Socket.CreatePairOptions,
) net.Socket.CreatePairError![2]net.Socket {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (!have_networking) return error.OperationUnsupported;
if (@TypeOf(posix.system.socketpair) == void) return error.OperationUnsupported;
if (native_os == .haiku) @panic("TODO");
const family: posix.sa_family_t = switch (options.family) {
.ip4 => posix.AF.INET,
.ip6 => posix.AF.INET6,
};
const mode, const protocol = try posixSocketModeProtocol(family, options.mode, options.protocol);
const flags: u32 = mode | if (socket_flags_unsupported) 0 else posix.SOCK.CLOEXEC;
var sockets: [2]posix.socket_t = undefined;
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.socketpair(family, flags, protocol, &sockets))) {
.SUCCESS => {
syscall.finish();
errdefer {
closeFd(sockets[0]);
closeFd(sockets[1]);
}
if (socket_flags_unsupported) {
try setCloexec(sockets[0]);
try setCloexec(sockets[1]);
}
var storages: [2]PosixAddress = undefined;
var addr_lens: [2]posix.socklen_t = .{ @sizeOf(PosixAddress), @sizeOf(PosixAddress) };
try posixGetSockName(sockets[0], &storages[0].any, &addr_lens[0]);
try posixGetSockName(sockets[1], &storages[1].any, &addr_lens[1]);
return .{
.{ .handle = sockets[0], .address = addressFromPosix(&storages[0]) },
.{ .handle = sockets[1], .address = addressFromPosix(&storages[1]) },
};
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.AFNOSUPPORT => return syscall.fail(error.AddressFamilyUnsupported),
.INVAL => return syscall.fail(error.ProtocolUnsupportedBySystem),
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NFILE => return syscall.fail(error.SystemFdQuotaExceeded),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.PROTONOSUPPORT => return syscall.fail(error.ProtocolUnsupportedByAddressFamily),
.PROTOTYPE => return syscall.fail(error.SocketModeUnsupported),
else => |err| return syscall.unexpectedErrno(err),
};
}
fn openSocketAfd(family: ws2_32.ADDRESS_FAMILY, options: IpAddress.BindOptions) !net.Socket.Handle {
const mode, const protocol = try posixSocketModeProtocol(family, options.mode, options.protocol);
var handle: windows.HANDLE = undefined;
var iosb: windows.IO_STATUS_BLOCK = undefined;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtCreateFile(
&handle,
.{
.STANDARD = .{ .RIGHTS = .{ .WRITE_DAC = true }, .SYNCHRONIZE = true },
.GENERIC = .{ .WRITE = true, .READ = true },
},
&.{
.ObjectName = @constCast(&windows.UNICODE_STRING.init(
windows.AFD.DEVICE_NAME ++ .{ '\\', 'E', 'n', 'd', 'p', 'o', 'i', 'n', 't' },
)),
},
&iosb,
null,
.{},
.{ .READ = true, .WRITE = true },
.OPEN_IF,
.{ .IO = .ASYNCHRONOUS },
&windows.AFD.OPEN_PACKET.FULL_EA_INFORMATION{ .Value = .{
.EndpointType = .{
.CONNECTIONLESS = switch (options.mode) {
.stream, .seqpacket, .rdm => false,
.dgram, .raw => true,
},
.MESSAGEMODE = options.mode != .stream,
.RAW = options.mode == .raw,
},
.GroupID = 0,
.AddressFamily = family,
.SocketType = @bitCast(mode),
.Protocol = @bitCast(protocol),
.TransportDeviceNameLength = 0,
.TransportDeviceName = undefined,
} },
@sizeOf(windows.AFD.OPEN_PACKET.FULL_EA_INFORMATION),
)) {
.SUCCESS => {
syscall.finish();
return handle;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.PROTOCOL_NOT_SUPPORTED => return syscall.fail(error.AddressFamilyUnsupported),
.NO_SUCH_FILE => return syscall.fail(error.ProtocolUnsupportedByAddressFamily),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
fn bindSocketIpAfd(socket_handle: net.Socket.Handle, address: *const IpAddress, mode: windows.AFD.BIND_INFO.MODE) !IpAddress {
const Storage = extern struct { Info: windows.AFD.BIND_INFO, Address: PosixAddress };
var storage: Storage = .{ .Info = .{ .Mode = mode }, .Address = undefined };
const addr_len = addressToPosix(address, &storage.Address);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.BIND,
.in = @as([]const u8, @ptrCast(&storage))[0 .. @offsetOf(Storage, "Address") + addr_len],
.out = @as([]u8, @ptrCast(&storage.Address))[0..addr_len],
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.SHARING_VIOLATION => return error.AddressInUse,
else => |status| return windows.unexpectedStatus(status),
}
return addressFromPosix(&storage.Address);
}
fn bindSocketUnixAfd(socket_handle: net.Socket.Handle, address: *const net.UnixAddress) !void {
const Storage = extern struct { Info: windows.AFD.BIND_INFO, Address: UnixAddress };
var storage: Storage = .{ .Info = .{ .Mode = .Unix }, .Address = undefined };
const addr_len = addressUnixToPosix(address, &storage.Address);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.BIND,
.in = @as([]const u8, @ptrCast(&storage))[0 .. @offsetOf(Storage, "Address") + addr_len],
.out = @ptrCast(&storage.Address),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.ADDRESS_ALREADY_EXISTS => return error.AddressInUse,
else => |status| return windows.unexpectedStatus(status),
}
}
fn netAcceptPosix(userdata: ?*anyopaque, listen_fd: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
options;
var storage: PosixAddress = undefined;
var addr_len: posix.socklen_t = @sizeOf(PosixAddress);
const syscall: Syscall = try .start();
const fd = while (true) {
const rc = if (have_accept4)
posix.system.accept4(listen_fd, &storage.any, &addr_len, posix.SOCK.CLOEXEC)
else
posix.system.accept(listen_fd, &storage.any, &addr_len);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const fd: posix.fd_t = @intCast(rc);
errdefer closeFd(fd);
if (!have_accept4) try setCloexec(fd);
break fd;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.AGAIN => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.CONNABORTED => return error.ConnectionAborted,
.FAULT => |err| return errnoBug(err),
.INVAL => return error.SocketNotListening,
.NOTSOCK => |err| return errnoBug(err),
.MFILE => return error.ProcessFdQuotaExceeded,
.NFILE => return error.SystemFdQuotaExceeded,
.NOBUFS => return error.SystemResources,
.NOMEM => return error.SystemResources,
.OPNOTSUPP => |err| return errnoBug(err),
.PROTO => return error.ProtocolFailure,
.PERM => return error.BlockedByFirewall,
else => |err| return posix.unexpectedErrno(err),
}
},
}
};
return .{ .handle = fd, .address = addressFromPosix(&storage) };
}
fn netAcceptWindows(userdata: ?*anyopaque, listen_handle: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
const Storage = extern struct {
Info: windows.AFD.LISTEN_RESPONSE_INFO,
RemoteAddress: extern union { posix: PosixAddress, unix: UnixAddress },
};
var storage: Storage = undefined;
switch ((try deviceIoControl(&.{
.file = .{ .handle = listen_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.WAIT_FOR_LISTEN,
.out = @ptrCast(&storage),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
errdefer t.deferAcceptAfd(listen_handle, storage.Info);
const accept_handle = openSocketAfd(
storage.RemoteAddress.posix.any.family,
.{ .mode = options.mode, .protocol = options.protocol },
) catch |err| switch (err) {
error.AddressFamilyUnsupported => return error.Unexpected,
error.ProtocolUnsupportedByAddressFamily => return error.Unexpected,
else => |e| return e,
};
errdefer windows.CloseHandle(accept_handle);
switch ((try deviceIoControl(&.{
.file = .{ .handle = listen_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.ACCEPT,
.in = @ptrCast(&windows.AFD.ACCEPT_INFO{
.UseSAN = .FALSE,
.Sequence = storage.Info.Sequence,
.AcceptHandle = accept_handle,
}),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
return .{ .handle = accept_handle, .address = addressFromPosix(&storage.RemoteAddress.posix) };
}
fn deferAcceptAfd(t: *Threaded, listen_handle: net.Socket.Handle, info: windows.AFD.LISTEN_RESPONSE_INFO) void {
const cancel_protection = swapCancelProtection(t, .blocked);
defer _ = swapCancelProtection(t, cancel_protection);
switch ((deviceIoControl(&.{
.file = .{ .handle = listen_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.DEFER_ACCEPT,
.in = @ptrCast(&windows.AFD.DEFER_ACCEPT_INFO{
.Sequence = info.Sequence,
.Reject = .FALSE,
}),
}) catch |err| switch (err) {
error.Canceled => unreachable, // 已阻塞
}).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
else => |status| windows.unexpectedStatus(status) catch {},
}
}
fn netRead(socket_handle: net.Socket.Handle, data: [][]u8, control: []u8) net.Stream.Reader.Error!net.Stream.ReadResult {
if (!have_networking) return error.NetworkDown;
if (is_windows) return .{ .data_len = try netReadWindows(socket_handle, data) };
return netReadPosix(socket_handle, data, control);
}
fn netReadPosix(fd: net.Socket.Handle, data: [][]u8, control: []u8) net.Stream.Reader.Error!net.Stream.ReadResult {
var iovecs_buffer: [max_iovecs_len]posix.iovec = undefined;
var i: usize = 0;
for (data) |buf| {
if (iovecs_buffer.len - i == 0) break;
if (buf.len != 0) {
iovecs_buffer[i] = .{ .base = buf.ptr, .len = buf.len };
i += 1;
}
}
const dest = iovecs_buffer[0..i];
assert(dest[0].len > 0);
if (native_os == .wasi and !builtin.link_libc) {
const syscall: Syscall = try .start();
while (true) {
var n: usize = undefined;
switch (std.os.wasi.fd_read(fd, dest.ptr, dest.len, &n)) {
.SUCCESS => {
syscall.finish();
return n;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.AGAIN => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOBUFS => return error.SystemResources,
.NOMEM => return error.SystemResources,
.NOTCONN => return error.SocketUnconnected,
.CONNRESET => return error.ConnectionResetByPeer,
.TIMEDOUT => return error.ConnectionTimedOut,
.NOTCAPABLE => return error.AccessDenied,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
var msg: posix.msghdr = .{
.name = null,
.namelen = 0,
.iov = dest.ptr,
.iovlen = @intCast(dest.len),
.control = control.ptr,
.controllen = @intCast(control.len),
.flags = 0,
};
const flags: u32 =
@as(u32, if (@hasDecl(posix.MSG, "CMSG_CLOEXEC")) posix.MSG.CMSG_CLOEXEC else 0);
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.recvmsg(fd, &msg, flags);
const rc_control = msg.controllen;
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return .{
.data_len = @intCast(rc),
.control_len = @intCast(rc_control),
.control_truncated = (msg.flags & posix.MSG.CTRUNC) != 0,
};
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.INVAL => |err| return errnoBug(err),
.FAULT => |err| return errnoBug(err),
.AGAIN => |err| return errnoBug(err),
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.NOBUFS => return error.SystemResources,
.NOMEM => return error.SystemResources,
.NOTCONN => return error.SocketUnconnected,
.CONNRESET => return error.ConnectionResetByPeer,
.TIMEDOUT => return error.ConnectionTimedOut,
.PIPE => return error.SocketUnconnected,
.NETDOWN => return error.NetworkDown,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn netReadWindows(socket_handle: net.Socket.Handle, data: [][]u8) net.Stream.Reader.Error!usize {
var iovecs: [max_iovecs_len]windows.AFD.WSABUF(.@"var") = undefined;
var len: u32 = 0;
for (data) |buf| {
if (iovecs.len - len == 0) break;
addAfdBuf(.@"var", &iovecs, &len, buf);
}
const iosb = try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.RECEIVE,
.in = @ptrCast(&windows.AFD.RECV_INFO{
.BufferArray = &iovecs,
.BufferCount = len,
.AfdFlags = .{ .NO_FAST_IO = true, .OVERLAPPED = true },
.TdiFlags = .{ .NORMAL = true },
}),
});
switch (iosb.u.Status) {
.SUCCESS => return iosb.Information,
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.CONNECTION_RESET, .REMOTE_DISCONNECT => return error.ConnectionResetByPeer,
.IO_TIMEOUT => return error.ConnectionTimedOut,
else => |status| return windows.unexpectedStatus(status),
}
}
fn netSendPosix(
t: *Threaded,
socket_handle: net.Socket.Handle,
messages: []net.OutgoingMessage,
flags: net.SendFlags,
nonblocking: bool,
) struct { ?(net.Socket.SendError || error{WouldBlock}), usize } {
if (!have_networking) return .{ error.NetworkDown, 0 };
const posix_flags: u32 =
@as(u32, if (@hasDecl(posix.MSG, "CONFIRM") and flags.confirm) posix.MSG.CONFIRM else 0) |
@as(u32, if (@hasDecl(posix.MSG, "DONTROUTE") and flags.dont_route) posix.MSG.DONTROUTE else 0) |
@as(u32, if (@hasDecl(posix.MSG, "EOR") and flags.eor) posix.MSG.EOR else 0) |
@as(u32, if (@hasDecl(posix.MSG, "OOB") and flags.oob) posix.MSG.OOB else 0) |
@as(u32, if (@hasDecl(posix.MSG, "FASTOPEN") and flags.fastopen) posix.MSG.FASTOPEN else 0) |
@as(u32, if (@hasDecl(posix.MSG, "DONTWAIT") and nonblocking) posix.MSG.DONTWAIT else 0) |
posix.MSG.NOSIGNAL;
var i: usize = 0;
while (messages.len - i != 0) {
if (have_sendmmsg) {
i += netSendManyPosix(socket_handle, messages[i..], posix_flags) catch |err| return .{ err, i };
continue;
}
t.netSendOnePosix(socket_handle, &messages[i], posix_flags) catch |err| return .{ err, i };
i += 1;
}
return .{ null, i };
}
fn netSendWindows(
t: *Threaded,
socket_handle: net.Socket.Handle,
messages: []net.OutgoingMessage,
flags: net.SendFlags,
) struct { ?net.Socket.SendError, usize } {
if (!have_networking) return .{ error.NetworkDown, 0 };
for (messages, 0..) |*m, i| {
t.netSendOneWindows(socket_handle, m, flags) catch |err| return .{ err, i };
}
return .{ null, messages.len };
}
fn netSendOneWindows(
t: *Threaded,
socket_handle: net.Socket.Handle,
message: *net.OutgoingMessage,
flags: net.SendFlags,
) net.Socket.SendError!void {
_ = t;
_ = flags;
const iovecs: [1]windows.AFD.WSABUF(.@"const") = .{.{
.buf = message.data_ptr,
.len = std.math.cast(std.os.windows.ULONG, message.data_len) orelse
return error.MessageOversize,
}};
var storage: PosixAddress = undefined;
const addr_len = addressToPosix(message.address, &storage);
switch ((try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.SEND_DATAGRAM,
.in = @ptrCast(&windows.AFD.SEND_DATAGRAM_INFO{
.BufferArray = &iovecs,
.BufferCount = iovecs.len,
.AfdFlags = .{ .NO_FAST_IO = true, .OVERLAPPED = true },
.TdiRequest = undefined,
.TdiConnInfo = .{
.UserDataLength = undefined,
.UserData = undefined,
.OptionsLength = undefined,
.Options = undefined,
.RemoteAddressLength = @bitCast(addr_len),
.RemoteAddress = &storage,
},
}),
})).u.Status) {
.SUCCESS => return,
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
}
fn netSendOnePosix(
t: *Threaded,
socket_handle: net.Socket.Handle,
message: *net.OutgoingMessage,
flags: u32,
) (net.Socket.SendError || error{WouldBlock})!void {
_ = t;
var addr: PosixAddress = undefined;
var iovec: posix.iovec_const = .{ .base = @constCast(message.data_ptr), .len = message.data_len };
const msg: posix.msghdr_const = .{
.name = &addr.any,
.namelen = addressToPosix(message.address, &addr),
.iov = (&iovec)[0..1],
.iovlen = 1,
// 如果该指针无效,即使 controllen 为零,操作系统也返回 EINVAL。
.control = if (message.control.len == 0) null else @constCast(message.control.ptr),
.controllen = @intCast(message.control.len),
.flags = 0,
};
var syscall: if (is_windows) AlertableSyscall else Syscall = try .start();
while (true) {
const rc = posix.system.sendmsg(socket_handle, &msg, flags);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
message.data_len = @intCast(rc);
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.AGAIN => return syscall.fail(error.WouldBlock),
.ALREADY => return syscall.fail(error.FastOpenAlreadyInProgress),
.CONNRESET => return syscall.fail(error.ConnectionResetByPeer),
.MSGSIZE => return syscall.fail(error.MessageOversize),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.PIPE => return syscall.fail(error.SocketUnconnected),
.AFNOSUPPORT => return syscall.fail(error.AddressFamilyUnsupported),
.HOSTUNREACH => return syscall.fail(error.HostUnreachable),
.NETUNREACH => return syscall.fail(error.NetworkUnreachable),
.NOTCONN => return syscall.fail(error.SocketUnconnected),
.TIMEDOUT => return syscall.fail(error.ConnectionTimedOut),
.NETDOWN => return syscall.fail(error.NetworkDown),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
.DESTADDRREQ => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
.ISCONN => |err| return syscall.errnoBug(err),
.NOTSOCK => |err| return syscall.errnoBug(err),
.OPNOTSUPP => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn netSendManyPosix(
socket_handle: net.Socket.Handle,
messages: []net.OutgoingMessage,
flags: u32,
) (net.Socket.SendError || error{WouldBlock})!usize {
var msg_buffer: [64]posix.system.mmsghdr = undefined;
var addr_buffer: [msg_buffer.len]PosixAddress = undefined;
var iovecs_buffer: [msg_buffer.len]posix.iovec = undefined;
const min_len: usize = @min(messages.len, msg_buffer.len);
const clamped_messages = messages[0..min_len];
const clamped_msgs = (&msg_buffer)[0..min_len];
const clamped_addrs = (&addr_buffer)[0..min_len];
const clamped_iovecs = (&iovecs_buffer)[0..min_len];
for (clamped_messages, clamped_msgs, clamped_addrs, clamped_iovecs) |*message, *msg, *addr, *iovec| {
iovec.* = .{ .base = @constCast(message.data_ptr), .len = message.data_len };
msg.* = .{
.hdr = .{
.name = &addr.any,
.namelen = addressToPosix(message.address, addr),
.iov = iovec[0..1],
.iovlen = 1,
.control = @constCast(message.control.ptr),
.controllen = message.control.len,
.flags = 0,
},
.len = undefined, // 通过下方的 sendmmsg 填充。
};
}
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.sendmmsg(socket_handle, clamped_msgs.ptr, @intCast(clamped_msgs.len), flags);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const n: usize = @intCast(rc);
for (clamped_messages[0..n], clamped_msgs[0..n]) |*message, *msg| {
message.data_len = msg.len;
}
return n;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.AGAIN => return syscall.fail(error.WouldBlock),
.ALREADY => return syscall.fail(error.FastOpenAlreadyInProgress),
.CONNRESET => return syscall.fail(error.ConnectionResetByPeer),
.MSGSIZE => return syscall.fail(error.MessageOversize),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.PIPE => return syscall.fail(error.SocketUnconnected),
.AFNOSUPPORT => return syscall.fail(error.AddressFamilyUnsupported),
.HOSTUNREACH => return syscall.fail(error.HostUnreachable),
.NETUNREACH => return syscall.fail(error.NetworkUnreachable),
.NOTCONN => return syscall.fail(error.SocketUnconnected),
.TIMEDOUT => return syscall.fail(error.ConnectionTimedOut),
.NETDOWN => return syscall.fail(error.NetworkDown),
.BADF => |err| return syscall.errnoBug(err), // 文件描述符在关闭后被使用。
.DESTADDRREQ => |err| return syscall.errnoBug(err), // 套接字不是面向连接的模式,且未设置对等方地址。
.FAULT => |err| return syscall.errnoBug(err), // 为某个参数指定了无效的用户空间地址。
.INVAL => |err| return syscall.errnoBug(err), // 传入的参数无效。
.ISCONN => |err| return syscall.errnoBug(err), // 面向连接的套接字已经连接,但又指定了接收方
.NOTSOCK => |err| return syscall.errnoBug(err), // 文件描述符 sockfd 不指向套接字。
.OPNOTSUPP => |err| return syscall.errnoBug(err), // flags 参数中的某个位不适用于该套接字类型。
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn netReceivePosix(
socket_handle: net.Socket.Handle,
message: *net.IncomingMessage,
data_buffer: []u8,
flags: net.ReceiveFlags,
nonblocking: bool,
) (net.Socket.ReceiveError || error{WouldBlock})!void {
// recvmmsg 没有用,原因如下:
// * [超时缺陷](https://bugzilla.kernel.org/show_bug.cgi?id=75371)。
// * 它要求为每条消息提供 iovec,但这里采用更好的接口:用单个数据缓冲区处理全部消息。然而,无法将此接口降级为分散的向量,因为减小缓冲区可能使某些消息无法接收。
//
//
//
const posix_flags: u32 =
@as(u32, if (flags.oob) posix.MSG.OOB else 0) |
@as(u32, if (flags.peek) posix.MSG.PEEK else 0) |
@as(u32, if (flags.trunc) posix.MSG.TRUNC else 0) |
@as(u32, if (nonblocking) posix.MSG.DONTWAIT else 0);
var storage: PosixAddress = undefined;
var iov: posix.iovec = .{ .base = data_buffer.ptr, .len = data_buffer.len };
var msg: posix.msghdr = .{
.name = &storage.any,
.namelen = @sizeOf(PosixAddress),
.iov = (&iov)[0..1],
.iovlen = 1,
.control = message.control.ptr,
.controllen = @intCast(message.control.len),
.flags = 0,
};
const syscall = try Syscall.start();
while (true) {
const rc = posix.system.recvmsg(socket_handle, &msg, posix_flags);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const data = data_buffer[0..@intCast(rc)];
message.* = .{
.from = addressFromPosix(&storage),
.data = data,
.control = if (msg.control) |ptr| @as([*]u8, @ptrCast(ptr))[0..msg.controllen] else message.control,
.flags = .{
.eor = (msg.flags & posix.MSG.EOR) != 0,
.trunc = (msg.flags & posix.MSG.TRUNC) != 0,
.ctrunc = (msg.flags & posix.MSG.CTRUNC) != 0,
.oob = (msg.flags & posix.MSG.OOB) != 0,
.errqueue = if (@hasDecl(posix.MSG, "ERRQUEUE")) (msg.flags & posix.MSG.ERRQUEUE) != 0 else false,
},
};
return;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.NFILE => return syscall.fail(error.SystemFdQuotaExceeded),
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.NOTCONN => return syscall.fail(error.SocketUnconnected),
.MSGSIZE => return syscall.fail(error.MessageOversize),
.PIPE => return syscall.fail(error.SocketUnconnected),
.CONNRESET => return syscall.fail(error.ConnectionResetByPeer),
.TIMEDOUT => return syscall.fail(error.ConnectionTimedOut),
.NETDOWN => return syscall.fail(error.NetworkDown),
.AGAIN => return syscall.fail(error.WouldBlock),
.BADF => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.INVAL => |err| return syscall.errnoBug(err),
.NOTSOCK => |err| return syscall.errnoBug(err),
.OPNOTSUPP => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn netReceiveWindows(
t: *Threaded,
socket_handle: net.Socket.Handle,
message_buffer: []net.IncomingMessage,
data_buffer: []u8,
flags: net.ReceiveFlags,
) struct { ?net.Socket.ReceiveError, usize } {
t.netReceiveOneWindows(socket_handle, &message_buffer[0], data_buffer, flags) catch |err|
return .{ err, 0 };
return .{ null, 1 };
}
fn netReceiveOneWindows(
t: *Threaded,
socket_handle: net.Socket.Handle,
message: *net.IncomingMessage,
data_buffer: []u8,
flags: net.ReceiveFlags,
) net.Socket.ReceiveError!void {
if (!have_networking) return error.NetworkDown;
_ = t;
const iovecs: [1]windows.AFD.WSABUF(.@"var") = .{.{
.buf = data_buffer.ptr,
.len = std.math.cast(std.os.windows.ULONG, data_buffer.len) orelse return error.MessageOversize,
}};
var storage: PosixAddress = undefined;
var addr_len: windows.ULONG = @sizeOf(PosixAddress);
const iosb = try deviceIoControl(&.{
.file = .{ .handle = socket_handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.RECEIVE_DATAGRAM,
.in = @ptrCast(&windows.AFD.RECV_DATAGRAM_INFO{
.BufferArray = &iovecs,
.BufferCount = iovecs.len,
.AfdFlags = .{ .NO_FAST_IO = true, .OVERLAPPED = true },
.TdiFlags = .{ .NORMAL = !flags.oob, .EXPEDITED = flags.oob, .PEEK = flags.peek },
.Address = &storage,
.AddressLength = &addr_len,
}),
});
switch (iosb.u.Status) {
.SUCCESS, .RECEIVE_EXPEDITED => |status| message.* = .{
.from = addressFromPosix(&storage),
.data = data_buffer[0..iosb.Information],
.control = &.{},
.flags = .{
.eor = false,
.trunc = false,
.ctrunc = false,
.oob = switch (status) {
else => unreachable,
.SUCCESS, .RECEIVE_PARTIAL, .BUFFER_OVERFLOW => false,
.RECEIVE_EXPEDITED, .RECEIVE_PARTIAL_EXPEDITED => true,
},
.errqueue = false,
},
},
.RECEIVE_PARTIAL,
.RECEIVE_PARTIAL_EXPEDITED,
=> |status| return windows.unexpectedStatus(status), // TdiFlags.PARTIAL = false
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.BUFFER_OVERFLOW => return error.MessageOversize,
.PORT_UNREACHABLE => return error.PortUnreachable,
else => |status| return windows.unexpectedStatus(status),
}
}
fn netWritePosix(
fd: net.Socket.Handle,
header: []const u8,
data: []const []const u8,
splat: usize,
control: []const u8,
) net.Stream.Writer.Error!usize {
if (!have_networking) return error.NetworkDown;
var iovecs: [max_iovecs_len]posix.iovec_const = undefined;
var msg: posix.msghdr_const = .{
.name = null,
.namelen = 0,
.iov = &iovecs,
.iovlen = 0,
.control = if (control.len == 0) null else @constCast(control.ptr),
.controllen = @intCast(control.len),
.flags = 0,
};
addBuf(&iovecs, &msg.iovlen, header);
for (data[0 .. data.len - 1]) |bytes| addBuf(&iovecs, &msg.iovlen, bytes);
const pattern = data[data.len - 1];
var splat_backup_buffer: [splat_buffer_size]u8 = undefined;
if (iovecs.len - msg.iovlen != 0) switch (splat) {
0 => {},
1 => addBuf(&iovecs, &msg.iovlen, pattern),
else => switch (pattern.len) {
0 => {},
1 => {
const splat_buffer = &splat_backup_buffer;
const memset_len = @min(splat_buffer.len, splat);
const buf = splat_buffer[0..memset_len];
@memset(buf, pattern[0]);
addBuf(&iovecs, &msg.iovlen, buf);
var remaining_splat = splat - buf.len;
while (remaining_splat > splat_buffer.len and iovecs.len - msg.iovlen != 0) {
assert(buf.len == splat_buffer.len);
addBuf(&iovecs, &msg.iovlen, splat_buffer);
remaining_splat -= splat_buffer.len;
}
addBuf(&iovecs, &msg.iovlen, splat_buffer[0..@min(remaining_splat, splat_buffer.len)]);
},
else => for (0..@min(splat, iovecs.len - msg.iovlen)) |_| {
addBuf(&iovecs, &msg.iovlen, pattern);
},
},
};
const flags = posix.MSG.NOSIGNAL;
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.sendmsg(fd, &msg, flags);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
return @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.ACCES => |err| return errnoBug(err),
.AGAIN => |err| return errnoBug(err),
.ALREADY => return error.FastOpenAlreadyInProgress,
.BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
.CONNRESET => return error.ConnectionResetByPeer,
.DESTADDRREQ => |err| return errnoBug(err), // 套接字不是面向连接的模式,且未设置对等方地址。
.FAULT => |err| return errnoBug(err), // 为某个参数指定了无效的用户空间地址。
.INVAL => |err| return errnoBug(err), // 传入的参数无效。
.ISCONN => |err| return errnoBug(err), // 面向连接的套接字已经连接,但又指定了接收方
.MSGSIZE => |err| return errnoBug(err),
.NOBUFS => return error.SystemResources,
.NOMEM => return error.SystemResources,
.NOTSOCK => |err| return errnoBug(err), // 文件描述符 sockfd 不指向套接字。
.OPNOTSUPP => |err| return errnoBug(err), // flags 参数中的某个位不适用于该套接字类型。
.PIPE => return error.SocketUnconnected,
.AFNOSUPPORT => return error.AddressFamilyUnsupported,
.HOSTUNREACH => return error.HostUnreachable,
.NETUNREACH => return error.NetworkUnreachable,
.NOTCONN => return error.SocketUnconnected,
.TIMEDOUT => return error.ConnectionTimedOut,
.NETDOWN => return error.NetworkDown,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn netWriteWindows(
handle: net.Socket.Handle,
header: []const u8,
data: []const []const u8,
splat: usize,
control: []const u8,
) net.Stream.Writer.Error!usize {
if (!have_networking) return error.NetworkDown;
// Windows 没有控制/辅助数据的概念。
_ = control;
var iovecs: [max_iovecs_len]windows.AFD.WSABUF(.@"const") = undefined;
var len: u32 = 0;
addAfdBuf(.@"const", &iovecs, &len, header);
for (data[0 .. data.len - 1]) |bytes| addAfdBuf(.@"const", &iovecs, &len, bytes);
const pattern = data[data.len - 1];
var backup_buffer: [64]u8 = undefined;
if (iovecs.len - len != 0) switch (splat) {
0 => {},
1 => addAfdBuf(.@"const", &iovecs, &len, pattern),
else => switch (pattern.len) {
0 => {},
1 => {
const splat_buffer = &backup_buffer;
const memset_len = @min(splat_buffer.len, splat);
const buf = splat_buffer[0..memset_len];
@memset(buf, pattern[0]);
addAfdBuf(.@"const", &iovecs, &len, buf);
var remaining_splat = splat - buf.len;
while (remaining_splat > splat_buffer.len and len < iovecs.len) {
addAfdBuf(.@"const", &iovecs, &len, splat_buffer);
remaining_splat -= splat_buffer.len;
}
addAfdBuf(.@"const", &iovecs, &len, splat_buffer[0..@min(remaining_splat, splat_buffer.len)]);
},
else => for (0..@min(splat, iovecs.len - len)) |_| {
addAfdBuf(.@"const", &iovecs, &len, pattern);
},
},
};
const iosb = try deviceIoControl(&.{
.file = .{ .handle = handle, .flags = .{ .nonblocking = true } },
.code = windows.IOCTL.AFD.SEND,
.in = @ptrCast(&windows.AFD.SEND_INFO{
.BufferArray = &iovecs,
.BufferCount = len,
.AfdFlags = .{ .NO_FAST_IO = true, .OVERLAPPED = true },
.TdiFlags = .{},
}),
});
switch (iosb.u.Status) {
.SUCCESS => return iosb.Information,
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
.CONNECTION_RESET, .REMOTE_DISCONNECT => return error.ConnectionResetByPeer,
.IO_TIMEOUT => return error.ConnectionTimedOut,
else => |status| return windows.unexpectedStatus(status),
}
}
fn addAfdBuf(
comptime mutability: windows.AFD.Mutability,
iovecs: []windows.AFD.WSABUF(mutability),
len: *u32,
bytes: switch (mutability) {
.@"const" => []const u8,
.@"var" => []u8,
},
) void {
if (bytes.len == 0) return;
const cap = std.math.maxInt(u32);
var remaining = bytes;
while (remaining.len > cap) {
if (iovecs.len - len.* == 0) return;
iovecs[len.*] = .{ .buf = remaining.ptr, .len = cap };
len.* += 1;
remaining = remaining[cap..];
} else {
@branchHint(.likely);
if (iovecs.len - len.* == 0) return;
iovecs[len.*] = .{ .buf = remaining.ptr, .len = @intCast(remaining.len) };
len.* += 1;
}
}
/// 此处为 usize 或 u32,二者均可。因此对写入文件
/// 和发送网络消息均使用同一个 `addBuf` 函数。
const iovlen_t = switch (native_os) {
.wasi => u32,
else => @FieldType(posix.msghdr_const, "iovlen"),
};
fn addBuf(v: []posix.iovec_const, i: *iovlen_t, bytes: []const u8) void {
// 操作系统先检查指针地址再检查长度,因此必须省略零长度向量。
if (bytes.len == 0) return;
if (v.len - i.* == 0) return;
v[i.*] = .{ .base = bytes.ptr, .len = bytes.len };
i.* += 1;
}
fn netClose(userdata: ?*anyopaque, sockets: []const net.Socket) void {
if (!have_networking) unreachable;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
for (sockets) |socket| switch (native_os) {
.windows => windows.CloseHandle(socket.handle),
else => closeFd(socket.handle),
};
}
fn netShutdownPosix(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const posix_how: i32 = switch (how) {
.recv => posix.SHUT.RD,
.send => posix.SHUT.WR,
.both => posix.SHUT.RDWR,
};
const syscall: Syscall = try .start();
while (true) {
switch (posix.errno(posix.system.shutdown(handle, posix_how))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
switch (e) {
.BADF, .NOTSOCK, .INVAL => |err| return errnoBug(err),
.NOTCONN => return error.SocketUnconnected,
.NOBUFS => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
},
}
}
}
fn netShutdownWindows(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void {
if (!have_networking) return error.NetworkDown;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
// shutdown 完全不支持 APC
switch ((try deviceIoControl(&.{
.file = .{ .handle = handle, .flags = .{ .nonblocking = false } },
.code = windows.IOCTL.AFD.PARTIAL_DISCONNECT,
.in = @ptrCast(&windows.AFD.PARTIAL_DISCONNECT_INFO{
.DisconnectMode = .{ .SEND = how != .recv, .RECEIVE = how != .send },
.Timeout = -1,
}),
})).u.Status) {
.SUCCESS => {},
.CANCELLED => unreachable,
.INSUFFICIENT_RESOURCES => return error.SystemResources,
else => |status| return windows.unexpectedStatus(status),
}
}
fn netInterfaceNameResolve(
userdata: ?*anyopaque,
name: *const net.Interface.Name,
) net.Interface.Name.ResolveError!net.Interface {
if (!have_networking) return error.InterfaceNotFound;
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (native_os == .linux) {
const sock_fd = openSocketPosix(posix.AF.UNIX, .{ .mode = .dgram }) catch |err| switch (err) {
error.ProcessFdQuotaExceeded => return error.SystemResources,
error.SystemFdQuotaExceeded => return error.SystemResources,
error.AddressFamilyUnsupported => return error.Unexpected,
error.ProtocolUnsupportedBySystem => return error.Unexpected,
error.ProtocolUnsupportedByAddressFamily => return error.Unexpected,
error.SocketModeUnsupported => return error.Unexpected,
error.OptionUnsupported => return error.Unexpected,
else => |e| return e,
};
defer closeFd(sock_fd);
var ifr: posix.ifreq = .{
.ifrn = .{ .name = @bitCast(name.bytes) },
.ifru = undefined,
};
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.ioctl(sock_fd, posix.SIOCGIFINDEX, @intFromPtr(&ifr)))) {
.SUCCESS => {
syscall.finish();
return .{ .index = @bitCast(ifr.ifru.ivalue) };
},
.INTR => {
try syscall.checkCancel();
continue;
},
.NODEV => return syscall.fail(error.InterfaceNotFound),
else => |err| return syscall.unexpectedErrno(err),
};
}
if (is_windows) {
var ConvertInterfaceNameToLuidW = t.dl.ConvertInterfaceNameToLuidW.load(.acquire);
var ConvertInterfaceLuidToIndex = t.dl.ConvertInterfaceLuidToIndex.load(.acquire);
if (ConvertInterfaceNameToLuidW == null or ConvertInterfaceLuidToIndex == null) {
const iphlpapi_dll = t.dl.iphlpapi_dll.load(.acquire) orelse iphlpapi_dll: {
try Thread.checkCancel();
var iphlpapi_dll: *anyopaque = undefined;
switch (windows.ntdll.LdrLoadDll(null, null, &.init(
&.{ 'I', 'P', 'H', 'L', 'P', 'A', 'P', 'I', '.', 'D', 'L', 'L' },
), &iphlpapi_dll)) {
.SUCCESS => {},
.DLL_NOT_FOUND => return error.Unexpected,
else => |status| return windows.unexpectedStatus(status),
}
const handle = t.dl.iphlpapi_dll.cmpxchgStrong(null, iphlpapi_dll, .release, .monotonic) orelse
break :iphlpapi_dll iphlpapi_dll;
switch (windows.ntdll.LdrUnloadDll(iphlpapi_dll)) {
.SUCCESS => break :iphlpapi_dll handle.?,
else => |status| return windows.unexpectedStatus(status),
}
};
switch (windows.ntdll.LdrGetProcedureAddress(iphlpapi_dll, &.init(
&.{
'C', 'o', 'n', 'v', 'e', 'r', 't', 'I', 'n', 't', 'e', 'r', 'f', 'a', 'c', 'e',
'N', 'a', 'm', 'e', 'T', 'o', 'L', 'u', 'i', 'd', 'W',
},
), 0, @ptrCast(&ConvertInterfaceNameToLuidW))) {
.SUCCESS => t.dl.ConvertInterfaceNameToLuidW.store(ConvertInterfaceNameToLuidW, .release),
else => |status| return windows.unexpectedStatus(status),
}
switch (windows.ntdll.LdrGetProcedureAddress(iphlpapi_dll, &.init(
&.{
'C', 'o', 'n', 'v', 'e', 'r', 't', 'I', 'n', 't', 'e', 'r', 'f', 'a', 'c', 'e',
'L', 'u', 'i', 'd', 'T', 'o', 'I', 'n', 'd', 'e', 'x',
},
), 0, @ptrCast(&ConvertInterfaceLuidToIndex))) {
.SUCCESS => t.dl.ConvertInterfaceLuidToIndex.store(ConvertInterfaceLuidToIndex, .release),
else => |status| return windows.unexpectedStatus(status),
}
}
try Thread.checkCancel();
var name_w: [net.Interface.Name.max_len:0]windows.WCHAR = undefined;
name_w[
std.unicode.wtf8ToWtf16Le(&name_w, name.toSlice()) catch |err| switch (err) {
error.InvalidWtf8 => return error.InterfaceNotFound,
}
] = 0;
var luid: windows.NET.LUID = undefined;
switch (ConvertInterfaceNameToLuidW.?(&name_w, &luid)) {
.SUCCESS => {},
.INVALID_NAME => return error.InterfaceNotFound,
.INVALID_PARAMETER => unreachable,
else => |err| return windows.unexpectedError(err),
}
var index: windows.NET.IFINDEX = undefined;
switch (ConvertInterfaceLuidToIndex.?(&luid, &index)) {
.SUCCESS => {},
.INVALID_PARAMETER => unreachable,
else => |err| return windows.unexpectedError(err),
}
return .{ .index = @backingInt(index) };
}
if (builtin.link_libc) {
try Thread.checkCancel();
const index = std.c.if_nametoindex(&name.bytes);
if (index == 0) return error.InterfaceNotFound;
return .{ .index = @bitCast(index) };
}
@panic("unimplemented");
}
fn netInterfaceName(userdata: ?*anyopaque, interface: net.Interface) net.Interface.NameError!net.Interface.Name {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (native_os == .linux) {
try Thread.checkCancel();
@panic("TODO implement netInterfaceName for linux");
}
if (is_windows) {
var ConvertInterfaceIndexToLuid = t.dl.ConvertInterfaceIndexToLuid.load(.acquire);
var ConvertInterfaceLuidToNameW = t.dl.ConvertInterfaceLuidToNameW.load(.acquire);
if (ConvertInterfaceIndexToLuid == null or ConvertInterfaceLuidToNameW == null) {
const iphlpapi_dll = t.dl.iphlpapi_dll.load(.acquire) orelse iphlpapi_dll: {
try Thread.checkCancel();
var iphlpapi_dll: *anyopaque = undefined;
switch (windows.ntdll.LdrLoadDll(null, null, &.init(
&.{ 'I', 'P', 'H', 'L', 'P', 'A', 'P', 'I', '.', 'D', 'L', 'L' },
), &iphlpapi_dll)) {
.SUCCESS => {},
.DLL_NOT_FOUND => return error.Unexpected,
else => |status| return windows.unexpectedStatus(status),
}
const handle = t.dl.iphlpapi_dll.cmpxchgStrong(null, iphlpapi_dll, .release, .monotonic) orelse
break :iphlpapi_dll iphlpapi_dll;
switch (windows.ntdll.LdrUnloadDll(iphlpapi_dll)) {
.SUCCESS => break :iphlpapi_dll handle.?,
else => |status| return windows.unexpectedStatus(status),
}
};
switch (windows.ntdll.LdrGetProcedureAddress(iphlpapi_dll, &.init(
&.{
'C', 'o', 'n', 'v', 'e', 'r', 't', 'I', 'n', 't', 'e', 'r', 'f', 'a', 'c', 'e',
'I', 'n', 'd', 'e', 'x', 'T', 'o', 'L', 'u', 'i', 'd',
},
), 0, @ptrCast(&ConvertInterfaceIndexToLuid))) {
.SUCCESS => t.dl.ConvertInterfaceIndexToLuid.store(ConvertInterfaceIndexToLuid, .release),
else => |status| return windows.unexpectedStatus(status),
}
switch (windows.ntdll.LdrGetProcedureAddress(iphlpapi_dll, &.init(
&.{
'C', 'o', 'n', 'v', 'e', 'r', 't', 'I', 'n', 't', 'e', 'r', 'f', 'a', 'c', 'e',
'L', 'u', 'i', 'd', 'T', 'o', 'N', 'a', 'm', 'e', 'W',
},
), 0, @ptrCast(&ConvertInterfaceLuidToNameW))) {
.SUCCESS => t.dl.ConvertInterfaceLuidToNameW.store(ConvertInterfaceLuidToNameW, .release),
else => |status| return windows.unexpectedStatus(status),
}
}
try Thread.checkCancel();
var luid: windows.NET.LUID = undefined;
switch (ConvertInterfaceIndexToLuid.?(@fromBackingInt(@intCast(interface.index)), &luid)) {
.SUCCESS => {},
.FILE_NOT_FOUND => return error.InterfaceNotFound,
.INVALID_PARAMETER => unreachable,
else => |err| return windows.unexpectedError(err),
}
var name_w: [net.Interface.Name.max_len:0]windows.WCHAR = undefined;
switch (ConvertInterfaceLuidToNameW.?(&luid, &name_w, name_w.len)) {
.SUCCESS => {},
.INVALID_PARAMETER => unreachable,
.NOT_ENOUGH_MEMORY => return error.NameTooLong,
else => |err| return windows.unexpectedError(err),
}
var name: [3 * net.Interface.Name.max_len]u8 = undefined;
return .fromSlice(name[0..std.unicode.wtf16LeToWtf8(&name, std.mem.sliceTo(&name_w, 0))]);
}
if (builtin.link_libc) {
try Thread.checkCancel();
@panic("TODO implement netInterfaceName for libc");
}
@panic("unimplemented");
}
fn netLookup(
userdata: ?*anyopaque,
host_name: HostName,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
) net.HostName.LookupError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
defer resolved.close(io(t));
t.netLookupFallible(host_name, resolved, options) catch |err| switch (err) {
error.Closed => unreachable, // 在 `netLookup` 返回之前,不得关闭 `resolved`。
else => |e| return e,
};
}
fn netLookupFallible(
t: *Threaded,
host_name: HostName,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
) (net.HostName.LookupError || Io.QueueClosedError)!void {
if (!have_networking) return error.NetworkDown;
const t_io = t.io();
const name = host_name.bytes;
assert(name.len <= HostName.max_len);
// Linux 上,glibc 提供可支持此处语义的 getaddrinfo_a。
// 但 musl 符合 POSIX 的 getaddrinfo 不支持,因此绕过它。
const is_glibc = builtin.link_libc and builtin.target.isGnuLibC();
if (is_glibc) {
// TODO 使用 getaddrinfo_a / gai_cancel
}
// 在 Linux 上,由于 Name Service Switch 功能,必须经由 glibc。
const non_glibc_linux = native_os == .linux and !is_glibc;
if (non_glibc_linux or is_windows) {
if (IpAddress.parseIp6(name, options.port)) |addr| {
if (options.family == .ip4) return error.UnknownHostName;
if (copyCanon(options.canonical_name_buffer, name)) |canon| {
try resolved.putAll(t_io, &.{
.{ .address = addr },
.{ .canonical_name = canon },
});
} else {
try resolved.putOne(t_io, .{ .address = addr });
}
return;
} else |_| {}
if (IpAddress.parseIp4(name, options.port)) |addr| {
if (options.family == .ip6) return error.UnknownHostName;
if (copyCanon(options.canonical_name_buffer, name)) |canon| {
try resolved.putAll(t_io, &.{
.{ .address = addr },
.{ .canonical_name = canon },
});
} else {
try resolved.putOne(t_io, .{ .address = addr });
}
return;
} else |_| {}
if (t.lookupHosts(host_name, resolved, options)) return else |err| switch (err) {
error.UnknownHostName => {},
else => |e| return e,
}
// RFC 6761 第 6.3.3 节。
// 名称解析 API 和库应当将
// localhost 名称识别为特殊名称;对地址查询应始终返回 IP
// 环回地址,对其他所有查询类型
// 返回否定响应。
// 检查是否等于 "localhost(.)" 或以 ".localhost(.)" 结尾
const localhost = if (name[name.len - 1] == '.') "localhost." else "localhost";
if (std.mem.endsWith(u8, name, localhost) and
(name.len == localhost.len or name[name.len - localhost.len - 1] == '.'))
{
var results_buffer: [3]HostName.LookupResult = undefined;
var results_index: usize = 0;
if (options.family != .ip4) {
results_buffer[results_index] = .{ .address = .{ .ip6 = .loopback(options.port) } };
results_index += 1;
}
if (options.family != .ip6) {
results_buffer[results_index] = .{ .address = .{ .ip4 = .loopback(options.port) } };
results_index += 1;
}
if (options.canonical_name_buffer) |buf| {
const canon_name = "localhost";
const canon_name_dest = buf[0..canon_name.len];
canon_name_dest.* = canon_name.*;
results_buffer[results_index] = .{ .canonical_name = .{ .bytes = canon_name_dest } };
results_index += 1;
}
try resolved.putAll(t_io, results_buffer[0..results_index]);
return;
}
if (native_os == .linux) return t.lookupDnsSearch(host_name, resolved, options);
comptime assert(is_windows);
var DnsQueryEx = t.dl.DnsQueryEx.load(.acquire);
// var DnsCancelQuery = t.dl.DnsCancelQuery.load(.acquire);
var DnsFree = t.dl.DnsFree.load(.acquire);
if (DnsQueryEx == null or
// DnsCancelQuery == null 或
DnsFree == null)
{
const dnsapi_dll = t.dl.dnsapi_dll.load(.acquire) orelse dnsapi_dll: {
try Thread.checkCancel();
var dnsapi_dll: *anyopaque = undefined;
switch (windows.ntdll.LdrLoadDll(null, null, &.init(
&.{ 'd', 'n', 's', 'a', 'p', 'i', '.', 'd', 'l', 'l' },
), &dnsapi_dll)) {
.SUCCESS => {},
.DLL_NOT_FOUND => return error.Unexpected,
else => |status| return windows.unexpectedStatus(status),
}
const handle = t.dl.dnsapi_dll.cmpxchgStrong(null, dnsapi_dll, .release, .monotonic) orelse
break :dnsapi_dll dnsapi_dll;
switch (windows.ntdll.LdrUnloadDll(dnsapi_dll)) {
.SUCCESS => break :dnsapi_dll handle.?,
else => |status| return windows.unexpectedStatus(status),
}
};
switch (windows.ntdll.LdrGetProcedureAddress(dnsapi_dll, &.init(
&.{ 'D', 'n', 's', 'Q', 'u', 'e', 'r', 'y', 'E', 'x' },
), 0, @ptrCast(&DnsQueryEx))) {
.SUCCESS => t.dl.DnsQueryEx.store(DnsQueryEx, .release),
else => |status| return windows.unexpectedStatus(status),
}
// switch (windows.ntdll.LdrGetProcedureAddress(dnsapi_dll, &.init(
// &.{ 'D', 'n', 's', 'C', 'a', 'n', 'c', 'e', 'l', 'Q', 'u', 'e', 'r', 'y' },
// ), 0, @ptrCast(&DnsCancelQuery))) {
// .SUCCESS => t.dl.DnsCancelQuery.store(DnsCancelQuery, .release),
// else => |status| return windows.unexpectedStatus(status),
// }
switch (windows.ntdll.LdrGetProcedureAddress(dnsapi_dll, &.init(
&.{ 'D', 'n', 's', 'F', 'r', 'e', 'e' },
), 0, @ptrCast(&DnsFree))) {
.SUCCESS => t.dl.DnsFree.store(DnsFree, .release),
else => |status| return windows.unexpectedStatus(status),
}
}
try Thread.checkCancel();
const current_thread = Thread.current;
var lookup_dns: LookupDnsWindows = .{
.threaded = t,
.thread = if (current_thread) |thread| thread.handle else undefined,
.resolved = resolved,
.options = options,
.results = .{
.Version = 1,
.QueryStatus = undefined,
.QueryOptions = undefined,
.pQueryRecords = undefined,
.Reserved = undefined,
},
.done = false,
};
var host_name_w: [HostName.max_len:0]windows.WCHAR = undefined;
host_name_w[
std.unicode.wtf8ToWtf16Le(&host_name_w, name) catch |err| switch (err) {
error.InvalidWtf8 => return error.UnknownHostName,
}
] = 0;
// var cancel_token: windows.DNS.QUERY.CANCEL = undefined;
// 先尝试执行同步非网络查询,以规避多种错误
switch (DnsQueryEx.?(&.{
.Version = 1,
.QueryName = &host_name_w,
.QueryType = if (options.family == .ip4) .A else .AAAA,
.QueryOptions = .{
.NO_WIRE_QUERY = true,
.NO_HOSTS_FILE = true, // 在上方处理
.ADDRCONFIG = true,
.DUAL_ADDR = options.family == null,
},
}, &lookup_dns.results, null)) {
.SUCCESS => try lookup_dns.completedFallible(),
// 必须等待 APC 例程。
.DNS_REQUEST_PENDING => unreachable, // `pQueryCompletionCallback` 为 `null`
.DNS_ERROR_RECORD_DOES_NOT_EXIST => switch (DnsQueryEx.?(&.{
.Version = 1,
.QueryName = &host_name_w,
.QueryType = if (options.family == .ip4) .A else .AAAA,
.QueryOptions = .{
.NO_HOSTS_FILE = true, // 在上方处理
.ADDRCONFIG = true,
.DUAL_ADDR = options.family == null,
.MULTICAST_WAIT = true,
},
.pQueryCompletionCallback = if (current_thread) |_| &LookupDnsWindows.completed else null,
}, &lookup_dns.results,
// &cancel_token,
null)) {
.SUCCESS => try lookup_dns.completedFallible(),
// 必须等待 APC 例程。
.DNS_REQUEST_PENDING => {
assert(current_thread != null); // `pQueryCompletionCallback` 为 `null`
while (!@atomicLoad(bool, &lookup_dns.done, .acquire)) {
// 一旦到达此处,就必须等到操作完成后
// 才能从函数返回,届时才能释放对 `host_name_w`、
// `lookup_dns.results` 和 `cancel_token` 的引用。
const alertable_syscall = AlertableSyscall.start() catch |err| switch (err) {
error.Canceled => |e| {
// _ = DnsCancelQuery.?(&cancel_token);
while (!@atomicLoad(bool, &lookup_dns.done, .acquire)) waitForApcOrAlert();
return e;
},
};
waitForApcOrAlert();
alertable_syscall.finish();
}
},
else => |status| lookup_dns.results.QueryStatus = status,
},
else => |status| lookup_dns.results.QueryStatus = status,
}
switch (lookup_dns.results.QueryStatus) {
.SUCCESS => return,
.DNS_REQUEST_PENDING => unreachable, // 已经处理
.INVALID_NAME,
.DNS_ERROR_RCODE_NAME_ERROR,
.DNS_INFO_NO_RECORDS,
.DNS_ERROR_INVALID_NAME_CHAR,
.DNS_ERROR_RECORD_DOES_NOT_EXIST,
=> return error.UnknownHostName,
.TIMEOUT => return error.NameServerFailure,
else => |err| return windows.unexpectedError(err),
}
}
if (native_os == .openbsd) {
// TODO 使用 getaddrinfo_async / asr_abort
}
if (native_os == .freebsd) {
// TODO 使用 dnsres_getaddrinfo
}
if (is_darwin) {
// TODO 使用 CFHostStartInfoResolution / CFHostCancelInfoResolution
}
if (builtin.link_libc) {
// 此操作系统没有异步解析的方式,只能
// 使用 getaddrinfo。
var name_buffer: [HostName.max_len:0]u8 = undefined;
@memcpy(name_buffer[0..name.len], name);
name_buffer[name.len] = 0;
const name_c = name_buffer[0..name.len :0];
var port_buffer: [8]u8 = undefined;
const port_c = std.mem.printSentinel(&port_buffer, "{d}", .{options.port}, 0) catch unreachable;
const family: i32 = if (options.family) |f| switch (f) {
.ip4 => posix.AF.INET,
.ip6 => posix.AF.INET6,
} else posix.AF.UNSPEC;
const hints: posix.addrinfo = .{
.flags = .{ .CANONNAME = options.canonical_name_buffer != null, .NUMERICSERV = true },
.family = family,
.socktype = posix.SOCK.STREAM,
.protocol = posix.IPPROTO.TCP,
.canonname = null,
.addr = null,
.addrlen = 0,
.next = null,
};
var res: ?*posix.addrinfo = null;
const syscall: Syscall = try .start();
while (true) {
switch (posix.system.getaddrinfo(name_c.ptr, port_c.ptr, &hints, &res)) {
@as(posix.system.EAI, @fromBackingInt(@intCast(0))) => {
syscall.finish();
break;
},
.SYSTEM => switch (posix.errno(-1)) {
.INTR => {
try syscall.checkCancel();
continue;
},
else => |e| {
syscall.finish();
return posix.unexpectedErrno(e);
},
},
else => |e| {
syscall.finish();
switch (e) {
.ADDRFAMILY => return error.AddressFamilyUnsupported,
.AGAIN => return error.NameServerFailure,
.FAIL => return error.NameServerFailure,
.FAMILY => return error.AddressFamilyUnsupported,
.MEMORY => return error.SystemResources,
.NODATA => return error.UnknownHostName,
.NONAME => return error.UnknownHostName,
else => return error.Unexpected,
}
},
}
}
defer if (res) |some| posix.system.freeaddrinfo(some);
var it = res;
var canon_name: ?[*:0]const u8 = null;
while (it) |info| : (it = info.next) {
const addr = info.addr orelse continue;
try resolved.putOne(t_io, .{ .address = addressFromPosix(@alignCast(@fieldParentPtr("any", addr))) });
if (info.canonname) |n| {
if (canon_name == null) {
canon_name = n;
}
}
}
if (canon_name) |n| {
if (copyCanon(options.canonical_name_buffer, std.mem.sliceTo(n, 0))) |canon| {
try resolved.putOne(t_io, .{ .canonical_name = canon });
}
}
return;
}
return error.OptionUnsupported;
}
fn lockStderr(userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const current_thread_id = Thread.currentId();
if (@atomicLoad(std.Thread.Id, &t.stderr_mutex_locker, .unordered) != current_thread_id) {
try mutexLock(&t.stderr_mutex);
assert(t.stderr_mutex_lock_count == 0);
@atomicStore(std.Thread.Id, &t.stderr_mutex_locker, current_thread_id, .unordered);
}
t.stderr_mutex_lock_count += 1;
return initLockedStderr(t, terminal_mode);
}
fn tryLockStderr(userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!?Io.LockedStderr {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const current_thread_id = Thread.currentId();
if (@atomicLoad(std.Thread.Id, &t.stderr_mutex_locker, .unordered) != current_thread_id) {
if (!t.stderr_mutex.tryLock()) return null;
assert(t.stderr_mutex_lock_count == 0);
@atomicStore(std.Thread.Id, &t.stderr_mutex_locker, current_thread_id, .unordered);
}
t.stderr_mutex_lock_count += 1;
return try initLockedStderr(t, terminal_mode);
}
fn initLockedStderr(t: *Threaded, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr {
if (!t.stderr_writer_initialized) {
const io_t = io(t);
if (is_windows) t.stderr_writer.file = .stderr();
t.stderr_writer.io = io_t;
t.stderr_writer_initialized = true;
t.scanEnviron();
const NO_COLOR = t.environ.exist.NO_COLOR;
const CLICOLOR_FORCE = t.environ.exist.CLICOLOR_FORCE;
t.stderr_mode = terminal_mode orelse try .detect(io_t, t.stderr_writer.file, NO_COLOR, CLICOLOR_FORCE);
}
return .{
.file_writer = &t.stderr_writer,
.terminal_mode = terminal_mode orelse t.stderr_mode,
};
}
fn unlockStderr(userdata: ?*anyopaque) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (t.stderr_writer.err == null) t.stderr_writer.interface.flush() catch {};
if (t.stderr_writer.err) |err| {
switch (err) {
error.Canceled => recancelInner(),
else => {},
}
t.stderr_writer.err = null;
}
t.stderr_writer.interface.end = 0;
t.stderr_writer.interface.buffer = &.{};
t.stderr_mutex_lock_count -= 1;
if (t.stderr_mutex_lock_count == 0) {
@atomicStore(std.Thread.Id, &t.stderr_mutex_locker, Thread.invalid_id, .unordered);
mutexUnlock(&t.stderr_mutex);
}
}
fn processCurrentPath(userdata: ?*anyopaque, buffer: []u8) process.CurrentPathError!usize {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (is_windows) {
var wtf16le_buf: [windows.PATH_MAX_WIDE:0]u16 = undefined;
const n = windows.ntdll.RtlGetCurrentDirectory_U(wtf16le_buf.len * 2 + 2, &wtf16le_buf) / 2;
if (n == 0) return error.Unexpected;
assert(n <= wtf16le_buf.len);
const wtf16le_slice = wtf16le_buf[0..n];
var end_index: usize = 0;
var it = std.unicode.Wtf16LeIterator.init(wtf16le_slice);
while (it.nextCodepoint()) |codepoint| {
const seq_len = std.unicode.utf8CodepointSequenceLength(codepoint) catch unreachable;
if (end_index + seq_len >= buffer.len)
return error.NameTooLong;
end_index += std.unicode.wtf8Encode(codepoint, buffer[end_index..]) catch unreachable;
}
return end_index;
}
if (native_os == .wasi and !builtin.link_libc) {
if (buffer.len == 0) return error.NameTooLong;
buffer[0] = '.';
return 1;
}
return processCurrentPathPosix(buffer);
}
fn processCurrentPathPosix(buffer: []u8) process.CurrentPathError!usize {
const err: posix.E = if (builtin.link_libc) err: {
const c_err = if (std.c.getcwd(buffer.ptr, buffer.len)) |_| 0 else std.c._errno().*;
break :err @fromBackingInt(@intCast(c_err));
} else err: {
break :err posix.errno(posix.system.getcwd(buffer.ptr, buffer.len));
};
switch (err) {
.SUCCESS => return std.mem.findScalar(u8, buffer, 0).?,
.NOENT => return error.CurrentDirUnlinked,
.RANGE => return error.NameTooLong,
// 在 Linux 上,此错误表示缓冲区可能已经足够大,但路径超过 PATH_MAX,长到系统调用无法处理。
// https://github.com/torvalds/linux/blob/e4b275531887fef7f7d8a7284bfc32f0fbbd4208/fs/d_path.c#L406-L407
//
// 将此错误与 RANGE 区分,是因为增大缓冲区始终无法恢复此 NAMETOOLONG 错误。恢复方法是逐段重建当前工作目录,例如从“.”开始反向遍历文件系统。许多 libc 的 `getcwd` 实现会自动回退到遍历文件系统的方式。
//
//
//
//
//
.NAMETOOLONG => return error.PathExceedsLimit,
.FAULT => |e| return errnoBug(e),
.INVAL => |e| return errnoBug(e),
else => return posix.unexpectedErrno(err),
}
}
fn processSetCurrentDir(userdata: ?*anyopaque, dir: Dir) process.SetCurrentDirError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (native_os == .wasi) return error.OperationUnsupported;
if (is_windows) {
var dir_path_buf: [windows.PATH_MAX_WIDE]u16 = undefined;
const dir_path = try GetFinalPathNameByHandle(dir.handle, .{}, &dir_path_buf);
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.RtlSetCurrentDirectory_U(&.init(dir_path))) {
.SUCCESS => return syscall.finish(),
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.OBJECT_PATH_SYNTAX_BAD => |err| return syscall.ntstatusBug(err),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| return syscall.unexpectedNtstatus(status),
};
}
return fchdir(dir.handle);
}
fn processSetCurrentPath(userdata: ?*anyopaque, path: []const u8) process.SetCurrentPathError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
if (native_os == .wasi) return error.OperationUnsupported;
if (is_windows) {
var path_w_buf: [windows.PATH_MAX_WIDE]u16 = undefined;
const len = std.unicode.calcWtf16LeLen(path) catch return error.InvalidWtf8;
if (len > path_w_buf.len) return error.NameTooLong;
const path_w_len = std.unicode.wtf8ToWtf16Le(&path_w_buf, path) catch |err| switch (err) {
error.InvalidWtf8 => unreachable, // 已经验证
};
const path_w = path_w_buf[0..path_w_len];
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.RtlSetCurrentDirectory_U(&.init(path_w))) {
.SUCCESS => return syscall.finish(),
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.INVALID_PARAMETER => |err| return syscall.ntstatusBug(err),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.OBJECT_PATH_SYNTAX_BAD => |err| return syscall.ntstatusBug(err),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| return syscall.unexpectedNtstatus(status),
};
}
return chdir(path);
}
pub const PosixAddress = extern union {
any: posix.sockaddr,
in: posix.sockaddr.in,
in6: posix.sockaddr.in6,
};
const UnixAddress = extern union {
any: posix.sockaddr,
un: posix.sockaddr.un,
};
pub fn posixAddressFamily(a: *const IpAddress) posix.sa_family_t {
return switch (a.*) {
.ip4 => posix.AF.INET,
.ip6 => posix.AF.INET6,
};
}
pub fn addressFromPosix(posix_address: *const PosixAddress) IpAddress {
return switch (posix_address.any.family) {
posix.AF.INET => .{ .ip4 = address4FromPosix(&posix_address.in) },
posix.AF.INET6 => .{ .ip6 = address6FromPosix(&posix_address.in6) },
else => .{ .ip4 = .loopback(0) },
};
}
pub fn addressToPosix(a: *const IpAddress, storage: *PosixAddress) posix.socklen_t {
return switch (a.*) {
.ip4 => |ip4| {
storage.in = address4ToPosix(ip4);
return @sizeOf(posix.sockaddr.in);
},
.ip6 => |*ip6| {
storage.in6 = address6ToPosix(ip6);
return @sizeOf(posix.sockaddr.in6);
},
};
}
fn addressUnixToPosix(a: *const net.UnixAddress, storage: *UnixAddress) posix.socklen_t {
storage.un.family = posix.AF.UNIX;
var path_len = switch (native_os) {
.windows => @min(a.path.len, storage.un.path.len),
else => a.path.len,
};
// 在 AFD API 中,`sockaddr.un` 仅供信息展示,
// 因此使用通常与路径最相关的后缀部分。
@memcpy(storage.un.path[0..path_len], a.path[a.path.len - path_len ..]);
if (storage.un.path.len - path_len > 0) {
@branchHint(.likely);
storage.un.path[path_len] = 0;
path_len += 1;
}
switch (native_os) {
.windows => {
if (storage.un.path[0] == 0) @memset(storage.un.path[path_len..], 0);
return @sizeOf(posix.sockaddr.un);
},
else => return @intCast(@offsetOf(posix.sockaddr.un, "path") + path_len),
}
}
fn address4FromPosix(in: *const posix.sockaddr.in) net.Ip4Address {
// `in.addr` 中采用网络字节序的地址已经是所需字节序。
const addr_bytes: *const [4]u8 = @ptrCast(&in.addr);
return .{
.port = std.mem.bigToNative(u16, in.port),
.bytes = addr_bytes.*,
};
}
fn address6FromPosix(in6: *const posix.sockaddr.in6) net.Ip6Address {
return .{
.port = std.mem.bigToNative(u16, in6.port),
.bytes = in6.addr,
.flow = in6.flowinfo,
.interface = .{ .index = in6.scope_id },
};
}
fn address4ToPosix(a: net.Ip4Address) posix.sockaddr.in {
// `a.bytes` 的字节序已等同于网络字节序地址。
const addr_raw: *align(1) const u32 = @ptrCast(&a.bytes);
return .{
.port = std.mem.nativeToBig(u16, a.port),
.addr = addr_raw.*,
};
}
fn address6ToPosix(a: *const net.Ip6Address) posix.sockaddr.in6 {
return .{
.port = std.mem.nativeToBig(u16, a.port),
.flowinfo = a.flow,
.addr = a.bytes,
.scope_id = a.interface.index,
};
}
pub fn errnoBug(err: posix.E) Io.UnexpectedError {
if (is_debug) std.debug.panic("programmer bug caused syscall error: {t}", .{err});
return error.Unexpected;
}
pub fn posixSocketModeProtocol(family: posix.sa_family_t, mode: net.Socket.Mode, protocol: ?net.Protocol) !struct { u32, u32 } {
return .{
switch (mode) {
.stream => posix.SOCK.STREAM,
.dgram => posix.SOCK.DGRAM,
.seqpacket => posix.SOCK.SEQPACKET,
.raw => posix.SOCK.RAW,
.rdm => if (@hasDecl(posix.SOCK, "RDM")) posix.SOCK.RDM else return error.OptionUnsupported,
},
if (protocol) |p| @backingInt(p) else if (is_windows) switch (family) {
posix.AF.UNIX => switch (mode) {
.stream => 0,
else => return error.ProtocolUnsupportedByAddressFamily,
},
posix.AF.INET, posix.AF.INET6 => @backingInt(@as(net.Protocol, switch (mode) {
.stream => .tcp,
.dgram => .udp,
else => return error.ProtocolUnsupportedByAddressFamily,
})),
else => return error.ProtocolUnsupportedByAddressFamily,
} else 0,
};
}
pub fn recoverableOsBugDetected() void {
if (is_debug) unreachable;
}
pub fn clockToPosix(clock: Io.Clock) posix.clockid_t {
return switch (clock) {
.real => posix.CLOCK.REALTIME,
.awake => switch (native_os) {
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => posix.CLOCK.UPTIME_RAW,
else => posix.CLOCK.MONOTONIC,
},
.boot => switch (native_os) {
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => posix.CLOCK.MONOTONIC_RAW,
// 在 FreeBSD 衍生系统上使用 MONOTONIC_FAST,
// 因为目前不会损失精度。
.freebsd, .dragonfly => posix.CLOCK.MONOTONIC_FAST,
// 在 Linux 上使用 BOOTTIME 而非 MONOTONIC,
// 因为前者在系统挂起时仍计时。
.linux => posix.CLOCK.BOOTTIME,
// 在其他 posix 系统上,MONOTONIC 通常最快,且
// 在挂起期间继续计时。
else => posix.CLOCK.MONOTONIC,
},
.cpu_process => posix.CLOCK.PROCESS_CPUTIME_ID,
.cpu_thread => posix.CLOCK.THREAD_CPUTIME_ID,
};
}
fn clockToWasi(clock: Io.Clock) std.os.wasi.clockid_t {
return switch (clock) {
.real => .REALTIME,
.awake => .MONOTONIC,
.boot => .MONOTONIC,
.cpu_process => .PROCESS_CPUTIME_ID,
.cpu_thread => .THREAD_CPUTIME_ID,
};
}
pub const linux_statx_request: std.os.linux.STATX = .{
.TYPE = true,
.MODE = true,
.ATIME = true,
.MTIME = true,
.CTIME = true,
.INO = true,
.SIZE = true,
.NLINK = true,
.BLOCKS = true,
};
pub const linux_statx_check: std.os.linux.STATX = .{
.TYPE = true,
.MODE = true,
.ATIME = false,
.MTIME = true,
.CTIME = true,
.INO = true,
.SIZE = true,
.NLINK = true,
.BLOCKS = false,
};
pub fn statFromLinux(stx: *const std.os.linux.Statx) Io.UnexpectedError!File.Stat {
const actual_mask_int: u32 = @bitCast(stx.mask);
const wanted_mask_int: u32 = @bitCast(linux_statx_check);
if ((actual_mask_int | wanted_mask_int) != actual_mask_int) return error.Unexpected;
return .{
.inode = stx.ino,
.nlink = stx.nlink,
.size = stx.size,
.permissions = .fromMode(stx.mode),
.kind = statxKind(stx.mode),
.atime = if (!stx.mask.ATIME) null else .{
.nanoseconds = @intCast(@as(i128, stx.atime.sec) * std.time.ns_per_s + stx.atime.nsec),
},
.mtime = .{ .nanoseconds = @intCast(@as(i128, stx.mtime.sec) * std.time.ns_per_s + stx.mtime.nsec) },
.ctime = .{ .nanoseconds = @intCast(@as(i128, stx.ctime.sec) * std.time.ns_per_s + stx.ctime.nsec) },
.block_size = if (stx.mask.BLOCKS) stx.blksize else 1,
};
}
pub fn statxKind(stx_mode: u16) File.Kind {
return switch (stx_mode & std.os.linux.S.IFMT) {
std.os.linux.S.IFDIR => .directory,
std.os.linux.S.IFCHR => .character_device,
std.os.linux.S.IFBLK => .block_device,
std.os.linux.S.IFREG => .file,
std.os.linux.S.IFIFO => .named_pipe,
std.os.linux.S.IFLNK => .sym_link,
std.os.linux.S.IFSOCK => .unix_domain_socket,
else => .unknown,
};
}
pub fn statFromPosix(st: *const posix.Stat) File.Stat {
const atime = st.atime();
const mtime = st.mtime();
const ctime = st.ctime();
return .{
.inode = st.ino,
.nlink = st.nlink,
.size = @bitCast(st.size),
.permissions = .fromMode(st.mode),
.kind = k: {
const m = st.mode & posix.S.IFMT;
switch (m) {
posix.S.IFBLK => break :k .block_device,
posix.S.IFCHR => break :k .character_device,
posix.S.IFDIR => break :k .directory,
posix.S.IFIFO => break :k .named_pipe,
posix.S.IFLNK => break :k .sym_link,
posix.S.IFREG => break :k .file,
posix.S.IFSOCK => break :k .unix_domain_socket,
else => {},
}
if (native_os == .illumos) switch (m) {
posix.S.IFDOOR => break :k .door,
posix.S.IFPORT => break :k .event_port,
else => {},
};
break :k .unknown;
},
.atime = timestampFromPosix(&atime),
.mtime = timestampFromPosix(&mtime),
.ctime = timestampFromPosix(&ctime),
.block_size = @intCast(st.blksize),
};
}
fn statFromWasi(st: *const std.os.wasi.filestat_t) File.Stat {
return .{
.inode = st.ino,
.nlink = st.nlink,
.size = @bitCast(st.size),
.permissions = .default_file,
.kind = switch (st.filetype) {
.BLOCK_DEVICE => .block_device,
.CHARACTER_DEVICE => .character_device,
.DIRECTORY => .directory,
.SYMBOLIC_LINK => .sym_link,
.REGULAR_FILE => .file,
.SOCKET_STREAM, .SOCKET_DGRAM => .unix_domain_socket,
else => .unknown,
},
.atime = .fromNanoseconds(st.atim),
.mtime = .fromNanoseconds(st.mtim),
.ctime = .fromNanoseconds(st.ctim),
.block_size = 1,
};
}
pub fn timestampFromPosix(timespec: *const posix.timespec) Io.Timestamp {
return .{ .nanoseconds = nanosecondsFromPosix(timespec) };
}
pub fn nanosecondsFromPosix(timespec: *const posix.timespec) i96 {
return @intCast(@as(i128, timespec.sec) * std.time.ns_per_s + timespec.nsec);
}
fn timestampToPosix(nanoseconds: i96) posix.timespec {
return .{
.sec = @intCast(@divFloor(nanoseconds, std.time.ns_per_s)),
.nsec = @intCast(@mod(nanoseconds, std.time.ns_per_s)),
};
}
pub fn setTimestampToPosix(set_ts: File.SetTimestamp) posix.timespec {
return switch (set_ts) {
.unchanged => posix.UTIME.OMIT,
.now => posix.UTIME.NOW,
.new => |t| timestampToPosix(t.nanoseconds),
};
}
pub fn pathToPosix(file_path: []const u8, buffer: *[posix.PATH_MAX]u8) Dir.PathNameError![:0]u8 {
if (std.mem.containsAtLeastScalar(u8, file_path, 0, 1)) return error.BadPathName;
// 使用 >= 而非 >,为空字节留出空间
if (file_path.len >= buffer.len) return error.NameTooLong;
@memcpy(buffer[0..file_path.len], file_path);
buffer[file_path.len] = 0;
return buffer[0..file_path.len :0];
}
fn lookupDnsSearch(
t: *Threaded,
host_name: HostName,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
) (HostName.LookupError || Io.QueueClosedError)!void {
const t_io = io(t);
const rc = HostName.ResolvConf.init(t_io) catch return error.ResolvConfParseFailed;
// 计算点的数量;若 >=ndots 或名称以点结尾,
// 则禁止搜索,因为这显式请求全局作用域。
const dots = std.mem.countScalar(u8, host_name.bytes, '.');
const search_len = if (dots >= rc.ndots or std.mem.endsWith(u8, host_name.bytes, ".")) 0 else rc.search_len;
const search = rc.search_buffer[0..search_len];
var canon_name = host_name.bytes;
// 规范化时去除末尾点号,若有多个尾随点号则失败。
if (std.mem.endsWith(u8, canon_name, ".")) canon_name.len -= 1;
if (std.mem.endsWith(u8, canon_name, ".")) return error.UnknownHostName;
// 将附加了搜索域的名称写入 `canon_name`。
// 这既提供所需的默认规范名称(当请求名称不是 CNAME 记录时),
// 也作为向 `lookupDns` 传递
// 完整请求名称的缓冲区。
var local_buf: [HostName.max_len]u8 = undefined;
const canon_buf = options.canonical_name_buffer orelse &local_buf;
@memcpy(canon_buf[0..canon_name.len], canon_name);
canon_buf[canon_name.len] = '.';
var it = std.mem.tokenizeAny(u8, search, " \t");
while (it.next()) |token| {
@memcpy(canon_buf[canon_name.len + 1 ..][0..token.len], token);
const lookup_canon_name = canon_buf[0 .. canon_name.len + 1 + token.len];
if (t.lookupDns(lookup_canon_name, &rc, resolved, options)) |result| {
return result;
} else |err| switch (err) {
error.UnknownHostName, error.NoAddressReturned => continue,
else => |e| return e,
}
}
const lookup_canon_name = canon_buf[0..canon_name.len];
return t.lookupDns(lookup_canon_name, &rc, resolved, options);
}
fn lookupDns(
t: *Threaded,
lookup_canon_name: []const u8,
rc: *const HostName.ResolvConf,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
) (HostName.LookupError || Io.QueueClosedError)!void {
const t_io = io(t);
const family_records: [2]struct { af: IpAddress.Family, rr: HostName.DnsRecord } = .{
.{ .af = .ip6, .rr = .A },
.{ .af = .ip4, .rr = .AAAA },
};
var query_buffers: [2][280]u8 = undefined;
var answer_buffer: [2 * 512]u8 = undefined;
var queries_buffer: [2][]const u8 = undefined;
var answers_buffer: [2][]const u8 = undefined;
var nq: usize = 0;
var answer_buffer_i: usize = 0;
for (family_records) |fr| {
if (options.family != fr.af) {
var entropy: [2]u8 = undefined;
random(t, &entropy);
const len = writeResolutionQuery(&query_buffers[nq], 0, lookup_canon_name, 1, fr.rr, entropy);
queries_buffer[nq] = query_buffers[nq][0..len];
nq += 1;
}
}
var ip4_mapped_buffer: [HostName.ResolvConf.max_nameservers]IpAddress = undefined;
const ip4_mapped = ip4_mapped_buffer[0..rc.nameservers_len];
var any_ip6 = false;
for (rc.nameservers(), ip4_mapped) |*ns, *m| {
m.* = .{ .ip6 = .fromAny(ns.*) };
any_ip6 = any_ip6 or ns.* == .ip6;
}
var socket = s: {
if (any_ip6) ip6: {
const ip6_addr: IpAddress = .{ .ip6 = .unspecified(0) };
const socket = ip6_addr.bind(t_io, .{ .ip6_only = false, .mode = .dgram }) catch |err| switch (err) {
error.AddressFamilyUnsupported => break :ip6,
else => |e| return e,
};
break :s socket;
}
any_ip6 = false;
const ip4_addr: IpAddress = .{ .ip4 = .unspecified(0) };
const socket = try ip4_addr.bind(t_io, .{ .mode = .dgram });
break :s socket;
};
defer socket.close(t_io);
const mapped_nameservers = if (any_ip6) ip4_mapped else rc.nameservers();
const queries = queries_buffer[0..nq];
const answers = answers_buffer[0..queries.len];
var answers_remaining = answers.len;
for (answers) |*answer| answer.len = 0;
// 选择启动时钟,因为计算机挂起的时间也应计入
// 等待外部消息到达的时间。
const clock: Io.Clock = .boot;
var now_ts = clock.now(t_io);
const final_ts = now_ts.addDuration(.fromSeconds(rc.timeout_seconds));
const attempt_duration: Io.Duration = .{
.nanoseconds = (std.time.ns_per_s / rc.attempts) * @as(i96, rc.timeout_seconds),
};
send: while (now_ts.nanoseconds < final_ts.nanoseconds) : (now_ts = clock.now(t_io)) {
const timeout: Io.Timeout = .{ .deadline = .{
.raw = now_ts.addDuration(attempt_duration),
.clock = clock,
} };
const max_messages = queries_buffer.len * HostName.ResolvConf.max_nameservers;
{
var message_buffer: [max_messages]net.OutgoingMessage = undefined;
var message_i: usize = 0;
for (queries, answers) |query, *answer| {
if (answer.len != 0) continue;
for (mapped_nameservers) |*ns| {
message_buffer[message_i] = .{
.address = ns,
.data_ptr = query.ptr,
.data_len = query.len,
};
message_i += 1;
}
}
const send_err, _ = socket.sendManyTimeout(t_io, message_buffer[0..message_i], .{}, timeout);
if (send_err) |err| switch (err) {
error.Canceled => |e| return e,
error.Timeout => continue :send,
else => {},
};
}
while (true) {
var message_buffer: [max_messages]net.IncomingMessage = @splat(.init);
const buf = answer_buffer[answer_buffer_i..];
const recv_err, const recv_n = socket.receiveManyTimeout(t_io, &message_buffer, buf, .{}, timeout);
for (message_buffer[0..recv_n]) |*received_message| {
const reply = received_message.data;
// 忽略无法识别的数据包。
if (reply.len < 4) continue;
// 忽略来自未曾发送目标地址的回复。
const ns = for (mapped_nameservers) |*ns| {
if (received_message.from.eql(ns)) break ns;
} else {
continue;
};
// 查找此答案对应的查询(如果有)
const query, const answer = for (queries, answers) |query, *answer| {
if (reply[0] == query[0] and reply[1] == query[1]) break .{ query, answer };
} else {
continue;
};
if (answer.len != 0) continue;
// 仅接受肯定或否定响应;服务器故障时立即重试,
// 忽略拒绝等其他所有状态码。
switch (reply[3] & 15) {
0, 3 => {
answer.* = reply;
answer_buffer_i += reply.len;
answers_remaining -= 1;
if (answer_buffer.len - answer_buffer_i == 0) break :send;
if (answers_remaining == 0) break :send;
},
2 => {
socket.sendTimeout(t_io, ns, query, timeout) catch |err| switch (err) {
error.Canceled => |e| return e,
error.Timeout => continue :send,
else => {},
};
continue;
},
else => continue,
}
}
if (recv_err) |err| switch (err) {
error.Canceled => |e| return e,
error.Timeout => continue :send,
else => continue,
};
}
} else {
return error.NameServerFailure;
}
var addresses_len: usize = 0;
var canonical_name: ?HostName = null;
for (answers) |answer| {
var it = HostName.DnsResponse.init(answer) catch {
// 此处可能可以向结果队列添加诊断信息。
continue;
};
while (it.next() catch {
// 此处可能可以向结果队列添加诊断信息。
continue;
}) |record| switch (record.rr) {
.A => {
const data = record.packet[record.data_off..][0..record.data_len];
if (data.len != 4) return error.InvalidDnsARecord;
try resolved.putOne(t_io, .{ .address = .{ .ip4 = .{
.bytes = data[0..4].*,
.port = options.port,
} } });
addresses_len += 1;
},
.AAAA => {
const data = record.packet[record.data_off..][0..record.data_len];
if (data.len != 16) return error.InvalidDnsAAAARecord;
try resolved.putOne(t_io, .{ .address = .{ .ip6 = .{
.bytes = data[0..16].*,
.port = options.port,
} } });
addresses_len += 1;
},
.CNAME => {
if (options.canonical_name_buffer) |buf| {
_, canonical_name = HostName.expand(
record.packet,
record.data_off,
buf,
) catch return error.InvalidDnsCnameRecord;
}
},
_ => continue,
};
}
if (options.canonical_name_buffer != null) {
try resolved.putOne(t_io, .{
.canonical_name = canonical_name orelse .{ .bytes = lookup_canon_name },
});
}
if (addresses_len == 0) return error.NoAddressReturned;
}
fn lookupHosts(
t: *Threaded,
host_name: HostName,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
) !void {
const path_w = if (is_windows) path_w: {
var path_w_buf: [windows.PATH_MAX_WIDE:0]u16 = undefined;
const system_dir = windows.getSystemDirectoryWtf16Le();
const suffix = [_]u16{
'\\', 'd', 'r', 'i', 'v', 'e', 'r', 's', '\\', 'e', 't', 'c', '\\', 'h', 'o', 's', 't', 's',
};
@memcpy(path_w_buf[0..system_dir.len], system_dir);
@memcpy(path_w_buf[system_dir.len..][0..suffix.len], &suffix);
path_w_buf[system_dir.len + suffix.len] = 0;
break :path_w wToPrefixedFileW(null, &path_w_buf, .{}) catch |err| switch (err) {
error.FileNotFound,
error.AccessDenied,
=> return error.UnknownHostName,
error.Canceled => |e| return e,
else => {
// 此处可向结果队列添加更详细的诊断信息。
return error.DetectingNetworkConfigurationFailed;
},
};
};
const file = (if (is_windows)
dirOpenFileWtf16(null, path_w.span(), .{})
else
dirOpenFile(t, .cwd(), "/etc/hosts", .{})) catch |err| switch (err) {
error.FileNotFound,
error.NotDir,
error.AccessDenied,
=> return error.UnknownHostName,
error.Canceled => |e| return e,
else => {
// 此处可向结果队列添加更详细的诊断信息。
return error.DetectingNetworkConfigurationFailed;
},
};
defer fileClose(t, &.{file});
var line_buf: [512]u8 = undefined;
var file_reader = file.reader(t.io(), &line_buf);
return t.lookupHostsReader(host_name, resolved, options, &file_reader.interface) catch |err| switch (err) {
error.ReadFailed => switch (file_reader.err.?) {
error.Canceled => |e| return e,
else => {
// 此处可向结果队列添加更详细的诊断信息。
return error.DetectingNetworkConfigurationFailed;
},
},
error.Canceled,
error.Closed,
error.UnknownHostName,
=> |e| return e,
};
}
fn lookupHostsReader(
t: *Threaded,
host_name: HostName,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
reader: *Io.Reader,
) error{ ReadFailed, Canceled, UnknownHostName, Closed }!void {
const t_io = io(t);
var addresses_len: usize = 0;
var canonical_name: ?HostName = null;
while (true) {
const line = reader.takeDelimiterExclusive('\n') catch |err| switch (err) {
error.StreamTooLong => {
// 跳过过长的行。
_ = reader.discardDelimiterInclusive('\n') catch |er| switch (er) {
error.EndOfStream => break,
error.ReadFailed => |e| return e,
};
continue;
},
error.ReadFailed => |e| return e,
error.EndOfStream => break,
};
reader.toss(@min(1, reader.bufferedLen()));
var split_it = std.mem.splitScalar(u8, if (is_windows and std.mem.endsWith(u8, line, "\r"))
line[0 .. line.len - 1]
else
line, '#');
const no_comment_line = split_it.first();
var line_it = std.mem.tokenizeAny(u8, no_comment_line, " \t");
const ip_text = line_it.next() orelse continue;
var first_name_text: ?[]const u8 = null;
while (line_it.next()) |name_text| {
if (std.ascii.eqlIgnoreCase(name_text, host_name.bytes)) {
if (first_name_text == null) first_name_text = name_text;
break;
}
} else continue;
if (canonical_name == null) {
if (options.canonical_name_buffer) |buf| {
if (HostName.init(first_name_text.?)) |name_text| {
if (name_text.bytes.len <= buf.len) {
const canonical_name_dest = buf[0..name_text.bytes.len];
@memcpy(canonical_name_dest, name_text.bytes);
canonical_name = .{ .bytes = canonical_name_dest };
}
} else |_| {}
}
}
if (options.family != .ip6) {
if (IpAddress.parseIp4(ip_text, options.port)) |addr| {
try resolved.putOne(t_io, .{ .address = addr });
addresses_len += 1;
} else |_| {}
}
if (options.family != .ip4) {
if (IpAddress.parseIp6(ip_text, options.port)) |addr| {
try resolved.putOne(t_io, .{ .address = addr });
addresses_len += 1;
} else |_| {}
}
}
if (canonical_name) |canon_name| try resolved.putOne(t_io, .{ .canonical_name = canon_name });
if (addresses_len == 0) return error.UnknownHostName;
}
/// 将 DNS 解析查询数据包写入 `w`,最多 280 字节。
fn writeResolutionQuery(q: *[280]u8, op: u4, dname: []const u8, class: u8, ty: HostName.DnsRecord, entropy: [2]u8) usize {
// 此实现移植自 musl libc。
// 欢迎提供更符合 Zig 惯用风格的实现。
var name = dname;
if (std.mem.endsWith(u8, name, ".")) name.len -= 1;
assert(name.len <= 253);
const n = 17 + name.len + @intFromBool(name.len != 0);
// 构造查询模板,ID 将稍后填充。
q[0..2].* = entropy;
@memset(q[2..n], 0);
q[2] = @as(u8, op) * 8 + 1;
q[5] = 1;
@memcpy(q[13..][0..name.len], name);
var i: usize = 13;
var j: usize = undefined;
while (q[i] != 0) : (i = j + 1) {
j = i;
while (q[j] != 0 and q[j] != '.') : (j += 1) {}
// TODO: 确定此情况发生的条件,以及是否应将其视为错误。
//
if (j - i - 1 > 62) unreachable;
q[i - 1] = @intCast(j - i);
}
q[i + 1] = @backingInt(ty);
q[i + 3] = class;
return n;
}
const LookupDnsWindows = struct {
threaded: *Threaded,
thread: Thread.Handle,
resolved: *Io.Queue(HostName.LookupResult),
options: HostName.LookupOptions,
results: windows.DNS.QUERY.RESULT,
done: bool,
fn completed(
pQueryContext: ?*anyopaque,
pQueryResults: *windows.DNS.QUERY.RESULT,
) callconv(.winapi) void {
_ = pQueryContext;
const lookup_dns: *LookupDnsWindows = @fieldParentPtr("results", pQueryResults);
lookup_dns.completedFallible() catch |err| switch (err) {
error.Closed => unreachable, // 在 `netLookup` 返回之前,不得关闭 `resolved`。
error.Canceled => unreachable, // 从不可取消的线程调用
};
@atomicStore(bool, &lookup_dns.done, true, .release);
_ = windows.ntdll.NtAlertThread(lookup_dns.thread);
}
fn completedFallible(lookup_dns: *LookupDnsWindows) (Io.QueueClosedError || Io.Cancelable)!void {
assert(!lookup_dns.done);
const t = lookup_dns.threaded;
defer t.dl.DnsFree.raw.?(lookup_dns.results.pQueryRecords, .RecordList);
if (lookup_dns.results.QueryStatus != .SUCCESS) return;
const t_io = t.io();
var record_it = lookup_dns.results.pQueryRecords;
while (record_it) |record| : (record_it = record.pNext) switch (record.wType) {
else => {},
.A => try lookup_dns.resolved.putOne(t_io, .{
.address = .{ .ip4 = .{ .bytes = record.Data.A, .port = lookup_dns.options.port } },
}),
.AAAA => {
const ip6: net.Ip6Address = .{
.bytes = record.Data.AAAA,
.port = lookup_dns.options.port,
};
try lookup_dns.resolved.putOne(t_io, .{
.address = if (lookup_dns.options.family) |_| .{ .ip6 = ip6 } else .fromIp6(ip6),
});
},
};
if (lookup_dns.results.pQueryRecords) |record| {
if (lookup_dns.options.canonical_name_buffer) |buf| {
const name_wtf16 = std.mem.span(
@as([*:0]const windows.WCHAR, @ptrCast(@alignCast(record.pName))),
);
const len = std.unicode.wtf16LeToWtf8(buf, name_wtf16);
try lookup_dns.resolved.putOne(t_io, .{
.canonical_name = .{ .bytes = buf[0..len] },
});
}
}
}
};
fn copyCanon(canonical_name_buffer: ?*[HostName.max_len]u8, name: []const u8) ?HostName {
const buf = canonical_name_buffer orelse return null;
const dest = buf[0..name.len];
@memcpy(dest, name);
return .{ .bytes = dest };
}
/// Darwin XNU 7195.50.7.100.1 引入 __ulock_wait2,并将若干代码路径,尤其是 pthread_cond_t,迁移到该接口:
/// https://github.com/apple/darwin-xnu/commit/d4061fb0260b3ed486147341b72468f836ed6c8f#diff-08f993cc40af475663274687b7c326cc6c3031e0db3ac8de7b24624610616be6
///
/// 此 XNU 版本似乎对应 11.0.1:
/// https://kernelshaman.blogspot.com/2021/01/building-xnu-for-macos-big-sur-1101.html
///
/// ulock_wait() 使用 32 位微秒超时,其中 0 表示无限等待或无超时。
/// ulock_wait2() 使用 64 位纳秒超时,约定相同。
const darwin_supports_ulock_wait2 = builtin.os.version_range.semver.min.major >= 11;
fn doNothingSignalHandler(_: posix.SIG) callconv(.c) void {}
const WindowsEnvironStrings = struct {
PATH: ?[:0]const u16 = null,
PATHEXT: ?[:0]const u16 = null,
fn scan() WindowsEnvironStrings {
const peb = windows.peb();
assert(windows.ntdll.RtlEnterCriticalSection(peb.FastPebLock) == .SUCCESS);
defer assert(windows.ntdll.RtlLeaveCriticalSection(peb.FastPebLock) == .SUCCESS);
const ptr = peb.ProcessParameters.Environment;
var result: WindowsEnvironStrings = .{};
var i: usize = 0;
while (ptr[i] != 0) {
const key_start = i;
// 某些特殊环境变量以 = 开头,
// 因此若第一个字符是 =,就必须特殊处理,不把它当作键值分隔符。
// https://devblogs.microsoft.com/oldnewthing/20100506-00/?p=14133
//
if (ptr[key_start] == '=') i += 1;
while (ptr[i] != 0 and ptr[i] != '=') : (i += 1) {}
const key_w = ptr[key_start..i];
if (ptr[i] == '=') i += 1;
const value_start = i;
while (ptr[i] != 0) : (i += 1) {}
const value_w = ptr[value_start..i :0];
i += 1; // 跳过空字节
inline for (@typeInfo(WindowsEnvironStrings).@"struct".field_names) |field_name| {
const field_name_w = comptime std.unicode.wtf8ToWtf16LeStringLiteral(field_name);
if (windows.eqlIgnoreCaseWtf16(key_w, field_name_w)) @field(result, field_name) = value_w;
}
}
return result;
}
};
fn scanEnviron(t: *Threaded) void {
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
if (t.environ_initialized) return;
t.environ.scan(t.allocator);
t.environ_initialized = true;
}
fn processReplace(userdata: ?*anyopaque, options: process.ReplaceOptions) process.ReplaceError {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (!process.can_replace) return error.OperationUnsupported;
t.scanEnviron(); // 用于 PATH
const PATH = t.environ.string.PATH orelse default_PATH;
var arena_allocator = std.heap.ArenaAllocator.init(t.allocator);
defer arena_allocator.deinit();
const arena = arena_allocator.allocator();
const argv_buf = try arena.allocSentinel(?[*:0]const u8, options.argv.len, null);
for (options.argv, 0..) |arg, i| argv_buf[i] = (try arena.dupeSentinel(u8, arg, 0)).ptr;
const env_block = env_block: {
const prog_fd: i32 = -1;
if (options.environ_map) |environ_map| break :env_block try environ_map.createPosixBlock(arena, .{
.zig_progress_fd = prog_fd,
});
break :env_block try t.environ.process_environ.createPosixBlock(arena, .{
.zig_progress_fd = prog_fd,
});
};
if (is_darwin) if (t.spawnDarwin(
.replace,
options.exe,
argv_buf.ptr,
options.cwd,
env_block,
options.expand_arg0,
.none,
.inherit,
.inherit,
.inherit,
options.inherit_dirs,
options.inherit_files,
null,
options.start_suspended,
PATH,
)) |_| unreachable else |err| switch (err) {
else => |e| return e,
error.WouldBlock => return error.SystemResources,
error.FileTooBig,
error.NoSpaceLeft,
error.PathAlreadyExists,
error.SymLinkLoop,
error.NetworkNotFound,
error.PipeBusy,
error.AntivirusInterference,
=> return error.FileNotFound,
error.DeviceBusy,
error.NoDevice,
error.UnrecognizedVolume,
error.ReadOnlyFileSystem,
=> return error.FileSystem,
error.ResourceLimitReached => return error.SystemResources,
error.FileLocksUnsupported => unreachable, // 未请求锁
error.InvalidWtf8 => unreachable, // 仅限 Windows
error.InvalidBatchScriptArg => unreachable, // 仅限 Windows
error.InvalidUserId => unreachable, // 不支持
error.InvalidProcessGroupId => unreachable, // 传入 null
error.InvalidName => unreachable, // 仅限 Windows
error.ProcessAlreadyExec => unreachable, // 仅限 linux
};
return posixExec(options.exe, argv_buf.ptr, options.expand_arg0, env_block, PATH);
}
const processSpawn = switch (native_os) {
.wasi, .emscripten, .ios, .tvos, .visionos, .watchos => processSpawnUnsupported,
.windows => processSpawnWindows,
.driverkit, .maccatalyst, .macos => processSpawnDarwin,
else => processSpawnPosix,
};
fn processSpawnUnsupported(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child {
_ = userdata;
_ = options;
return error.OperationUnsupported;
}
const Spawned = struct {
pid: posix.pid_t,
err_fd: posix.fd_t,
stdin: ?File,
stdout: ?File,
stderr: ?File,
};
fn spawnPosix(t: *Threaded, options: process.SpawnOptions) process.SpawnError!Spawned {
// 子进程确实需要访问这些管道的一端,但最初必须设置 CLOEXEC,以避免竞态条件。若另一个线程正在并发创建其他子进程,绝不能让后者继承这些文件描述符。例如,其他子进程可能保留管道写端引用,导致父进程调用 `poll` 时,无法在预期时机检测到目标子进程的标准输出关闭。
// 因此,创建管道时先设置 CLOEXEC。fork 后,必须在新子进程中确保保留所需引用。可以使用 `fcntl` 移除描述符上的 CLOEXEC,但实际上所有描述符都会经过 `dup2`,因此无需额外操作。
//
//
//
//
//
//
//
//
const pipe_flags: posix.O = .{ .CLOEXEC = true };
const stdin_pipe = if (options.stdin == .pipe) try pipe2(pipe_flags) else undefined;
errdefer if (options.stdin == .pipe) {
destroyPipe(stdin_pipe);
};
const stdout_pipe = if (options.stdout == .pipe) try pipe2(pipe_flags) else undefined;
errdefer if (options.stdout == .pipe) {
destroyPipe(stdout_pipe);
};
const stderr_pipe = if (options.stderr == .pipe) try pipe2(pipe_flags) else undefined;
errdefer if (options.stderr == .pipe) {
destroyPipe(stderr_pipe);
};
const any_ignore = (options.stdin == .ignore or options.stdout == .ignore or options.stderr == .ignore);
const dev_null_fd = if (any_ignore) try getDevNullFd(t) else undefined;
const prog_pipe: [2]posix.fd_t = if (options.progress_node.index != .none) pipe: {
// 与 `pipe_flags` 中相同的原因,使用 CLOEXEC。
const pipe = try pipe2(.{ .NONBLOCK = true, .CLOEXEC = true });
switch (native_os) {
.linux => _ = posix.system.fcntl(pipe[0], posix.F.SETPIPE_SZ, @as(u32, std.Progress.max_packet_len * 2)),
else => {},
}
break :pipe pipe;
} else .{ -1, -1 };
errdefer destroyPipe(prog_pipe);
var arena_allocator = std.heap.ArenaAllocator.init(t.allocator);
defer arena_allocator.deinit();
const arena = arena_allocator.allocator();
// POSIX 标准不允许在 fork() 与 execve() 之间调用 malloc(),
// 而此分配器可能是 libc 分配器。
// 我曾在 musl v1.1.24 中亲眼观察到:
// 由于 fork() 与 execve() 之间发生堆分配,
// 子进程尝试调用 malloc() 时发生死锁。
// 此外,我们希望减少 fork() 与 execve() 之间
// 可能发生失败的方式。
// 因此,execve() 所需的所有分配都在 fork() 之前完成。
// 这意味着必须在此处为 argv 和环境变量添加空字符终止符。
const argv_buf = try arena.allocSentinel(?[*:0]const u8, options.argv.len, null);
for (options.argv, 0..) |arg, i| argv_buf[i] = (try arena.dupeSentinel(u8, arg, 0)).ptr;
const env_block = env_block: {
if (options.environ_map) |environ_map| break :env_block try environ_map.createPosixBlock(arena, .{
.zig_progress_fd = prog_pipe[1],
});
break :env_block try t.environ.process_environ.createPosixBlock(arena, .{
.zig_progress_fd = prog_pipe[1],
});
};
// 此管道在 `fork` 与 `execvpe` 之间向父进程传递子进程错误。
// 若 `execvpe` 成功,子进程会通过 CLOEXEC 关闭管道而不写入。
const err_pipe = try pipe2(.{ .CLOEXEC = true });
errdefer destroyPipe(err_pipe);
t.scanEnviron(); // 用于 PATH
const PATH = t.environ.string.PATH orelse default_PATH;
const pid_result: posix.pid_t = fork: {
const rc = posix.system.fork();
switch (posix.errno(rc)) {
.SUCCESS => break :fork @intCast(rc),
.AGAIN => return error.SystemResources,
.NOMEM => return error.SystemResources,
.NOSYS => return error.OperationUnsupported,
else => |err| return posix.unexpectedErrno(err),
}
};
if (pid_result == 0) {
defer comptime unreachable; // 当前为子进程。
if (Thread.current) |current_thread| current_thread.cancel_protection = .blocked;
const ep1 = err_pipe[1];
// 必须在下方覆盖文件描述符之前执行。
switch (options.cwd) {
.inherit => {},
.dir => |cwd| fchdir(cwd.handle) catch |err| forkBail(ep1, err),
.path => |cwd| chdir(cwd) catch |err| forkBail(ep1, err),
}
for (options.inherit_dirs) |inherit_dir| switch (posix.errno(
posix.system.fcntl(inherit_dir.handle, posix.F.SETFD, @as(u32, 0)),
)) {
.SUCCESS => {},
else => |err| forkBail(ep1, posix.unexpectedErrno(err)),
};
for (options.inherit_files) |file| switch (posix.errno(
posix.system.fcntl(file.handle, posix.F.SETFD, @as(u32, 0)),
)) {
.SUCCESS => {},
else => |err| forkBail(ep1, posix.unexpectedErrno(err)),
};
if (prog_pipe[1] != -1) switch (posix.errno(
posix.system.fcntl(prog_pipe[1], posix.F.SETFD, @as(u32, 0)),
)) {
.SUCCESS => {},
else => |err| forkBail(ep1, posix.unexpectedErrno(err)),
};
for (
[_]process.SpawnOptions.StdIo{ options.stdin, options.stdout, options.stderr },
[_]posix.fd_t{ stdin_pipe[0], stdout_pipe[1], stderr_pipe[1] },
[_]posix.fd_t{ posix.STDIN_FILENO, posix.STDOUT_FILENO, posix.STDERR_FILENO },
) |stdio, pipe_fd, std_fd| switch (stdio) {
.pipe => dup2(pipe_fd, std_fd) catch |err| forkBail(ep1, err),
.close => closeFd(std_fd),
.inherit => {},
.ignore => dup2(dev_null_fd, std_fd) catch |err| forkBail(ep1, err),
.file => |file| dup2(file.handle, std_fd) catch |err| forkBail(ep1, err),
};
if (options.gid) |gid| {
switch (posix.errno(posix.system.setregid(gid, gid))) {
.SUCCESS => {},
.AGAIN => forkBail(ep1, error.ResourceLimitReached),
.INVAL => forkBail(ep1, error.InvalidUserId),
.PERM => forkBail(ep1, error.PermissionDenied),
else => forkBail(ep1, error.Unexpected),
}
}
if (options.uid) |uid| {
switch (posix.errno(posix.system.setreuid(uid, uid))) {
.SUCCESS => {},
.AGAIN => forkBail(ep1, error.ResourceLimitReached),
.INVAL => forkBail(ep1, error.InvalidUserId),
.PERM => forkBail(ep1, error.PermissionDenied),
else => forkBail(ep1, error.Unexpected),
}
}
if (options.pgid) |pid| {
switch (posix.errno(posix.system.setpgid(0, pid))) {
.SUCCESS => {},
.ACCES => forkBail(ep1, error.ProcessAlreadyExec),
.INVAL => forkBail(ep1, error.InvalidProcessGroupId),
.PERM => forkBail(ep1, error.PermissionDenied),
else => forkBail(ep1, error.Unexpected),
}
}
if (options.start_suspended) {
switch (posix.errno(posix.system.kill(posix.system.getpid(), .STOP))) {
.SUCCESS => {},
.PERM => forkBail(ep1, error.PermissionDenied),
else => forkBail(ep1, error.Unexpected),
}
}
const err = posixExec(options.exe, argv_buf.ptr, options.expand_arg0, env_block, PATH);
forkBail(ep1, err);
}
const pid: posix.pid_t = @intCast(pid_result); // 当前为父进程。
errdefer comptime unreachable; // 子进程已 fork;此后绝不能返回错误
closeFd(err_pipe[1]); // 确保只有子进程保持写入端打开
if (options.stdin == .pipe) closeFd(stdin_pipe[0]);
if (options.stdout == .pipe) closeFd(stdout_pipe[1]);
if (options.stderr == .pipe) closeFd(stderr_pipe[1]);
if (prog_pipe[1] != -1) closeFd(prog_pipe[1]);
options.progress_node.setIpcFile(t, .{ .handle = prog_pipe[0], .flags = .{ .nonblocking = true } });
return .{
.pid = pid,
.err_fd = err_pipe[0],
.stdin = switch (options.stdin) {
.pipe => .{ .handle = stdin_pipe[1], .flags = .{ .nonblocking = false } },
else => null,
},
.stdout = switch (options.stdout) {
.pipe => .{ .handle = stdout_pipe[0], .flags = .{ .nonblocking = false } },
else => null,
},
.stderr = switch (options.stderr) {
.pipe => .{ .handle = stderr_pipe[0], .flags = .{ .nonblocking = false } },
else => null,
},
};
}
fn getDevNullFd(t: *Threaded) !posix.fd_t {
{
try mutexLock(&t.mutex);
defer mutexUnlock(&t.mutex);
if (t.null_file.fd != -1) return t.null_file.fd;
}
const mode: u32 = 0;
const syscall: Syscall = try .start();
while (true) {
const rc = open_sym("/dev/null", .{ .ACCMODE = .RDWR }, mode);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const fresh_fd: posix.fd_t = @intCast(rc);
mutexLockUncancelable(&t.mutex); // 另一个线程可能已在竞态中获胜。
defer mutexUnlock(&t.mutex);
if (t.null_file.fd != -1) {
closeFd(fresh_fd);
return t.null_file.fd;
} else {
t.null_file.fd = fresh_fd;
return fresh_fd;
}
},
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NFILE => return syscall.fail(error.SystemFdQuotaExceeded),
.NODEV => return syscall.fail(error.NoDevice),
.NOENT => return syscall.fail(error.FileNotFound),
.NOMEM => return syscall.fail(error.SystemResources),
.PERM => return syscall.fail(error.PermissionDenied),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
fn processSpawnPosix(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const spawned = try spawnPosix(t, options);
defer closeFd(spawned.err_fd);
// 等待子进程报告 `execvpe` 内部或之前发生的任何错误。
if (readIntFd(spawned.err_fd)) |child_err_int| {
const child_err: process.SpawnError = @errorCast(@errorFromInt(child_err_int));
return child_err;
} else |read_err| switch (read_err) {
error.EndOfStream => {
// 调用 `execvpe` 时,写入端由 CLOEXEC 关闭,
// 表示成功。
},
else => {
// 从错误报告管道读取错误时出现问题。
// 无法确定子进程仍存活还是已退出。最好假定它仍
// 存活,以免资源泄漏。
},
}
return .{
.id = spawned.pid,
.thread_handle = {},
.stdin = spawned.stdin,
.stdout = spawned.stdout,
.stderr = spawned.stderr,
.request_resource_usage_statistics = options.request_resource_usage_statistics,
};
}
fn childWait(userdata: ?*anyopaque, child: *process.Child) process.Child.WaitError!process.Child.Term {
if (native_os == .wasi) unreachable;
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
switch (native_os) {
.windows => return childWaitWindows(child),
else => return childWaitPosix(child),
}
}
fn childKill(userdata: ?*anyopaque, child: *process.Child) void {
if (native_os == .wasi) unreachable;
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (is_windows) {
childKillWindows(t, child, 1) catch childCleanupWindows(child);
} else {
childKillPosix(child) catch {};
childCleanupPosix(child);
}
}
fn childKillWindows(t: *Threaded, child: *process.Child, exit_code: windows.UINT) !void {
_ = t; // TODO 取消操作
const handle = child.id.?;
_ = windows.ntdll.RtlReportSilentProcessExit(handle, @fromBackingInt(@intCast(exit_code)));
switch (windows.ntdll.NtTerminateProcess(handle, @fromBackingInt(@intCast(exit_code)))) {
.SUCCESS, .PROCESS_IS_TERMINATING => {
_ = windows.ntdll.NtWaitForSingleObject(handle, .FALSE, null);
childCleanupWindows(child);
},
.ACCESS_DENIED => {
// TerminateProcess 触发 ACCESS_DENIED 错误时,通常表示进程已退出,但极少数边界情况下,进程句柄可能不再具有 PROCESS_TERMINATE 访问权。
// 因此,再执行一次检查,确保该进程确实已停止运行:
//
//
//
const minimal_timeout: windows.LARGE_INTEGER = -1;
return switch (windows.ntdll.NtWaitForSingleObject(handle, .FALSE, &minimal_timeout)) {
windows.NTSTATUS.WAIT_0 => error.AlreadyTerminated,
else => error.AccessDenied,
};
},
else => |status| return windows.unexpectedStatus(status),
}
}
fn childWaitWindows(child: *process.Child) process.Child.WaitError!process.Child.Term {
const handle = child.id.?;
const alertable_syscall: AlertableSyscall = try .start();
while (true) switch (windows.ntdll.NtWaitForSingleObject(handle, .TRUE, null)) {
windows.NTSTATUS.WAIT_0 => break alertable_syscall.finish(),
.USER_APC, .ALERTED, .TIMEOUT => {
try alertable_syscall.checkCancel();
continue;
},
else => |status| return alertable_syscall.unexpectedNtstatus(status),
};
var info: windows.PROCESS.BASIC_INFORMATION = undefined;
const term: process.Child.Term = switch (windows.ntdll.NtQueryInformationProcess(
handle,
.BasicInformation,
&info,
@sizeOf(windows.PROCESS.BASIC_INFORMATION),
null,
)) {
.SUCCESS => .{ .exited = @as(u8, @truncate(@backingInt(info.ExitStatus))) },
else => .{ .unknown = 0 },
};
childCleanupWindows(child);
return term;
}
fn childCleanupWindows(child: *process.Child) void {
const handle = child.id orelse return;
if (child.request_resource_usage_statistics) {
var vmc: windows.PROCESS.VM_COUNTERS = undefined;
switch (windows.ntdll.NtQueryInformationProcess(
handle,
.VmCounters,
&vmc,
@sizeOf(windows.PROCESS.VM_COUNTERS),
null,
)) {
.SUCCESS => child.resource_usage_statistics.rusage = vmc,
else => child.resource_usage_statistics.rusage = null,
}
}
windows.CloseHandle(handle);
child.id = null;
windows.CloseHandle(child.thread_handle);
child.thread_handle = undefined;
if (child.stdin) |stdin| {
windows.CloseHandle(stdin.handle);
child.stdin = null;
}
if (child.stdout) |stdout| {
windows.CloseHandle(stdout.handle);
child.stdout = null;
}
if (child.stderr) |stderr| {
windows.CloseHandle(stderr.handle);
child.stderr = null;
}
}
fn childWaitPosix(child: *process.Child) process.Child.WaitError!process.Child.Term {
defer childCleanupPosix(child);
const pid = child.id.?;
var ru: posix.rusage = undefined;
const ru_ptr = if (child.request_resource_usage_statistics) &ru else null;
if (have_wait4) {
var status: if (builtin.link_libc) c_int else i32 = undefined;
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.wait4(pid, &status, 0, ru_ptr))) {
.SUCCESS => {
syscall.finish();
if (ru_ptr) |p| child.resource_usage_statistics.rusage = p.*;
return statusToTerm(@bitCast(status));
},
.INTR => {
try syscall.checkCancel();
continue;
},
.CHILD => |err| return syscall.errnoBug(err), // 重复释放。
else => |err| return syscall.unexpectedErrno(err),
};
}
if (have_waitid) {
const linux = std.os.linux; // 绕过签名错误的 libc。
var info: linux.siginfo_t = undefined;
const syscall: Syscall = try .start();
while (true) switch (linux.errno(linux.waitid(.PID, pid, &info, linux.W.EXITED, ru_ptr))) {
.SUCCESS => {
syscall.finish();
if (ru_ptr) |p| child.resource_usage_statistics.rusage = p.*;
const status: u32 = @bitCast(info.fields.common.second.sigchld.status);
const code: linux.CLD = @fromBackingInt(@intCast(info.code));
return switch (code) {
.EXITED => .{ .exited = @truncate(status) },
.KILLED, .DUMPED => .{ .signal = @fromBackingInt(@intCast(status)) },
.TRAPPED, .STOPPED => .{ .stopped = @fromBackingInt(@intCast(status)) },
_, .CONTINUED => .{ .unknown = status },
};
},
.INTR => {
try syscall.checkCancel();
continue;
},
.CHILD => |err| return syscall.errnoBug(err), // 重复释放。
else => |err| return syscall.unexpectedErrno(err),
};
}
var status: if (builtin.link_libc) c_int else i32 = undefined;
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.waitpid(pid, &status, 0))) {
.SUCCESS => {
syscall.finish();
return statusToTerm(@bitCast(status));
},
.INTR => {
try syscall.checkCancel();
continue;
},
.CHILD => |err| return syscall.errnoBug(err), // 重复释放。
else => |err| return syscall.unexpectedErrno(err),
};
}
pub fn statusToTerm(status: u32) process.Child.Term {
return if (posix.W.IFEXITED(status))
.{ .exited = posix.W.EXITSTATUS(status) }
else if (posix.W.IFSIGNALED(status))
.{ .signal = posix.W.TERMSIG(status) }
else if (posix.W.IFSTOPPED(status))
.{ .stopped = posix.W.STOPSIG(status) }
else
.{ .unknown = status };
}
fn childKillPosix(child: *process.Child) !void {
// 有意使整个函数体不可取消。
const pid = child.id.?;
while (true) switch (posix.errno(posix.system.kill(pid, .TERM))) {
.SUCCESS => break,
.INTR => continue,
.PERM => return error.PermissionDenied,
.INVAL => |err| return errnoBug(err),
.SRCH => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
};
if (have_wait4) {
var status: if (builtin.link_libc) c_int else i32 = undefined;
while (true) switch (posix.errno(posix.system.wait4(pid, &status, 0, null))) {
.SUCCESS => return,
.INTR => continue,
.CHILD => |err| return errnoBug(err), // 重复释放。
else => |err| return posix.unexpectedErrno(err),
};
}
if (have_waitid) {
const linux = std.os.linux; // 绕过签名错误的 libc。
var info: linux.siginfo_t = undefined;
while (true) switch (linux.errno(linux.waitid(.PID, pid, &info, linux.W.EXITED, null))) {
.SUCCESS => return,
.INTR => continue,
.CHILD => |err| return errnoBug(err), // 重复释放。
else => |err| return posix.unexpectedErrno(err),
};
}
var status: if (builtin.link_libc) c_int else i32 = undefined;
while (true) switch (posix.errno(posix.system.waitpid(pid, &status, 0))) {
.SUCCESS => return,
.INTR => continue,
.CHILD => |err| return errnoBug(err), // 重复释放。
else => |err| return posix.unexpectedErrno(err),
};
}
fn childCleanupPosix(child: *process.Child) void {
if (child.stdin) |stdin| {
closeFd(stdin.handle);
child.stdin = null;
}
if (child.stdout) |stdout| {
closeFd(stdout.handle);
child.stdout = null;
}
if (child.stderr) |stderr| {
closeFd(stderr.handle);
child.stderr = null;
}
child.id = null;
}
/// fork() 与 execv() 之间可能发生的错误。
const ForkBailError = process.SpawnError || process.ReplaceError;
/// fork 子进程调用此函数,向 fork 父进程报告错误。
/// 然后子进程退出。
fn forkBail(fd: posix.fd_t, err: ForkBailError) noreturn {
writeIntFd(fd, @as(ErrInt, @intFromError(err))) catch {};
// 如果链接 libc,一些不守规矩的应用程序可能已注册 atexit 处理器,
// 而我们完全不希望它们在 fork 出的子进程中运行。我发现 LLVM 就会如此,
// 导致死锁,而非执行退出系统调用。用 Avril Lavigne 的歌词说,
// “为什么非要把事情弄得这么复杂?”
if (builtin.link_libc) {
// `_exit` 函数仅发起 exit 系统调用,其他什么也不做,这与 `exit` 不同。
std.c._exit(1);
} else if (native_os == .linux and !builtin.single_threaded) {
std.os.linux.exit_group(1);
} else {
posix.system.exit(1);
}
}
fn writeIntFd(fd: posix.fd_t, value: ErrInt) !void {
var buffer: [8]u8 = undefined;
std.mem.writeInt(u64, &buffer, value, .little);
// 跳过取消机制。
var i: usize = 0;
while (true) {
const rc = posix.system.write(fd, buffer[i..].ptr, buffer.len - i);
switch (posix.errno(rc)) {
.SUCCESS => {
const n: usize = @intCast(rc);
i += n;
if (buffer.len - i == 0) return;
},
.INTR => continue,
else => return error.SystemResources,
}
}
}
fn readIntFd(fd: posix.fd_t) !ErrInt {
var buffer: [8]u8 = undefined;
var i: usize = 0;
while (true) {
const rc = posix.system.read(fd, buffer[i..].ptr, buffer.len - i);
switch (posix.errno(rc)) {
.SUCCESS => {
const n: usize = @intCast(rc);
if (n == 0) break;
i += n;
continue;
},
.INTR => continue,
else => |err| return posix.unexpectedErrno(err),
}
}
if (buffer.len - i != 0) return error.EndOfStream;
return @intCast(std.mem.readInt(u64, &buffer, .little));
}
const ErrInt = @Int(.unsigned, @sizeOf(anyerror) * 8);
fn destroyPipe(pipe: [2]posix.fd_t) void {
if (pipe[0] != -1) closeFd(pipe[0]);
if (pipe[0] != pipe[1]) closeFd(pipe[1]);
}
fn processSpawnDarwin(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child {
const t: *Threaded = @ptrCast(@alignCast(userdata));
t.scanEnviron(); // 用于 PATH
const PATH = t.environ.string.PATH orelse default_PATH;
var arena_allocator = std.heap.ArenaAllocator.init(t.allocator);
defer arena_allocator.deinit();
const arena = arena_allocator.allocator();
const argv_buf = try arena.allocSentinel(?[*:0]const u8, options.argv.len, null);
for (options.argv, 0..) |arg, i| argv_buf[i] = (try arena.dupeSentinel(u8, arg, 0)).ptr;
const env_block = env_block: {
const prog_fd: i32 = -1;
if (options.environ_map) |environ_map| break :env_block try environ_map.createPosixBlock(arena, .{
.zig_progress_fd = prog_fd,
});
break :env_block try t.environ.process_environ.createPosixBlock(arena, .{
.zig_progress_fd = prog_fd,
});
};
const spawned = try t.spawnDarwin(
.spawn,
options.exe,
argv_buf.ptr,
options.cwd,
env_block,
options.expand_arg0,
options.progress_node,
options.stdin,
options.stdout,
options.stderr,
options.inherit_dirs,
options.inherit_files,
options.pgid,
options.start_suspended,
PATH,
);
return .{
.id = spawned.pid,
.thread_handle = {},
.stdin = spawned.stdin,
.stdout = spawned.stdout,
.stderr = spawned.stderr,
.request_resource_usage_statistics = options.request_resource_usage_statistics,
};
}
fn processSpawnWindows(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child {
const t: *Threaded = @ptrCast(@alignCast(userdata));
var arena_allocator = std.heap.ArenaAllocator.init(t.allocator);
defer arena_allocator.deinit();
const arena = arena_allocator.allocator();
const cwd_w = cwd_w: {
switch (options.cwd) {
.inherit => break :cwd_w null,
.dir => |cwd_dir| {
var dir_path_buffer = try arena.alloc(u16, windows.PATH_MAX_WIDE + 1);
const dir_path = try GetFinalPathNameByHandle(
cwd_dir.handle,
.{},
dir_path_buffer[0..windows.PATH_MAX_WIDE],
);
dir_path_buffer[dir_path.len] = 0;
// 将分配收缩到仅容纳路径缓冲区和哨兵值
dir_path_buffer = try arena.realloc(dir_path_buffer, dir_path.len + 1);
break :cwd_w dir_path_buffer[0..dir_path.len :0];
},
.path => |cwd| {
break :cwd_w try std.unicode.wtf8ToWtf16LeAllocZ(arena, cwd);
},
}
};
const cwd_w_ptr = if (cwd_w) |cwd| cwd.ptr else null;
// 如果应用程序名不仅是文件名,则需要将其拆成
// 基本名称和目录名,并将目录名追加到
// 当前工作目录路径。原因是 NtQueryDirectoryFile 不接受
// 包含路径分隔符的 FileName 参数。
var app_w_buf: [windows.PATH_MAX_WIDE]u16 = undefined;
// 若应用名称为绝对路径,则 cwd 已包含应用目录名,
// 因此仅当应用名称是至少包含一个路径分隔符的相对路径时,才填充 app_dir。
const app_path_w, const app_dir_w, const app_name_w = app: {
const path = switch (options.exe) {
.detect, .search, .path => options.argv[0],
.file => |file| {
const path_w = try GetFinalPathNameByHandle(file.handle, .{}, &app_w_buf);
var path_it: Dir.path.ComponentIterator(.windows, u16) = .init(path_w);
const base = path_it.last().?;
break :app .{
null,
if (path_it.previous()) |dir| dir.path else path_it.root(),
base.name,
};
},
.explicit => |explicit| explicit.path,
};
break :app .{
if (Dir.path.isAbsolute(path)) null else switch (options.exe) {
// 为符合 POSIX 语义,选择可执行文件路径时,
// options 提供的 cwd 已生效。
.detect, .search => cwd_w,
.path => |dir| try GetFinalPathNameByHandle(dir.handle, .{}, &app_w_buf),
.file => unreachable,
.explicit => |explicit| try GetFinalPathNameByHandle(
explicit.dir.handle,
.{},
&app_w_buf,
),
},
if (Dir.path.dirname(path)) |app_dir|
try std.unicode.wtf8ToWtf16LeAllocZ(arena, app_dir)
else
null,
try std.unicode.wtf8ToWtf16LeAllocZ(arena, Dir.path.basename(path)),
};
};
const flags: windows.CreateProcessFlags = .{
.create_suspended = options.start_suspended,
.create_unicode_environment = true,
.create_no_window = options.create_no_window,
};
try mutexLock(&t.process_spawn_mutex);
defer mutexUnlock(&t.process_spawn_mutex);
const any_ignore =
options.stdin == .ignore or
options.stdout == .ignore or
options.stderr == .ignore;
const nul_handle = if (any_ignore) try getNulDevice(t) else undefined;
const any_inherit =
options.stdin == .inherit or
options.stdout == .inherit or
options.stderr == .inherit;
const peb = if (any_inherit) windows.peb() else undefined;
const stdin_pipe = if (options.stdin == .pipe) try t.windowsCreatePipe(.{
.server = .{ .attributes = .{ .INHERIT = false }, .mode = .{ .IO = .SYNCHRONOUS_NONALERT } },
.client = .{ .attributes = .{ .INHERIT = true }, .mode = .{ .IO = .SYNCHRONOUS_NONALERT } },
.outbound = true,
}) else undefined;
errdefer if (options.stdin == .pipe) for (stdin_pipe) |handle| windows.CloseHandle(handle);
const stdout_pipe = if (options.stdout == .pipe) try t.windowsCreatePipe(.{
.server = .{ .attributes = .{ .INHERIT = false }, .mode = .{ .IO = .ASYNCHRONOUS } },
.client = .{ .attributes = .{ .INHERIT = true }, .mode = .{ .IO = .SYNCHRONOUS_NONALERT } },
.inbound = true,
}) else undefined;
errdefer if (options.stdout == .pipe) for (stdout_pipe) |handle| windows.CloseHandle(handle);
const stderr_pipe = if (options.stderr == .pipe) try t.windowsCreatePipe(.{
.server = .{ .attributes = .{ .INHERIT = false }, .mode = .{ .IO = .ASYNCHRONOUS } },
.client = .{ .attributes = .{ .INHERIT = true }, .mode = .{ .IO = .SYNCHRONOUS_NONALERT } },
.inbound = true,
}) else undefined;
errdefer if (options.stderr == .pipe) for (stderr_pipe) |handle| windows.CloseHandle(handle);
const prog_pipe = if (options.progress_node.index != .none) try t.windowsCreatePipe(.{
.server = .{ .attributes = .{ .INHERIT = false }, .mode = .{ .IO = .ASYNCHRONOUS } },
.client = .{ .attributes = .{ .INHERIT = true }, .mode = .{ .IO = .ASYNCHRONOUS } },
.inbound = true,
.quota = std.Progress.max_packet_len * 2,
}) else undefined;
errdefer if (options.progress_node.index != .none) for (prog_pipe) |handle| windows.CloseHandle(handle);
defer for (options.inherit_dirs) |inherit_dir| switch (windows.ntdll.NtSetInformationObject(
inherit_dir.handle,
.HandleFlag,
&windows.OBJECT.HANDLE_FLAG{ .INHERIT = false },
@sizeOf(windows.OBJECT.HANDLE_FLAG),
)) {
.SUCCESS => {},
else => |status| windows.unexpectedStatus(status) catch {},
};
for (options.inherit_dirs) |inherit_dir| switch (windows.ntdll.NtSetInformationObject(
inherit_dir.handle,
.HandleFlag,
&windows.OBJECT.HANDLE_FLAG{ .INHERIT = true },
@sizeOf(windows.OBJECT.HANDLE_FLAG),
)) {
.SUCCESS => {},
else => |status| return windows.unexpectedStatus(status),
};
defer for (options.inherit_files) |inherit_file| switch (windows.ntdll.NtSetInformationObject(
inherit_file.handle,
.HandleFlag,
&windows.OBJECT.HANDLE_FLAG{ .INHERIT = false },
@sizeOf(windows.OBJECT.HANDLE_FLAG),
)) {
.SUCCESS => {},
else => |status| windows.unexpectedStatus(status) catch {},
};
for (options.inherit_files) |inherit_file| switch (windows.ntdll.NtSetInformationObject(
inherit_file.handle,
.HandleFlag,
&windows.OBJECT.HANDLE_FLAG{ .INHERIT = true },
@sizeOf(windows.OBJECT.HANDLE_FLAG),
)) {
.SUCCESS => {},
else => |status| return windows.unexpectedStatus(status),
};
var siStartInfo: windows.STARTUPINFOW = .{
.cb = @sizeOf(windows.STARTUPINFOW),
.dwFlags = windows.STARTF_USESTDHANDLES,
.hStdInput = switch (options.stdin) {
.inherit => peb.ProcessParameters.hStdInput,
.file => |file| try OpenFile(&.{}, .{
.access_mask = .{
.STANDARD = .{ .SYNCHRONIZE = true },
.GENERIC = .{ .READ = true },
},
.dir = file.handle,
.sa = &.{
.nLength = @sizeOf(windows.SECURITY_ATTRIBUTES),
.lpSecurityDescriptor = null,
.bInheritHandle = .TRUE,
},
.creation = .OPEN,
}),
.ignore => nul_handle,
.pipe => stdin_pipe[1],
.close => null,
},
.hStdOutput = switch (options.stdout) {
.inherit => peb.ProcessParameters.hStdOutput,
.file => |file| try OpenFile(&.{}, .{
.access_mask = .{
.STANDARD = .{ .SYNCHRONIZE = true },
.GENERIC = .{ .WRITE = true },
},
.dir = file.handle,
.sa = &.{
.nLength = @sizeOf(windows.SECURITY_ATTRIBUTES),
.lpSecurityDescriptor = null,
.bInheritHandle = .TRUE,
},
.creation = .OPEN,
}),
.ignore => nul_handle,
.pipe => stdout_pipe[1],
.close => null,
},
.hStdError = switch (options.stderr) {
.inherit => peb.ProcessParameters.hStdError,
.file => |file| try OpenFile(&.{}, .{
.access_mask = .{
.STANDARD = .{ .SYNCHRONIZE = true },
.GENERIC = .{ .WRITE = true },
},
.dir = file.handle,
.sa = &.{
.nLength = @sizeOf(windows.SECURITY_ATTRIBUTES),
.lpSecurityDescriptor = null,
.bInheritHandle = .TRUE,
},
.creation = .OPEN,
}),
.ignore => nul_handle,
.pipe => stderr_pipe[1],
.close => null,
},
.lpReserved = null,
.lpDesktop = null,
.lpTitle = null,
.dwX = 0,
.dwY = 0,
.dwXSize = 0,
.dwYSize = 0,
.dwXCountChars = 0,
.dwYCountChars = 0,
.dwFillAttribute = 0,
.wShowWindow = 0,
.cbReserved2 = 0,
.lpReserved2 = null,
};
var piProcInfo: windows.PROCESS.INFORMATION = undefined;
const env_block = env_block: {
const prog_handle = if (options.progress_node.index != .none)
prog_pipe[1]
else
windows.INVALID_HANDLE_VALUE;
if (options.environ_map) |environ_map| break :env_block try environ_map.createWindowsBlock(arena, .{
.zig_progress_handle = prog_handle,
});
break :env_block try t.environ.process_environ.createWindowsBlock(arena, .{
.zig_progress_handle = if (options.progress_node.index != .none) prog_pipe[1] else windows.INVALID_HANDLE_VALUE,
});
};
run: {
// 由于 PEB 环境指针不稳定,必须每次扫描。
const env_strings: WindowsEnvironStrings = .scan();
const PATH = env_strings.PATH orelse &[_:0]u16{};
const PATHEXT = env_strings.PATHEXT orelse &[_:0]u16{};
// 若最终命令是 .bat 或 .cmd 脚本,必须按 cmd.exe 规则转义,并自行调用 cmd.exe,以缓解恶意构造参数导致的任意命令执行风险。
//
// 只有实际尝试运行命令时,才能确定解析后的命令是否带 `.bat` 或 `.cmd` 扩展名,因此将命令行的实际序列化推迟到明确应采用何种序列化方式之后。
//
//
//
//
var cmd_line_cache = WindowsCommandLineCache.init(arena, options.argv);
var app_buf: std.ArrayList(u16) = .empty;
try app_buf.appendSlice(arena, app_name_w);
var dir_buf: std.ArrayList(u16) = .empty;
if (app_path_w) |app_path| try dir_buf.appendSlice(arena, app_path);
if (app_dir_w) |app_dir| {
if (dir_buf.items.len > 0) try dir_buf.append(arena, Dir.path.sep);
try dir_buf.appendSlice(arena, app_dir);
}
windowsCreateProcessPathExt(
arena,
&dir_buf,
&app_buf,
PATHEXT,
&cmd_line_cache,
env_block,
cwd_w_ptr,
flags,
&siStartInfo,
&piProcInfo,
) catch |no_path_err| {
const original_err = switch (no_path_err) {
// argv[0] 包含不支持的字符,永远无法解析为有效 exe。
error.InvalidArg0 => return error.FileNotFound,
error.FileNotFound, error.InvalidExe, error.AccessDenied => |e| e,
error.UnrecoverableInvalidExe => return error.InvalidExe,
else => |e| return e,
};
// 即使 cwd 为绝对路径,仍需搜索 PATH,因为
// “选择可执行文件路径时,选项提供的 cwd 已生效,
// 以匹配 POSIX 语义”。不能仅因尝试设置子进程的
// 当前工作目录,就跳过 PATH 搜索。
if (switch (options.exe) {
// 如果应用程序名称含路径分隔符,则禁止进行 PATH 搜索。
.detect => app_dir_w != null,
// 应用程序名称为绝对路径时,无需搜索 PATH。
.search => app_path_w == null,
// 禁止搜索 PATH。
.path, .file, .explicit => true,
}) return original_err;
var it = std.mem.tokenizeScalar(u16, PATH, ';');
while (it.next()) |search_path| {
dir_buf.clearRetainingCapacity();
try dir_buf.appendSlice(arena, search_path);
if (windowsCreateProcessPathExt(
arena,
&dir_buf,
&app_buf,
PATHEXT,
&cmd_line_cache,
env_block,
cwd_w_ptr,
flags,
&siStartInfo,
&piProcInfo,
)) {
break :run;
} else |err| switch (err) {
// argv[0] 包含不支持的字符,永远无法解析为有效 exe。
error.InvalidArg0 => return error.FileNotFound,
error.FileNotFound, error.AccessDenied, error.InvalidExe => continue,
error.UnrecoverableInvalidExe => return error.InvalidExe,
else => |e| return e,
}
} else {
return original_err;
}
};
}
if (options.progress_node.index != .none) {
windows.CloseHandle(prog_pipe[1]);
options.progress_node.setIpcFile(t, .{ .handle = prog_pipe[0], .flags = .{ .nonblocking = true } });
}
return .{
.id = piProcInfo.hProcess,
.thread_handle = piProcInfo.hThread,
.stdin = stdin: switch (options.stdin) {
.file => {
windows.CloseHandle(siStartInfo.hStdInput.?);
break :stdin null;
},
.pipe => {
windows.CloseHandle(stdin_pipe[1]);
break :stdin .{ .handle = stdin_pipe[0], .flags = .{ .nonblocking = false } };
},
else => null,
},
.stdout = stdout: switch (options.stdout) {
.file => {
windows.CloseHandle(siStartInfo.hStdOutput.?);
break :stdout null;
},
.pipe => {
windows.CloseHandle(stdout_pipe[1]);
break :stdout .{ .handle = stdout_pipe[0], .flags = .{ .nonblocking = true } };
},
else => null,
},
.stderr = stderr: switch (options.stderr) {
.file => {
windows.CloseHandle(siStartInfo.hStdError.?);
break :stderr null;
},
.pipe => {
windows.CloseHandle(stderr_pipe[1]);
break :stderr .{ .handle = stderr_pipe[0], .flags = .{ .nonblocking = true } };
},
else => null,
},
.request_resource_usage_statistics = options.request_resource_usage_statistics,
};
}
fn getCngDevice(t: *Threaded) Io.RandomSecureError!windows.HANDLE {
{
try mutexLock(&t.mutex);
defer mutexUnlock(&t.mutex);
if (t.random_file.handle) |handle| return handle;
}
var fresh_handle: windows.HANDLE = undefined;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtOpenFile(
&fresh_handle,
.{
.STANDARD = .{ .SYNCHRONIZE = true },
.SPECIFIC = .{ .FILE = .{ .READ_DATA = true } },
},
&.{ .ObjectName = @constCast(&windows.UNICODE_STRING.init(
&.{ '\\', 'D', 'e', 'v', 'i', 'c', 'e', '\\', 'C', 'N', 'G' },
)) },
&io_status_block,
.VALID_FLAGS,
.{ .IO = .SYNCHRONOUS_NONALERT },
)) {
.SUCCESS => {
syscall.finish();
mutexLockUncancelable(&t.mutex); // 另一个线程可能已在竞态中获胜。
defer mutexUnlock(&t.mutex);
if (t.random_file.handle) |prev_handle| {
windows.CloseHandle(fresh_handle);
return prev_handle;
} else {
t.random_file.handle = fresh_handle;
return fresh_handle;
}
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.EntropyUnavailable), // 在 wine 10.0 中观察到
else => return syscall.fail(error.EntropyUnavailable),
};
}
fn getNulDevice(t: *Threaded) !windows.HANDLE {
{
try mutexLock(&t.mutex);
defer mutexUnlock(&t.mutex);
if (t.null_file.handle) |handle| return handle;
}
var fresh_handle: windows.HANDLE = undefined;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtOpenFile(
&fresh_handle,
.{
.STANDARD = .{ .SYNCHRONIZE = true },
.SPECIFIC = .{ .FILE = .{ .READ_DATA = true, .WRITE_DATA = true } },
},
&.{
.Attributes = .{ .INHERIT = true },
.ObjectName = @constCast(&windows.UNICODE_STRING.init(
&.{ '\\', 'D', 'e', 'v', 'i', 'c', 'e', '\\', 'N', 'u', 'l', 'l' },
)),
},
&io_status_block,
.VALID_FLAGS,
.{ .IO = .SYNCHRONOUS_NONALERT },
)) {
.SUCCESS => {
syscall.finish();
mutexLockUncancelable(&t.mutex); // 另一个线程可能已在竞态中获胜。
defer mutexUnlock(&t.mutex);
if (t.null_file.handle) |prev_handle| {
windows.CloseHandle(fresh_handle);
return prev_handle;
} else {
t.null_file.handle = fresh_handle;
return fresh_handle;
}
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.OBJECT_PATH_SYNTAX_BAD => |status| return syscall.ntstatusBug(status),
.INVALID_HANDLE => |status| return syscall.ntstatusBug(status),
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.SHARING_VIOLATION => return syscall.fail(error.AccessDenied),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.NoDevice),
.FILE_IS_A_DIRECTORY => return syscall.fail(error.IsDir),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
fn getNamedPipeDevice(t: *Threaded) !windows.HANDLE {
{
try mutexLock(&t.mutex);
defer mutexUnlock(&t.mutex);
if (t.pipe_file.handle) |handle| return handle;
}
var fresh_handle: windows.HANDLE = undefined;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtOpenFile(
&fresh_handle,
.{ .STANDARD = .{ .SYNCHRONIZE = true } },
&.{
.ObjectName = @constCast(&windows.UNICODE_STRING.init(
&.{ '\\', 'D', 'e', 'v', 'i', 'c', 'e', '\\', 'N', 'a', 'm', 'e', 'd', 'P', 'i', 'p', 'e', '\\' },
)),
},
&io_status_block,
.VALID_FLAGS,
.{ .IO = .SYNCHRONOUS_NONALERT },
)) {
.SUCCESS => {
syscall.finish();
mutexLockUncancelable(&t.mutex); // 另一个线程可能已在竞态中获胜。
defer mutexUnlock(&t.mutex);
if (t.pipe_file.handle) |prev_handle| {
windows.CloseHandle(fresh_handle);
return prev_handle;
} else {
t.pipe_file.handle = fresh_handle;
return fresh_handle;
}
},
.DELETE_PENDING => {
// 此错误表示文件系统的该位置原先存在文件,但已被删除。然而,操作系统尚未完成删除操作,因此本次 CreateFile 调用失败。
// 除了等待操作系统完成删除后重试创建之外,没有合理的处理方式。
//
//
//
//
syscall.finish();
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds(1),
.clock = .awake,
} });
syscall = try .start();
continue;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.OBJECT_PATH_SYNTAX_BAD => |status| return syscall.ntstatusBug(status),
.INVALID_HANDLE => |status| return syscall.ntstatusBug(status),
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.SHARING_VIOLATION => return syscall.fail(error.AccessDenied),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.NoDevice),
.FILE_IS_A_DIRECTORY => return syscall.fail(error.IsDir),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
else => |status| return syscall.unexpectedNtstatus(status),
};
}
/// 要求 `app_buf` 恰好包含应用程序名称,`dir_buf` 恰好包含目录路径。
/// 返回后,`app_buf` 始终恰好包含应用程序名称,`dir_buf` 始终恰好包含目录路径。
/// 注意:`app_buf` 不应带前导路径分隔符。
/// 注意:若目录为当前工作目录,dir_buf 应为空,即 len = 0。
fn windowsCreateProcessPathExt(
arena: Allocator,
dir_buf: *std.ArrayList(u16),
app_buf: *std.ArrayList(u16),
pathext: [:0]const u16,
cmd_line_cache: *WindowsCommandLineCache,
env_block: ?process.Environ.WindowsBlock,
cwd_ptr: ?[*:0]u16,
flags: windows.CreateProcessFlags,
lpStartupInfo: *windows.STARTUPINFOW,
lpProcessInformation: *windows.PROCESS.INFORMATION,
) !void {
const app_name_len = app_buf.items.len;
const dir_path_len = dir_buf.items.len;
if (app_name_len == 0) return error.FileNotFound;
defer app_buf.shrinkRetainingCapacity(app_name_len);
defer dir_buf.shrinkRetainingCapacity(dir_path_len);
// 此处的核心目标是尽可能避免调用 CreateProcessW,
// 仅在确有可执行候选项时才尝试调用。
// 其次,检查应用名追加各 PATHEXT 扩展名后的版本时,
// 尽量减少系统调用次数。
//
// 所用技术概述如下:
// - 打开搜索目录以便迭代,目录为 cwd 或 PATH 中的某一路径。
// - 使用文件名通配符 `<app name>*` 调用 NtQueryDirectoryFile,
// 检查是否存在任何可能匹配原始应用名
// 或追加某个 PATHEXT 值后的应用名的条目。
// - 若通配符 NtQueryDirectoryFile 调用未找到任何条目,可以提前退出,
// 完全不必处理 PATHEXT。
//
// 这样,对于不含任何可能匹配项的目录,可以只执行
// 一次“打开目录、NtQueryDirectoryFile、关闭目录”序列,
// 而不必分别查找每个文件名组合(原始名称与
// 追加每个 PATHEXT 值后的名称)。对于通配符*确实*匹配到内容的目录,
// 遍历匹配项,并记录原始名称
// 或追加受支持 PATHEXT 扩展名的名称。随后
// 按适当顺序,对找到的版本尝试调用 CreateProcessW。
const dir = dir: {
// 需要以空字符结尾
try dir_buf.append(arena, 0);
defer dir_buf.shrinkRetainingCapacity(dir_path_len);
const dir_path_z = dir_buf.items[0 .. dir_buf.items.len - 1 :0];
const prefixed_path = try wToPrefixedFileW(null, dir_path_z, .{});
break :dir dirOpenDirWindows(.cwd(), prefixed_path.span(), .{
.iterate = true,
}) catch |err| switch (err) {
// 不得忽略这些错误,因为它们不应影响
// 要执行的文件选择。此外,绝不能吞掉 `error.Canceled`。
//
error.Canceled,
error.SystemResources,
error.Unexpected,
error.ProcessFdQuotaExceeded,
error.SystemFdQuotaExceeded,
=> |e| return e,
error.AccessDenied,
error.PermissionDenied,
error.SymLinkLoop,
error.FileNotFound,
error.NotDir,
error.NoDevice,
error.NetworkNotFound,
error.NameTooLong,
error.BadPathName,
=> return error.FileNotFound,
};
};
defer windows.CloseHandle(dir.handle);
// 添加通配符和空终止符
try app_buf.append(arena, '*');
try app_buf.append(arena, 0);
const app_name_wildcard = app_buf.items[0 .. app_buf.items.len - 1 :0];
// 2048 是任意选择的,只需足够大,使每次 NtQueryDirectoryFile 调用
// 能够返回多个 FILE_DIRECTORY_INFORMATION 条目。
var file_information_buf: [2048]u8 align(@alignOf(windows.FILE_DIRECTORY_INFORMATION)) = undefined;
const file_info_maximum_single_entry_size = @sizeOf(windows.FILE_DIRECTORY_INFORMATION) + (windows.NAME_MAX * 2);
if (file_information_buf.len < file_info_maximum_single_entry_size) {
@compileError("file_information_buf must be large enough to contain at least one maximum size FILE_DIRECTORY_INFORMATION entry");
}
var io_status: windows.IO_STATUS_BLOCK = undefined;
const num_supported_pathext = @typeInfo(process.WindowsExtension).@"enum".field_names.len;
var pathext_seen: [num_supported_pathext]bool = @splat(false);
var any_pathext_seen = false;
var unappended_exists = false;
// 通过 NtQueryDirectoryFile 完整遍历通配符匹配项,记录所有
// 应尝试启动的 app_name 版本。
// 注意:这是必需的,因为文件返回顺序取决于文件系统:
// NTFS 上,如果 `blah.exe` 存在,`blah.exe*` 总会首先返回它。
// FAT32 上,可能先返回 `blah.exe.obj` 之类的文件。
while (true) {
// 若使用通配符未找到任何内容,则可直接退出,因为追加 PATHEXT 也不会产生结果。
//
switch (windows.ntdll.NtQueryDirectoryFile(
dir.handle,
null,
null,
null,
&io_status,
&file_information_buf,
file_information_buf.len,
.Directory,
.FALSE, // 单个结果
&.init(app_name_wildcard),
.FALSE, // 重新开始迭代
)) {
.SUCCESS => {},
.NO_SUCH_FILE => return error.FileNotFound,
.NO_MORE_FILES => break,
.ACCESS_DENIED => return error.AccessDenied,
else => |status| return windows.unexpectedStatus(status),
}
// 根据文档,仅当缓冲区剩余空间不足以
// 写入至少一个完整的 FILE_DIRECTORY_INFORMATION 条目时才会发生。
// 因此,使用当前缓冲区大小时,不应遇到此情况。
std.debug.assert(io_status.Information != 0);
var it = windows.FileInformationIterator(windows.FILE_DIRECTORY_INFORMATION){ .buf = &file_information_buf };
while (it.next()) |info| {
// 跳过目录
if (info.FileAttributes.DIRECTORY) continue;
const filename = @as([*]u16, @ptrCast(&info.FileName))[0 .. info.FileNameLength / 2];
// 由于使用通配符 `app_name*`,所有结果均以 app_name 开头,
// 所以长度等于 app_name 时即为精确匹配
if (filename.len == app_name_len) {
// 注意:此处不能提前退出,因为未追加后缀的版本可能无法启动;
// 此时仍需尝试追加 PATHEXT 后缀的版本。
unappended_exists = true;
} else if (windowsCreateProcessSupportsExtension(filename[app_name_len..])) |pathext_ext| {
pathext_seen[@backingInt(pathext_ext)] = true;
any_pathext_seen = true;
}
}
}
const unappended_err = unappended: {
if (unappended_exists) {
if (dir_path_len != 0) switch (dir_buf.items[dir_buf.items.len - 1]) {
'/', '\\' => {},
else => try dir_buf.append(arena, Dir.path.sep),
};
try dir_buf.appendSlice(arena, app_buf.items[0..app_name_len]);
try dir_buf.append(arena, 0);
const full_app_name = dir_buf.items[0 .. dir_buf.items.len - 1 :0];
const is_bat_or_cmd = bat_or_cmd: {
const app_name = app_buf.items[0..app_name_len];
const ext_start = std.mem.findScalarLast(u16, app_name, '.') orelse break :bat_or_cmd false;
const ext = app_name[ext_start..];
const ext_enum = windowsCreateProcessSupportsExtension(ext) orelse break :bat_or_cmd false;
switch (ext_enum) {
.cmd, .bat => break :bat_or_cmd true,
else => break :bat_or_cmd false,
}
};
const cmd_line_w = if (is_bat_or_cmd)
try cmd_line_cache.scriptCommandLine(full_app_name)
else
try cmd_line_cache.commandLine();
const app_name_w = if (is_bat_or_cmd)
try cmd_line_cache.cmdExePath()
else
full_app_name;
if (windowsCreateProcess(
app_name_w.ptr,
cmd_line_w.ptr,
env_block,
cwd_ptr,
flags,
lpStartupInfo,
lpProcessInformation,
)) |_| {
return;
} else |err| switch (err) {
error.FileNotFound,
error.AccessDenied,
=> break :unappended err,
error.InvalidExe => {
// 遇到 InvalidExe 时,若应用名称扩展名为 .exe,
// 则视为不可恢复错误。否则,
// 按常规跳过。
const app_name = app_buf.items[0..app_name_len];
const ext_start = std.mem.findScalarLast(u16, app_name, '.') orelse break :unappended err;
const ext = app_name[ext_start..];
if (windows.eqlIgnoreCaseWtf16(ext, std.unicode.utf8ToUtf16LeStringLiteral(".EXE"))) {
return error.UnrecoverableInvalidExe;
}
break :unappended err;
},
else => return err,
}
}
break :unappended error.FileNotFound;
};
if (!any_pathext_seen) return unappended_err;
// 现在尝试已发现的各 PATHEXT 后缀版本
var ext_it = std.mem.tokenizeScalar(u16, pathext, ';');
while (ext_it.next()) |ext| {
const ext_enum = windowsCreateProcessSupportsExtension(ext) orelse continue;
if (!pathext_seen[@backingInt(ext_enum)]) continue;
dir_buf.shrinkRetainingCapacity(dir_path_len);
if (dir_path_len != 0) switch (dir_buf.items[dir_buf.items.len - 1]) {
'/', '\\' => {},
else => try dir_buf.append(arena, Dir.path.sep),
};
try dir_buf.appendSlice(arena, app_buf.items[0..app_name_len]);
try dir_buf.appendSlice(arena, ext);
try dir_buf.append(arena, 0);
const full_app_name = dir_buf.items[0 .. dir_buf.items.len - 1 :0];
const is_bat_or_cmd = switch (ext_enum) {
.cmd, .bat => true,
else => false,
};
const cmd_line_w = if (is_bat_or_cmd)
try cmd_line_cache.scriptCommandLine(full_app_name)
else
try cmd_line_cache.commandLine();
const app_name_w = if (is_bat_or_cmd)
try cmd_line_cache.cmdExePath()
else
full_app_name;
if (windowsCreateProcess(
app_name_w.ptr,
cmd_line_w.ptr,
env_block,
cwd_ptr,
flags,
lpStartupInfo,
lpProcessInformation,
)) |_| {
return;
} else |err| switch (err) {
error.FileNotFound => continue,
error.AccessDenied => continue,
error.InvalidExe => {
// 遇到 InvalidExe 时,若应用名称扩展名为 .exe,
// 则视为不可恢复错误。否则,
// 按常规跳过。
if (windows.eqlIgnoreCaseWtf16(ext, std.unicode.utf8ToUtf16LeStringLiteral(".EXE"))) {
return error.UnrecoverableInvalidExe;
}
continue;
},
else => return err,
}
}
return unappended_err;
}
fn windowsCreateProcess(
app_name: [*:0]u16,
cmd_line: [*:0]u16,
env_block: ?process.Environ.WindowsBlock,
cwd_ptr: ?[*:0]u16,
flags: windows.CreateProcessFlags,
lpStartupInfo: *windows.STARTUPINFOW,
lpProcessInformation: *windows.PROCESS.INFORMATION,
) !void {
const syscall: Syscall = try .start();
while (true) {
if (windows.kernel32.CreateProcessW(
app_name,
cmd_line,
null,
null,
.TRUE,
flags,
if (env_block) |block| block.slice.ptr else null,
cwd_ptr,
lpStartupInfo,
lpProcessInformation,
).toBool()) {
return syscall.finish();
} else switch (windows.GetLastError()) {
.INVALID_PARAMETER => unreachable,
.OPERATION_ABORTED => {
try syscall.checkCancel();
continue;
},
.FILE_NOT_FOUND => return syscall.fail(error.FileNotFound),
.PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.DIRECTORY => return syscall.fail(error.FileNotFound),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.INVALID_NAME => return syscall.fail(error.InvalidName),
.FILENAME_EXCED_RANGE => return syscall.fail(error.NameTooLong),
.SHARING_VIOLATION => return syscall.fail(error.FileBusy),
.COMMITMENT_LIMIT => return syscall.fail(error.SystemResources),
// 这些是未记录在文档中的 _dosmaperr,即旧 CRT,或 __acrt_errno_map_os_error,
// 即新 CRT,映射到 ENOEXEC 的全部系统错误。
// 代码位于 Windows SDK 的 crt/src/dosmap.c,旧 SDK,
// 或 urt/misc/errno.cpp,新 SDK。
.BAD_FORMAT,
.INVALID_STARTING_CODESEG, // errno.cpp 中的 MIN_EXEC_ERROR
.INVALID_STACKSEG,
.INVALID_MODULETYPE,
.INVALID_EXE_SIGNATURE,
.EXE_MARKED_INVALID,
.BAD_EXE_FORMAT,
.ITERATED_DATA_EXCEEDS_64k,
.INVALID_MINALLOCSIZE,
.DYNLINK_FROM_INVALID_RING,
.IOPL_NOT_ENABLED,
.INVALID_SEGDPL,
.AUTODATASEG_EXCEEDS_64k,
.RING2SEG_MUST_BE_MOVABLE,
.RELOC_CHAIN_XEEDS_SEGLIM,
.INFLOOP_IN_RELOC_CHAIN, // errno.cpp 中的 MAX_EXEC_ERROR。
// 此错误未映射到 ENOEXEC,但仍可能发生,例如
// 对扩展名为 .exe 的纯文本文件调用 CreateProcessW 时。
.EXE_MACHINE_TYPE_MISMATCH,
=> return syscall.fail(error.InvalidExe),
else => |err| {
syscall.finish();
return windows.unexpectedError(err);
},
}
}
}
/// 不区分大小写的 WTF-16 查找
fn windowsCreateProcessSupportsExtension(ext: []const u16) ?process.WindowsExtension {
comptime {
// 确保此函数与枚举保持同步。
const field_names = @typeInfo(process.WindowsExtension).@"enum".field_names;
assert(field_names.len == 4);
assert(@backingInt(process.WindowsExtension.bat) == 0);
assert(@backingInt(process.WindowsExtension.cmd) == 1);
assert(@backingInt(process.WindowsExtension.com) == 2);
assert(@backingInt(process.WindowsExtension.exe) == 3);
}
if (ext.len != 4) return null;
const State = enum {
start,
dot,
b,
ba,
c,
cm,
co,
e,
ex,
};
var state: State = .start;
for (ext) |c| switch (state) {
.start => switch (c) {
'.' => state = .dot,
else => return null,
},
.dot => switch (c) {
'b', 'B' => state = .b,
'c', 'C' => state = .c,
'e', 'E' => state = .e,
else => return null,
},
.b => switch (c) {
'a', 'A' => state = .ba,
else => return null,
},
.c => switch (c) {
'm', 'M' => state = .cm,
'o', 'O' => state = .co,
else => return null,
},
.e => switch (c) {
'x', 'X' => state = .ex,
else => return null,
},
.ba => switch (c) {
't', 'T' => return .bat,
else => return null,
},
.cm => switch (c) {
'd', 'D' => return .cmd,
else => return null,
},
.co => switch (c) {
'm', 'M' => return .com,
else => return null,
},
.ex => switch (c) {
'e', 'E' => return .exe,
else => return null,
},
};
return null;
}
test windowsCreateProcessSupportsExtension {
try std.testing.expectEqual(process.WindowsExtension.exe, windowsCreateProcessSupportsExtension(&[_]u16{ '.', 'e', 'X', 'e' }).?);
try std.testing.expect(windowsCreateProcessSupportsExtension(&[_]u16{ '.', 'e', 'X', 'e', 'c' }) == null);
}
/// 将 argv 序列化为 WTF-16 编码的命令行字符串,供 CreateProcessW 使用。
///
/// 按需序列化并缓存结果,以便:
/// - 只序列化需要的命令行类型;`.bat`、`.cmd`
/// 的命令行序列化方式与 `.exe` 等不同。
/// - 必要时复用已序列化的命令行,例如命令执行
/// 失败后,还需继续搜索 PATH
/// 中的其他候选项。
const WindowsCommandLineCache = struct {
cmd_line: ?[:0]u16 = null,
script_cmd_line: ?[:0]u16 = null,
cmd_exe_path: ?[:0]u16 = null,
argv: []const []const u8,
allocator: Allocator,
fn init(allocator: Allocator, argv: []const []const u8) WindowsCommandLineCache {
return .{
.allocator = allocator,
.argv = argv,
};
}
fn deinit(self: *WindowsCommandLineCache) void {
if (self.cmd_line) |cmd_line| self.allocator.free(cmd_line);
if (self.script_cmd_line) |script_cmd_line| self.allocator.free(script_cmd_line);
if (self.cmd_exe_path) |cmd_exe_path| self.allocator.free(cmd_exe_path);
}
fn commandLine(self: *WindowsCommandLineCache) ![:0]u16 {
if (self.cmd_line == null) {
self.cmd_line = try argvToCommandLineWindows(self.allocator, self.argv);
}
return self.cmd_line.?;
}
/// 不缓存,因为搜索 PATH 时,批处理脚本路径会变化。
/// `script_path` 应尽可能完整,例如搜索 PATH 时,script_path 应同时包含搜索路径与脚本文件名,从而避免 cmd.exe 再次搜索 PATH。
///
///
fn scriptCommandLine(self: *WindowsCommandLineCache, script_path: []const u16) ![:0]u16 {
if (self.script_cmd_line) |v| self.allocator.free(v);
self.script_cmd_line = try argvToScriptCommandLineWindows(
self.allocator,
script_path,
self.argv[1..],
);
return self.script_cmd_line.?;
}
fn cmdExePath(self: *WindowsCommandLineCache) Allocator.Error![:0]u16 {
if (self.cmd_exe_path == null) {
// 移除系统目录路径末尾的斜杠;稍后会重新添加。
const system_dir = std.mem.trimEnd(u16, windows.getSystemDirectoryWtf16Le(), &.{ '/', '\\' });
const suffix = std.unicode.utf8ToUtf16LeStringLiteral("\\cmd.exe");
const buf = try self.allocator.allocSentinel(u16, system_dir.len + suffix.len, 0);
errdefer comptime unreachable;
@memcpy(buf[0..system_dir.len], system_dir);
@memcpy(buf[system_dir.len..], suffix);
self.cmd_exe_path = buf;
}
return self.cmd_exe_path.?;
}
};
const ArgvToScriptCommandLineError = error{
OutOfMemory,
InvalidWtf8,
/// 执行 `.bat`/`.cmd` 脚本时,参数内不允许包含
/// NUL(U+0000)、LF(U+000A)、CR(U+000D)。
/// - NUL/LF 表示参数结束,因此其后所有内容
/// 在执行后都会丢失。
/// - `cmd.exe` 会移除 CR,因此任何 CR 码点
/// 在执行后都会丢失。
InvalidBatchScriptArg,
};
/// 将 `argv` 序列化为 Windows 命令行字符串,使用 `cmd.exe /c` 及 `cmd.exe` 专用转义规则。调用方拥有返回切片的所有权。
///
/// 转义 `argv` 时采用以下文章针对任意命令执行所建议的缓解措施:
/// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
///
/// 此函数返回的内容形如
/// `cmd.exe /d /e:ON /v:OFF /c "<escaped command line>"`
/// 应将其用作 `CreateProcessW` 的 `lpCommandLine`,而 `WindowsCommandLineCache.cmdExePath` 的返回值应作为 `lpApplicationName`。
///
/// 仅在创建 `.bat`/`.cmd` 脚本进程时使用;其他情况见 `argvToCommandLineWindows`。必须已知该 `.bat`/`.cmd` 文件既具有 `.bat`/`.cmd` 扩展名,也确实存在于文件系统中。
///
///
///
fn argvToScriptCommandLineWindows(
allocator: Allocator,
/// `.bat`/`.cmd` 脚本的路径。若为相对路径,则假定相对于当前工作目录。
/// 调用此函数前,必须已确认脚本存在于此路径。
script_path: []const u16,
/// 参数,不包括脚本名称本身。预期采用 WTF-8 编码。
script_args: []const []const u8,
) ArgvToScriptCommandLineError![:0]u16 {
var buf = try std.array_list.Managed(u8).initCapacity(allocator, 64);
defer buf.deinit();
// `/d` 禁止执行 AutoRun 命令。
// 缓解 BatBadBut 漏洞需要 `/e:ON` 和 `/v:OFF`:
// > 若通过注册表值 DelayedExpansion 启用了延迟展开,必须显式以 /V:OFF 选项调用 cmd.exe 来禁用它。
// > 对 % 的转义要求启用命令扩展。
// > 若通过注册表值 EnableExtensions 禁用了命令扩展,必须使用 /E:ON 选项启用。
// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
//
buf.appendSliceAssumeCapacity("cmd.exe /d /e:ON /v:OFF /c \"");
// 脚本参数的路径始终加引号
buf.appendAssumeCapacity('"');
// 始终希望批处理脚本路径包含路径分隔符,
// 以避免 cmd.exe 通过 PATH 搜索脚本。这并非缓解任意
// 命令执行风险的措施,而是因为此时已准确知道
// 希望执行哪个脚本,无需让 cmd.exe 再次查找。
//
// 若脚本路径不含分隔符,便知道它相对于 CWD,
// 直接在开头加上 `.\` 即可。
if (std.mem.findAny(u16, script_path, &[_]u16{
std.mem.nativeToLittle(u16, '\\'), std.mem.nativeToLittle(u16, '/'),
}) == null) {
try buf.appendSlice(".\\");
}
// 注意,此参数无需进行转义或防护,因为相关字符("、%、等)在文件路径中
// 均不合法,而且此函数只应对已确认存在的脚本路径调用。
//
try std.unicode.wtf16LeToWtf8ArrayList(&buf, script_path);
buf.appendAssumeCapacity('"');
for (script_args) |arg| {
// 经过 cmd.exe 时,字面回车符会被移除,
// NUL 和换行符会充当“命令结束”。因此,
// 在 argv 中包含这些字符几乎总是错误,
// 这里将其视为错误情况,以确保此函数的返回值
// 始终能够经 cmd.exe 无损往返。
if (std.mem.findAny(u8, arg, "\x00\r\n") != null) {
return error.InvalidBatchScriptArg;
}
// 用空格分隔参数。
try buf.append(' ');
// 参数为空时需要加引号,否则该参数会丢失;
// 末尾字符为 `\` 时也需要,因为 .bat 脚本中类似 "%~2" 的写法
// 会使闭合引号被转义,而这并非所需行为。
var needs_quotes = arg.len == 0 or arg[arg.len - 1] == '\\';
if (!needs_quotes) {
for (arg) |c| {
switch (c) {
// 已知无需加引号的安全字符
'A'...'Z', 'a'...'z', '0'...'9', '#', '$', '*', '+', '-', '.', '/', ':', '?', '@', '\\', '_' => {},
// 无法确定时加引号
else => {
needs_quotes = true;
break;
},
}
}
}
if (needs_quotes) {
try buf.append('"');
}
var backslashes: usize = 0;
for (arg) |c| {
switch (c) {
'\\' => {
backslashes += 1;
},
'"' => {
try buf.appendNTimes('\\', backslashes);
try buf.append('"');
backslashes = 0;
},
// 将 `%` 替换为 `%%cd:~,%`。
//
// cmd.exe 允许使用 `%foo:~<start_index>,<end_index>%` 语法,从环境变量中提取子字符串。
// 因此,`%cd:~,%` 始终展开为空字符串,因为起止索引均为空,并假定 `%cd%` 始终存在,因为它是对应当前目录的内置变量。
//
// 这意味着,将 `%foo%` 替换为 `%%cd:~,%foo%%cd:~,%`,可阻止 `%foo%` 被展开,并且在展开之后仍保留 `%foo%` 这一字面字符串。
//
//
//
//
//
//
'%' => {
// 尾随 `%` 在 switch 外部追加。
try buf.appendSlice("%%cd:~,");
backslashes = 0;
},
else => {
backslashes = 0;
},
}
try buf.append(c);
}
if (needs_quotes) {
try buf.appendNTimes('\\', backslashes);
try buf.append('"');
}
}
try buf.append('"');
return try std.unicode.wtf8ToWtf16LeAllocZ(allocator, buf.items);
}
const ArgvToCommandLineError = error{ OutOfMemory, InvalidWtf8, InvalidArg0 };
/// 将 `argv` 序列化为 Windows 命令行字符串,可传给子进程并由
/// `CommandLineToArgvW` 算法解析。调用方拥有返回切片。
///
/// 启动 `.bat`/`.cmd` 脚本时,不应使用此函数,以免发生任意命令执行。
/// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
///
/// 执行 `.bat`/`.cmd` 脚本时,请改用 `argvToScriptCommandLineWindows`。
fn argvToCommandLineWindows(
allocator: Allocator,
argv: []const []const u8,
) ArgvToCommandLineError![:0]u16 {
var buf = std.array_list.Managed(u8).init(allocator);
defer buf.deinit();
if (argv.len != 0) {
const arg0 = argv[0];
// 第一个参数若包含空格或 ASCII 控制字符(不包括 DEL),则必须加引号。它还遵循特殊引号规则,其中反斜杠没有特殊含义,因此某些包含双引号的第一个参数无法正确传给子进程,而不会使其中的字符泄漏到后续参数中,这可能产生安全影响。
//
// 空参数在技术上不需要引号,但为最大限度兼容“CommandLineToArgvW”算法的不同实现,仍为其添加引号。
//
// Windows 路径不允许双引号,因此为简化处理,拒绝所有包含双引号的第一个参数,即使其中某些参数理论上可以不加引号序列化。
//
//
//
//
//
//
//
var needs_quotes = arg0.len == 0;
for (arg0) |c| {
if (c <= ' ') {
needs_quotes = true;
} else if (c == '"') {
return error.InvalidArg0;
}
}
if (needs_quotes) {
try buf.append('"');
try buf.appendSlice(arg0);
try buf.append('"');
} else {
try buf.appendSlice(arg0);
}
for (argv[1..]) |arg| {
try buf.append(' ');
// 后续参数若包含空格、制表符、双引号,
// 或为空,则必须加引号。为简单起见并最大限度兼容不同
// CommandLineToArgvW 算法实现,也会为所有 ASCII
// 控制字符加引号,同样不包括 DEL。
needs_quotes = for (arg) |c| {
if (c <= ' ' or c == '"') {
break true;
}
} else arg.len == 0;
if (!needs_quotes) {
try buf.appendSlice(arg);
continue;
}
try buf.append('"');
var backslash_count: usize = 0;
for (arg) |byte| {
switch (byte) {
'\\' => {
backslash_count += 1;
},
'"' => {
try buf.appendNTimes('\\', backslash_count * 2 + 1);
try buf.append('"');
backslash_count = 0;
},
else => {
try buf.appendNTimes('\\', backslash_count);
try buf.append(byte);
backslash_count = 0;
},
}
}
try buf.appendNTimes('\\', backslash_count * 2);
try buf.append('"');
}
}
return try std.unicode.wtf8ToWtf16LeAllocZ(allocator, buf.items);
}
test argvToCommandLineWindows {
const t = testArgvToCommandLineWindows;
try t(&.{
\\C:\Program Files\zig\zig.exe
,
\\run
,
\\.\src\main.zig
,
\\-target
,
\\x86_64-windows-gnu
,
\\-O
,
\\safe
,
\\--
,
\\--emoji=🗿
,
\\--eval=new Regex("Dwayne \"The Rock\" Johnson")
,
},
\\"C:\Program Files\zig\zig.exe" run .\src\main.zig -target x86_64-windows-gnu -O safe -- --emoji=🗿 "--eval=new Regex(\"Dwayne \\\"The Rock\\\" Johnson\")"
);
try t(&.{}, "");
try t(&.{""}, "\"\"");
try t(&.{" "}, "\" \"");
try t(&.{"\t"}, "\"\t\"");
try t(&.{"\x07"}, "\"\x07\"");
try t(&.{"🦎"}, "🦎");
try t(
&.{ "zig", "aa aa", "bb\tbb", "cc\ncc", "dd\r\ndd", "ee\x7Fee" },
"zig \"aa aa\" \"bb\tbb\" \"cc\ncc\" \"dd\r\ndd\" ee\x7Fee",
);
try t(
&.{ "\\\\foo bar\\foo bar\\", "\\\\zig zag\\zig zag\\" },
"\"\\\\foo bar\\foo bar\\\" \"\\\\zig zag\\zig zag\\\\\"",
);
try std.testing.expectError(
error.InvalidArg0,
argvToCommandLineWindows(std.testing.allocator, &.{"\"quotes\"quotes\""}),
);
try std.testing.expectError(
error.InvalidArg0,
argvToCommandLineWindows(std.testing.allocator, &.{"quotes\"quotes"}),
);
try std.testing.expectError(
error.InvalidArg0,
argvToCommandLineWindows(std.testing.allocator, &.{"q u o t e s \" q u o t e s"}),
);
}
fn testArgvToCommandLineWindows(argv: []const []const u8, expected_cmd_line: []const u8) !void {
const cmd_line_w = try argvToCommandLineWindows(std.testing.allocator, argv);
defer std.testing.allocator.free(cmd_line_w);
const cmd_line = try std.unicode.wtf16LeToWtf8Alloc(std.testing.allocator, cmd_line_w);
defer std.testing.allocator.free(cmd_line);
try std.testing.expectEqualStrings(expected_cmd_line, cmd_line);
}
fn posixExec(
exe: process.ReplaceOptions.Exe,
argv: [*:null]?[*:0]const u8,
expand_arg0: process.ArgExpansion,
env_block: process.Environ.PosixBlock,
PATH: []const u8,
) process.ReplaceError {
const arg0_slice = std.mem.span(argv[0].?);
exe: switch (exe) {
.detect => continue :exe if (std.mem.findScalar(u8, arg0_slice, '/')) |_| .{
.path = .cwd(),
} else .search,
.search => {
if (Dir.path.isAbsolute(arg0_slice)) continue :exe .{ .path = .cwd() };
// 此处使用 PATH_MAX 合理,因为 path_buf 会在
// posixExecveat 中直接传给操作系统。
var path_buf: [posix.PATH_MAX]u8 = undefined;
var it = std.mem.tokenizeScalar(u8, PATH, ':');
var err: error{ AccessDenied, FileNotFound, NotDir } = error.FileNotFound;
while (it.next()) |search_path| {
const path_len = search_path.len + arg0_slice.len + 1;
if (path_buf.len < path_len + 1) return error.NameTooLong;
@memcpy(path_buf[0..search_path.len], search_path);
path_buf[search_path.len] = Dir.path.sep;
@memcpy(path_buf[search_path.len + 1 ..][0..arg0_slice.len], arg0_slice);
path_buf[path_len] = 0;
const full_path = path_buf[0..path_len :0].ptr;
switch (expand_arg0) {
.expand => argv[0] = full_path,
.no_expand => {},
}
switch (posixExecveat(posix.AT.FDCWD, full_path, argv, env_block)) {
error.AccessDenied, error.FileNotFound, error.NotDir => |e| switch (err) {
error.AccessDenied => {},
error.FileNotFound, error.NotDir => err = e,
},
else => |e| return e,
}
}
return err;
},
.path => |path| return posixExecveat(path.handle, arg0_slice, argv, env_block),
.file => |file| return posixExecveat(file.handle, null, argv, env_block),
.explicit => |explicit| {
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const path_posix = try pathToPosix(explicit.path, &path_buffer);
return posixExecveat(explicit.dir.handle, path_posix, argv, env_block);
},
}
}
/// 此函数忽略 PATH 环境变量。
pub fn posixExecveat(
dir: posix.fd_t,
path: ?[*:0]const u8,
argv: [*:null]const ?[*:0]const u8,
env_block: process.Environ.PosixBlock,
) process.ReplaceError {
try Thread.checkCancel();
switch (err: {
if (path) |p| if (dir == posix.AT.FDCWD or Dir.path.isAbsoluteZ(p)) {
break :err posix.errno(posix.system.execve(p, argv, env_block.slice.ptr));
};
if (comptime native_os == .linux and (!builtin.link_libc or
(builtin.target.isGnuLibC() and builtin.target.os.version_range.linux.glibc.order(
.{ .major = 2, .minor = 34, .patch = 0 },
).compare(.gte))))
{
switch (posix.errno(posix.system.execveat(dir, path orelse "", argv, env_block.slice.ptr, .{
.EMPTY_PATH = path == null,
.SYMLINK_NOFOLLOW = false,
}))) {
else => |err| break :err err,
.NOSYS => {},
}
}
var path_buffer: [posix.PATH_MAX]u8 = undefined;
var path_len = realPathPosix(dir, &path_buffer) catch |err| switch (err) {
else => |e| return e,
error.InputOutput,
error.FileTooBig,
error.NoSpaceLeft,
error.PathAlreadyExists,
error.SymLinkLoop,
error.NetworkNotFound,
error.PipeBusy,
error.AntivirusInterference,
=> return error.FileNotFound,
error.DeviceBusy,
error.NoDevice,
error.UnrecognizedVolume,
=> return error.FileSystem,
};
if (path) |p| {
const path_slice = std.mem.span(p);
path_buffer[path_len] = Dir.path.sep;
path_len += 1;
@memcpy(path_buffer[path_len..][0..path_slice.len], path_slice);
path_len += path_slice.len;
}
path_buffer[path_len] = 0;
break :err posix.errno(
posix.system.execve(path_buffer[0..path_len :0], argv, env_block.slice.ptr),
);
}) {
.FAULT => |err| return errnoBug(err), // 错误的指针参数。
.@"2BIG" => return error.SystemResources,
.MFILE => return error.ProcessFdQuotaExceeded,
.NAMETOOLONG => return error.NameTooLong,
.NFILE => return error.SystemFdQuotaExceeded,
.NOMEM => return error.SystemResources,
.ACCES => return error.AccessDenied,
.PERM => return error.PermissionDenied,
.INVAL => return error.InvalidExe,
.NOEXEC => return error.InvalidExe,
.IO => return error.FileSystem,
.LOOP => return error.FileSystem,
.ISDIR => return error.IsDir,
.NOENT => return error.FileNotFound,
.NOTDIR => return error.NotDir,
.TXTBSY => return error.FileBusy,
else => |err| switch (native_os) {
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => switch (err) {
.BADEXEC => return error.InvalidExe,
.BADARCH => return error.InvalidExe,
else => return posix.unexpectedErrno(err),
},
.linux => switch (err) {
.LIBBAD => return error.InvalidExe,
else => return posix.unexpectedErrno(err),
},
else => return posix.unexpectedErrno(err),
},
}
}
fn spawnDarwin(
t: *Threaded,
mode: enum { spawn, replace },
exe: process.ReplaceOptions.Exe,
argv: [*:null]?[*:0]const u8,
cwd: process.Child.Cwd,
env_block: process.Environ.PosixBlock,
expand_arg0: process.ArgExpansion,
progress_node: std.Progress.Node,
stdin: process.SpawnOptions.StdIo,
stdout: process.SpawnOptions.StdIo,
stderr: process.SpawnOptions.StdIo,
inherit_dirs: []const Dir,
inherit_files: []const File,
pgid: ?posix.pid_t,
start_suspended: bool,
PATH: []const u8,
) (process.SpawnError || process.ReplaceError)!Spawned {
var fa: std.c.posix_spawn_file_actions_t = undefined;
switch (@as(std.c.E, @fromBackingInt(@intCast(std.c.posix_spawn_file_actions_init(&fa))))) {
.SUCCESS => {},
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
defer switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn_file_actions_destroy(&fa),
)))) {
.SUCCESS => {},
.INVAL => recoverableOsBugDetected(),
else => recoverableOsBugDetected(),
};
var attr: std.c.posix_spawnattr_t = undefined;
switch (@as(std.c.E, @fromBackingInt(@intCast(std.c.posix_spawnattr_init(&attr))))) {
.SUCCESS => {},
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
}
defer switch (@as(std.c.E, @fromBackingInt(@intCast(std.c.posix_spawnattr_destroy(&attr))))) {
.SUCCESS => {},
.INVAL => recoverableOsBugDetected(),
else => recoverableOsBugDetected(),
};
// 子进程确实需要访问这些管道的一端,但最初必须设置 CLOEXEC,以避免竞态条件。若另一个线程正在并发创建其他子进程,绝不能让后者继承这些文件描述符。例如,其他子进程可能保留管道写端引用,导致父进程调用 `poll` 时,无法在预期时机检测到目标子进程的标准输出关闭。
// 因此,创建管道时先设置 CLOEXEC。fork 后,必须在新子进程中确保保留所需引用。可以使用 `fcntl` 移除描述符上的 CLOEXEC,但实际上所有描述符都会经过 `dup2`,因此无需额外操作。
//
//
//
//
//
//
//
//
const pipe_flags: posix.O = .{ .CLOEXEC = true };
const stdin_pipe = if (stdin == .pipe) try pipe2(pipe_flags) else undefined;
errdefer if (stdin == .pipe) {
destroyPipe(stdin_pipe);
};
const stdout_pipe = if (stdout == .pipe) try pipe2(pipe_flags) else undefined;
errdefer if (stdout == .pipe) {
destroyPipe(stdout_pipe);
};
const stderr_pipe = if (stderr == .pipe) try pipe2(pipe_flags) else undefined;
errdefer if (stderr == .pipe) {
destroyPipe(stderr_pipe);
};
const any_ignore = (stdin == .ignore or stdout == .ignore or stderr == .ignore);
const dev_null_fd = if (any_ignore) try t.getDevNullFd() else undefined;
const prog_pipe: [2]posix.fd_t = if (progress_node.index != .none) pipe: {
// 与 `pipe_flags` 中相同的原因,使用 CLOEXEC。
break :pipe try pipe2(.{ .NONBLOCK = true, .CLOEXEC = true });
} else .{ -1, -1 };
errdefer destroyPipe(prog_pipe);
var cwd_buffer: [posix.PATH_MAX]u8 = undefined;
switch (cwd) {
.inherit => {},
.dir => |dir| switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn_file_actions_addfchdir_np(&fa, dir.handle),
)))) {
.SUCCESS => {},
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
},
.path => |path| switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn_file_actions_addchdir_np(&fa, try pathToPosix(path, &cwd_buffer)),
)))) {
.SUCCESS => {},
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.NAMETOOLONG => return error.NameTooLong,
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
},
}
for (inherit_dirs) |inherit_dir| switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn_file_actions_addinherit_np(&fa, inherit_dir.handle),
)))) {
.SUCCESS => {},
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
};
for (inherit_files) |inherit_file| switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn_file_actions_addinherit_np(&fa, inherit_file.handle),
)))) {
.SUCCESS => {},
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
};
if (prog_pipe[1] != -1) switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn_file_actions_addinherit_np(&fa, prog_pipe[1]),
)))) {
.SUCCESS => {},
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
};
for (
[_]process.SpawnOptions.StdIo{ stdin, stdout, stderr },
[_]posix.fd_t{ stdin_pipe[0], stdout_pipe[1], stderr_pipe[1] },
[_]posix.fd_t{ posix.STDIN_FILENO, posix.STDOUT_FILENO, posix.STDERR_FILENO },
) |stdio, pipe_fd, std_fd| switch (@as(std.c.E, @fromBackingInt(@intCast(switch (stdio) {
.pipe => std.c.posix_spawn_file_actions_adddup2(&fa, pipe_fd, std_fd),
.close => std.c.posix_spawn_file_actions_addclose(&fa, std_fd),
.inherit => std.c.posix_spawn_file_actions_addinherit_np(&fa, std_fd),
.ignore => std.c.posix_spawn_file_actions_adddup2(&fa, dev_null_fd, std_fd),
.file => |file| std.c.posix_spawn_file_actions_adddup2(&fa, file.handle, std_fd),
})))) {
.SUCCESS => {},
.BADF => |err| return errnoBug(err),
.INVAL => |err| return errnoBug(err),
.NOMEM => return error.SystemResources,
else => |err| return posix.unexpectedErrno(err),
};
if (pgid) |pid| switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawnattr_setpgroup(&attr, pid),
)))) {
.SUCCESS => {},
.INVAL => return error.InvalidProcessGroupId,
else => |err| return posix.unexpectedErrno(err),
};
switch (@as(std.c.E, @fromBackingInt(@intCast(std.c.posix_spawnattr_setflags(&attr, .{
.SETPGROUP = pgid != null,
.SETEXEC = switch (mode) {
.spawn => false,
.replace => true,
},
.START_SUSPENDED = start_suspended,
}))))) {
.SUCCESS => {},
.INVAL => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
var pid: posix.pid_t = undefined;
const arg0_slice = std.mem.span(argv[0].?);
var path_buffer: [posix.PATH_MAX]u8 = undefined;
switch (err: {
break :err @as(std.c.E, @fromBackingInt(@intCast(exe: switch (exe) {
.detect => if (std.mem.findScalar(u8, arg0_slice, '/')) |_|
std.c.posix_spawn(&pid, arg0_slice, &fa, &attr, argv, env_block.slice.ptr)
else
continue :exe .search,
.search => if (!Dir.path.isAbsolute(arg0_slice)) {
// 此处使用 PATH_MAX 合理,因为 path_buf 会在
// posixExecveat 中直接传给操作系统。
var path_buf: [posix.PATH_MAX]u8 = undefined;
var it = std.mem.tokenizeScalar(u8, PATH, ':');
var err: error{ AccessDenied, FileNotFound, NotDir } = error.FileNotFound;
while (it.next()) |search_path| {
const path_len = search_path.len + arg0_slice.len + 1;
if (path_buf.len < path_len + 1) return error.NameTooLong;
@memcpy(path_buf[0..search_path.len], search_path);
path_buf[search_path.len] = Dir.path.sep;
@memcpy(path_buf[search_path.len + 1 ..][0..arg0_slice.len], arg0_slice);
path_buf[path_len] = 0;
const full_path = path_buf[0..path_len :0].ptr;
switch (expand_arg0) {
.expand => argv[0] = full_path,
.no_expand => {},
}
switch (@as(std.c.E, @fromBackingInt(@intCast(
std.c.posix_spawn(&pid, full_path, &fa, &attr, argv, env_block.slice.ptr),
)))) {
else => |e| break :err e,
.ACCES, .NOENT, .NOTDIR => |e| switch (err) {
error.AccessDenied => {},
error.FileNotFound, error.NotDir => err = switch (e) {
else => unreachable,
.ACCES => error.AccessDenied,
.NOENT => error.FileNotFound,
.NOTDIR => error.NotDir,
},
},
}
}
return err;
} else std.c.posix_spawn(&pid, arg0_slice, &fa, &attr, argv, env_block.slice.ptr),
.path => |path| if (path.handle != posix.AT.FDCWD and !Dir.path.isAbsolute(arg0_slice)) {
var path_len = realPathPosix(path.handle, &path_buffer) catch |err| switch (err) {
else => |e| return e,
error.InputOutput => return error.FileNotFound,
};
path_buffer[path_len] = Dir.path.sep;
path_len += 1;
@memcpy(path_buffer[path_len..][0..arg0_slice.len], arg0_slice);
path_len += arg0_slice.len;
path_buffer[path_len] = 0;
break :exe std.c.posix_spawn(
&pid,
path_buffer[0..path_len :0],
&fa,
&attr,
argv,
env_block.slice.ptr,
);
} else std.c.posix_spawn(&pid, arg0_slice, &fa, &attr, argv, env_block.slice.ptr),
.file => |file| {
const path_len = realPathPosix(file.handle, &path_buffer) catch |err| switch (err) {
else => |e| return e,
error.InputOutput => return error.FileNotFound,
};
path_buffer[path_len] = 0;
break :exe std.c.posix_spawn(
&pid,
path_buffer[0..path_len :0],
&fa,
&attr,
argv,
env_block.slice.ptr,
);
},
.explicit => |explicit| if (explicit.dir.handle != posix.AT.FDCWD and
!Dir.path.isAbsolute(explicit.path))
{
var path_len = realPathPosix(
explicit.dir.handle,
&path_buffer,
) catch |err| switch (err) {
else => |e| return e,
error.InputOutput => return error.FileNotFound,
};
path_buffer[path_len] = Dir.path.sep;
path_len += 1;
@memcpy(path_buffer[path_len..][0..explicit.path.len], explicit.path);
path_len += explicit.path.len;
path_buffer[path_len] = 0;
break :exe std.c.posix_spawn(
&pid,
path_buffer[0..path_len :0],
&fa,
&attr,
argv,
env_block.slice.ptr,
);
} else std.c.posix_spawn(
&pid,
try pathToPosix(explicit.path, &path_buffer),
&fa,
&attr,
argv,
env_block.slice.ptr,
),
})));
}) {
.SUCCESS => {},
.AGAIN => return error.SystemResources,
.INVAL => |err| return errnoBug(err),
.@"2BIG" => return error.SystemResources,
.ACCES => return error.AccessDenied,
.FAULT => |err| return errnoBug(err),
.IO => return error.FileSystem,
.LOOP => return error.FileSystem,
.NAMETOOLONG => return error.NameTooLong,
.NOENT => return error.FileNotFound,
.NOEXEC => return error.InvalidExe,
.NOMEM => return error.SystemResources,
.NOTDIR => return error.NotDir,
.TXTBSY => return error.FileBusy,
.BADARCH => return error.InvalidExe,
.BADF => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
errdefer comptime unreachable; // 子进程已创建;此后不得再返回错误
if (stdin == .pipe) closeFd(stdin_pipe[0]);
if (stdout == .pipe) closeFd(stdout_pipe[1]);
if (stderr == .pipe) closeFd(stderr_pipe[1]);
if (prog_pipe[1] != -1) closeFd(prog_pipe[1]);
progress_node.setIpcFile(t, .{ .handle = prog_pipe[0], .flags = .{ .nonblocking = true } });
return .{
.pid = pid,
.err_fd = -1,
.stdin = switch (stdin) {
.pipe => .{ .handle = stdin_pipe[1], .flags = .{ .nonblocking = false } },
else => null,
},
.stdout = switch (stdout) {
.pipe => .{ .handle = stdout_pipe[0], .flags = .{ .nonblocking = false } },
else => null,
},
.stderr = switch (stderr) {
.pipe => .{ .handle = stderr_pipe[0], .flags = .{ .nonblocking = false } },
else => null,
},
};
}
pub const CreatePipeOptions = struct {
server: End,
client: End,
inbound: bool = false,
outbound: bool = false,
maximum_instances: u32 = 1,
quota: u32 = 4096,
default_timeout: windows.LARGE_INTEGER = -120 * std.time.ns_per_s / 100,
pub const End = struct {
attributes: windows.OBJECT.ATTRIBUTES.Flags = .{},
mode: windows.FILE.MODE,
};
};
pub fn windowsCreatePipe(t: *Threaded, options: CreatePipeOptions) ![2]windows.HANDLE {
const named_pipe_device = try t.getNamedPipeDevice();
const server_handle = server_handle: {
var handle: windows.HANDLE = undefined;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtCreateNamedPipeFile(
&handle,
.{
.SPECIFIC = .{ .FILE_PIPE = .{
.READ_DATA = options.inbound,
.WRITE_DATA = options.outbound,
.WRITE_ATTRIBUTES = true,
} },
.STANDARD = .{ .SYNCHRONIZE = true },
},
&.{
.RootDirectory = named_pipe_device,
.Attributes = options.server.attributes,
},
&io_status_block,
.{ .READ = true, .WRITE = true },
.CREATE,
options.server.mode,
.{ .TYPE = .BYTE_STREAM },
.{ .MODE = .BYTE_STREAM },
.{ .OPERATION = .QUEUE },
options.maximum_instances,
if (options.inbound) options.quota else 0,
if (options.outbound) options.quota else 0,
&options.default_timeout,
)) {
.SUCCESS => break syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.INSUFFICIENT_RESOURCES => return syscall.fail(error.SystemResources),
else => |status| return syscall.unexpectedNtstatus(status),
};
break :server_handle handle;
};
errdefer windows.CloseHandle(server_handle);
const client_handle = client_handle: {
var handle: windows.HANDLE = undefined;
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
const syscall: Syscall = try .start();
while (true) switch (windows.ntdll.NtOpenFile(
&handle,
.{
.SPECIFIC = .{ .FILE_PIPE = .{
.READ_DATA = options.outbound,
.WRITE_DATA = options.inbound,
.WRITE_ATTRIBUTES = true,
} },
.STANDARD = .{ .SYNCHRONIZE = true },
},
&.{
.RootDirectory = server_handle,
.Attributes = options.client.attributes,
},
&io_status_block,
.{ .READ = true, .WRITE = true },
options.client.mode,
)) {
.SUCCESS => break syscall.finish(),
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.INSUFFICIENT_RESOURCES => return syscall.fail(error.SystemResources),
else => |status| return syscall.unexpectedNtstatus(status),
};
break :client_handle handle;
};
errdefer windows.CloseHandle(client_handle);
return .{ server_handle, client_handle };
}
fn progressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
t.scanEnviron();
return t.environ.zig_progress_file;
}
fn inheritParentHandle(handle: posix.fd_t) Io.InheritParentHandleError!void {
switch (native_os) {
.linux,
.dragonfly,
.freebsd,
.netbsd,
.openbsd,
.illumos,
.driverkit,
.ios,
.maccatalyst,
.macos,
.tvos,
.visionos,
.watchos,
=> return setCloexec(handle),
.windows => switch (windows.ntdll.NtSetInformationObject(
handle,
.HandleFlag,
&windows.OBJECT.HANDLE_FLAG{ .INHERIT = false },
@sizeOf(windows.OBJECT.HANDLE_FLAG),
)) {
.SUCCESS => return,
else => |status| return windows.unexpectedStatus(status),
},
else => return error.UnsupportedOperation,
}
}
fn inheritParentDir(userdata: ?*anyopaque, handle: Dir.Handle) Io.InheritParentHandleError!Dir {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
try inheritParentHandle(handle);
return .{ .handle = handle };
}
fn inheritParentFile(
userdata: ?*anyopaque,
handle: File.Handle,
flags: File.Flags,
) Io.InheritParentHandleError!File {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
try inheritParentHandle(handle);
return .{ .handle = handle, .flags = flags };
}
pub fn environString(t: *Threaded, comptime name: []const u8) ?[:0]const u8 {
t.scanEnviron();
return @field(t.environ.string, name);
}
fn random(userdata: ?*anyopaque, buffer: []u8) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const thread = Thread.current orelse return randomMainThread(t, buffer);
if (!thread.csprng.isInitialized()) {
@branchHint(.unlikely);
var seed: [Csprng.seed_len]u8 = undefined;
randomMainThread(t, &seed);
thread.csprng.rng = .init(seed);
}
thread.csprng.rng.fill(buffer);
}
fn randomMainThread(t: *Threaded, buffer: []u8) void {
mutexLockUncancelable(&t.mutex);
defer mutexUnlock(&t.mutex);
if (!t.csprng.isInitialized()) {
@branchHint(.unlikely);
var seed: [Csprng.seed_len]u8 = undefined;
{
mutexUnlock(&t.mutex);
defer mutexLockUncancelable(&t.mutex);
const prev = swapCancelProtection(t, .blocked);
defer _ = swapCancelProtection(t, prev);
randomSecure(t, &seed) catch |err| switch (err) {
error.Canceled => unreachable,
error.EntropyUnavailable => fallbackSeed(t, &seed),
};
}
t.csprng.rng = .init(seed);
}
t.csprng.rng.fill(buffer);
}
pub fn fallbackSeed(aslr_addr: ?*anyopaque, seed: *[Csprng.seed_len]u8) void {
@memset(seed, 0);
std.mem.writeInt(usize, seed[seed.len - @sizeOf(usize) ..][0..@sizeOf(usize)], @intFromPtr(aslr_addr), .native);
const fallbackSeedImpl = switch (native_os) {
.windows => fallbackSeedWindows,
.wasi => if (builtin.link_libc) fallbackSeedPosix else fallbackSeedWasi,
else => fallbackSeedPosix,
};
fallbackSeedImpl(seed);
}
fn fallbackSeedPosix(seed: *[Csprng.seed_len]u8) void {
std.mem.writeInt(posix.pid_t, seed[0..@sizeOf(posix.pid_t)], posix.system.getpid(), .native);
const i_1 = @sizeOf(posix.pid_t);
var ts: posix.timespec = undefined;
const Sec = @TypeOf(ts.sec);
const Nsec = @TypeOf(ts.nsec);
const i_2 = i_1 + @sizeOf(Sec);
switch (posix.errno(posix.system.clock_gettime(.REALTIME, &ts))) {
.SUCCESS => {
std.mem.writeInt(Sec, seed[i_1..][0..@sizeOf(Sec)], ts.sec, .native);
std.mem.writeInt(Nsec, seed[i_2..][0..@sizeOf(Nsec)], ts.nsec, .native);
},
else => {},
}
}
fn fallbackSeedWindows(seed: *[Csprng.seed_len]u8) void {
var pc: windows.LARGE_INTEGER = undefined;
_ = windows.ntdll.RtlQueryPerformanceCounter(&pc);
std.mem.writeInt(windows.LARGE_INTEGER, seed[0..@sizeOf(windows.LARGE_INTEGER)], pc, .native);
}
fn fallbackSeedWasi(seed: *[Csprng.seed_len]u8) void {
var ts: std.os.wasi.timestamp_t = undefined;
if (std.os.wasi.clock_time_get(.REALTIME, 1, &ts) == .SUCCESS) {
std.mem.writeInt(std.os.wasi.timestamp_t, seed[0..@sizeOf(std.os.wasi.timestamp_t)], ts, .native);
}
}
fn randomSecure(userdata: ?*anyopaque, buffer: []u8) Io.RandomSecureError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
if (is_windows) {
if (buffer.len == 0) return;
// bcryptprimitives.dll 中的 ProcessPrng 具有以下特点:
// * 引入 bcryptprimitives.dll 依赖,该库似乎
// 每次加载都会运行测试套件。
// * 在堆上分配 48 字节缓冲区,失败时以 BOOL 返回 NO_MEMORY,
// 尽管文档声称该函数始终返回 TRUE。
// * 读取 "\\Device\\CNG",随后为每 CPU 的 AES CSPRNG 设置种子。
// 因此,避免使用该函数,改为直接访问设备。
const cng_device = try getCngDevice(t);
var io_status_block: windows.IO_STATUS_BLOCK = undefined;
var i: usize = 0;
const syscall: Syscall = try .start();
while (true) {
const remaining_len = std.math.lossyCast(u32, buffer.len - i);
switch (windows.ntdll.NtDeviceIoControlFile(
cng_device,
null,
null,
null,
&io_status_block,
windows.IOCTL.KSEC.GEN_RANDOM,
null,
0,
buffer[i..].ptr,
remaining_len,
)) {
.SUCCESS => {
i += remaining_len;
if (buffer.len - i == 0) {
return syscall.finish();
} else {
try syscall.checkCancel();
continue;
}
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
}
}
}
if (builtin.link_libc and @TypeOf(posix.system.arc4random_buf) != void) {
if (buffer.len == 0) return;
posix.system.arc4random_buf(buffer.ptr, buffer.len);
return;
}
if (native_os == .wasi) {
if (buffer.len == 0) return;
const syscall: Syscall = try .start();
while (true) switch (std.os.wasi.random_get(buffer.ptr, buffer.len)) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
};
}
if (@TypeOf(posix.system.getrandom) != void) {
const getrandom = if (use_libc_getrandom) std.c.getrandom else std.os.linux.getrandom;
var i: usize = 0;
const syscall: Syscall = try .start();
while (buffer.len - i != 0) {
const buf = buffer[i..];
const rc = getrandom(buf.ptr, buf.len, 0);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const n: usize = @intCast(rc);
i += n;
continue;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
}
}
return;
}
if (native_os == .emscripten) {
if (buffer.len == 0) return;
const err = posix.errno(std.c.getentropy(buffer.ptr, buffer.len));
switch (err) {
.SUCCESS => return,
else => return error.EntropyUnavailable,
}
}
if (native_os == .linux) {
comptime assert(use_dev_urandom);
const urandom_fd = try getRandomFd(t);
var i: usize = 0;
while (buffer.len - i != 0) {
const syscall: Syscall = try .start();
const rc = posix.system.read(urandom_fd, buffer[i..].ptr, buffer.len - i);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
const n: usize = @intCast(rc);
if (n == 0) return error.EntropyUnavailable;
i += n;
continue;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
}
}
}
return error.EntropyUnavailable;
}
fn getRandomFd(t: *Threaded) Io.RandomSecureError!posix.fd_t {
{
try mutexLock(&t.mutex);
defer mutexUnlock(&t.mutex);
if (t.random_file.fd == -2) return error.EntropyUnavailable;
if (t.random_file.fd != -1) return t.random_file.fd;
}
const mode: posix.mode_t = 0;
const fd: posix.fd_t = fd: {
const syscall: Syscall = try .start();
while (true) {
const rc = openat_sym(posix.AT.FDCWD, "/dev/urandom", .{
.ACCMODE = .RDONLY,
.CLOEXEC = true,
}, mode);
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
break :fd @intCast(rc);
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
}
}
};
errdefer closeFd(fd);
switch (native_os) {
.linux => {
const sys = if (statx_use_c) std.c else std.os.linux;
const syscall: Syscall = try .start();
while (true) {
var statx = std.mem.zeroes(std.os.linux.Statx);
switch (sys.errno(sys.statx(fd, "", std.os.linux.AT.EMPTY_PATH, .{ .TYPE = true }, &statx))) {
.SUCCESS => {
syscall.finish();
if (!statx.mask.TYPE) return error.EntropyUnavailable;
mutexLockUncancelable(&t.mutex); // 另一个线程可能已在竞态中获胜。
defer mutexUnlock(&t.mutex);
if (t.random_file.fd >= 0) {
closeFd(fd);
return t.random_file.fd;
} else if (!posix.S.ISCHR(statx.mode)) {
t.random_file.fd = -2;
return error.EntropyUnavailable;
} else {
t.random_file.fd = fd;
return fd;
}
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
}
}
},
else => {
const syscall: Syscall = try .start();
while (true) {
var stat = std.mem.zeroes(posix.Stat);
switch (posix.errno(fstat_sym(fd, &stat))) {
.SUCCESS => {
syscall.finish();
mutexLockUncancelable(&t.mutex); // 另一个线程可能已在竞态中获胜。
defer mutexUnlock(&t.mutex);
if (t.random_file.fd >= 0) {
closeFd(fd);
return t.random_file.fd;
} else if (!posix.S.ISCHR(stat.mode)) {
t.random_file.fd = -2;
return error.EntropyUnavailable;
} else {
t.random_file.fd = fd;
return fd;
}
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => return syscall.fail(error.EntropyUnavailable),
}
}
},
}
}
test {
_ = @import("Threaded/test.zig");
}
const use_parking_futex = switch (native_os) {
.windows => true, // RtlWaitOnAddress 本来就是用户态实现
.netbsd => true, // NetBSD 具有 `futex(2)`,但过去存在较多缺陷。TODO: 评估现在是否可用。
.illumos => true, // Illumos 没有 futex 机制
.haiku => true, // Haiku 没有 futex 机制
else => false,
};
const use_parking_sleep = switch (native_os) {
// 在 Windows 上,可以用 `NtDelayExecution`(kernel32 中 `SleepEx` 的实现方式)或 `NtWaitForAlertByThreadId`(线程停放)实现休眠。既然 futex 已使用后者,也可将其用于休眠,以最大限度复用代码。
// 作者也更确信它始终能正确处理取消竞态,即先解除停放再停放时,停放会立即返回。可警醒休眠配合 `NtAlertThread` 似乎也有这一行为,但可能存在某些特定条件下失效等限制;而 `NtWaitForAlertByThreadId` 必须可靠地提供这种行为,因为 `RtlWaitOnAddress` 依赖它。
//
//
//
//
//
//
.windows => true,
// 这些目标具有 `_lwp_park`,其取消机制更完善,
// 因此优于 POSIX nanosleep。
.netbsd,
.illumos,
=> true,
else => false,
};
const parking_futex = struct {
comptime {
assert(use_parking_futex);
}
const Bucket = struct {
/// 供 `wake` 快速检查,以免为了发现没有等待者而获取 `mutex`。
/// `wait` 必须在检查 futex 值*之前*递增此计数,
/// 以避免竞态条件。
num_waiters: std.atomic.Value(u32),
/// 保护 `waiters`。
mutex: ParkingMutex,
waiters: std.DoublyLinkedList,
/// 避免桶之间的伪共享。
_: void align(std.atomic.cache_line) = {},
const init: Bucket = .{ .num_waiters = .init(0), .mutex = .init, .waiters = .{} };
};
const Waiter = struct {
node: std.DoublyLinkedList.Node,
address: usize,
tid: ParkTid,
/// 线程等待时,`thread_status.cancelation` 为 `.parked`。
/// 以原子方式将其更新为 `.none` 或 `.canceling` 的唯一线程负责:
///
/// * 移除 `Waiter`,来源为 `Bucket.waiters`。
/// * 递减 `Bucket.num_waiters`。
/// * 解除线程停放,必须在上述操作之后执行,以免 `Waiter` 仍在 `Bucket` 中时就离开作用域。
///
thread_status: *std.atomic.Value(Thread.Status),
unpark_flag: if (need_unpark_flag) *UnparkFlag else void,
};
fn bucketForAddress(address: usize) *Bucket {
const global = struct {
/// 长度必须为二的幂。此数组越长,不同 futex 之间
/// 发生争用的可能性越小。此长度似乎能合理平衡
/// 争用与内存用量:假定 `Bucket` 为 128 字节(由于缓存行
/// 对齐),这里使用 32 KiB 内存。
var buckets: [256]Bucket = @splat(.init);
};
// 此处使用斐波那契哈希:黄金比例可将输入值均匀重新分布到某个范围,
// 得到质量较差但计算极快的哈希。
// 此字面量是“2^64 / phi”的舍入值,其中 phi 为黄金比例。
// 随后移位将其转换为“2^b / phi”,其中 b 为指针位宽。
const fibonacci_multiplier = 0x9E3779B97F4A7C15 >> (64 - @bitSizeOf(usize));
const hashed = address *% fibonacci_multiplier;
comptime assert(std.math.isPowerOfTwo(global.buckets.len));
// `hashed` 的高位比低位具有更好的熵。
const index = hashed >> (@bitSizeOf(usize) - @ctz(global.buckets.len));
return &global.buckets[index];
}
fn wait(ptr: *const u32, expect: u32, uncancelable: bool, timeout: Io.Timeout) Io.Cancelable!void {
const bucket = bucketForAddress(@intFromPtr(ptr));
// 将线程局部变量的访问移至临界区之外。
const opt_thread = Thread.current;
const self_tid = getParkTid();
var waiter: Waiter = .{
.node = undefined, // 通过列表追加操作填充
.address = @intFromPtr(ptr),
.tid = self_tid,
.thread_status = undefined, // 在临界区内填充
.unpark_flag = undefined, // 在临界区内填充
};
var status_buf: std.atomic.Value(Thread.Status) = undefined;
var unpark_flag_buf: UnparkFlag = unpark_flag_init;
{
bucket.mutex.lock();
defer bucket.mutex.unlock();
_ = bucket.num_waiters.fetchAdd(1, .acquire);
if (@atomicLoad(u32, ptr, .monotonic) != expect) {
assert(bucket.num_waiters.fetchSub(1, .monotonic) > 0);
return;
}
// 此操作置于临界区内,避免在线程确定实际进入停驻前就将其标记为已停驻。
//
waiter.thread_status, waiter.unpark_flag = status: {
cancelable: {
if (uncancelable) break :cancelable;
const thread = opt_thread orelse break :cancelable;
switch (thread.cancel_protection) {
.blocked => break :cancelable,
.unblocked => {},
}
thread.futex_waiter = &waiter;
const old_status = thread.status.fetchOr(
.{ .cancelation = @fromBackingInt(@intCast(0b001)), .awaitable = .null },
.release, // 释放 `thread.futex_waiter`
);
switch (old_status.cancelation) {
.none => {}, // 状态现在为 `.parked`
.canceling => {
// 状态现在为 `.canceled`
assert(bucket.num_waiters.fetchSub(1, .monotonic) > 0);
return error.Canceled;
},
.canceled => break :cancelable, // 状态仍为 `.canceled`
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
}
// 现在可能随时因取消而被解除挂起!
break :status .{ &thread.status, if (need_unpark_flag) &thread.unpark_flag };
}
// 这是不可取消的等待,因此直接使用 `status_buf`。注意,
// `status_buf.awaitable` 的值无关紧要,因为它仅对 futex 代码可见,
// 而只有取消逻辑才关心 `awaitable`。
status_buf.raw = .{ .cancelation = .parked, .awaitable = .null };
break :status .{ &status_buf, if (need_unpark_flag) &unpark_flag_buf };
};
bucket.waiters.append(&waiter.node);
}
if (park(timeout, ptr, waiter.unpark_flag)) {
// 已由 `wake` 或取消操作解除停驻,因此当前状态为
// `.none` 或 `.canceling`。无论哪种情况,对方均已从 `bucket`
// 移除 `waiter`,所以无需再做其他操作!
} else |err| switch (err) {
error.Timeout => {
// 问题尚未解决:取消停驻操作可能与超时发生竞态。
const old_status = waiter.thread_status.fetchAnd(
.{ .cancelation = @fromBackingInt(@intCast(0b110)), .awaitable = .all_ones },
.monotonic,
);
switch (old_status.cancelation) {
.parked => {
// 不存在竞态。由我们负责从 `bucket` 中移除 `waiter`。
// 新状态为 `.none`。
bucket.mutex.lock();
defer bucket.mutex.unlock();
bucket.waiters.remove(&waiter.node);
assert(bucket.num_waiters.fetchSub(1, .monotonic) > 0);
},
.none, .canceling => {
// 竞态:超时已到达,随后 `wake` 或取消方尝试
// 解除我们的停驻。执行该操作的一方会将我们从 `bucket` 移除。等待
// 此操作完成,同时丢弃解除停驻请求。
// 新状态分别为 `.none` 或 `.canceling`。
park(.none, ptr, waiter.unpark_flag) catch |e| switch (e) {
error.Timeout => unreachable,
};
},
.canceled => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_canceling => unreachable,
.blocked_alertable_canceling => unreachable,
}
},
}
}
fn wake(ptr: *const u32, max_waiters: u32) void {
if (max_waiters == 0) return;
const bucket = bucketForAddress(@intFromPtr(ptr));
// 为确保向 `ptr` 的存储排在此检查之前,实际上需要 `.release`
// 加载,但 C11 内存模型没有此操作,因此使用不修改值的读改写操作模拟。
if (bucket.num_waiters.fetchAdd(0, .release) == 0) {
@branchHint(.likely);
return; // 没有等待者
}
// 在互斥锁保护下从链表移除的等待者,以便在临界区之外唤回其线程。
// 使用 `Waiter.node.next` 将它们组织成单向链表。
var waking_head: ?*std.DoublyLinkedList.Node = null;
{
bucket.mutex.lock();
defer bucket.mutex.unlock();
var num_removed: u32 = 0;
var it = bucket.waiters.first;
while (num_removed < max_waiters) {
const waiter: *Waiter = @fieldParentPtr("node", it orelse break);
it = waiter.node.next;
if (waiter.address != @intFromPtr(ptr)) continue;
const old_status = waiter.thread_status.fetchAnd(
.{ .cancelation = @fromBackingInt(@intCast(0b110)), .awaitable = .all_ones },
.monotonic,
);
switch (old_status.cancelation) {
.parked => {}, // 状态已更新为 `.none`
.none => continue, // 与超时操作发生竞态;对方即将锁定 `bucket.mutex` 并将自身从桶中移除。
.canceling => continue, // 与尚未调用 `removeCanceledWaiter` 的取消方发生竞争
.canceled => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
}
// 将要唤醒此等待者。将其从桶中移除,并加入本地列表。
bucket.waiters.remove(&waiter.node);
waiter.node.next = waking_head;
waking_head = &waiter.node;
num_removed += 1;
}
_ = bucket.num_waiters.fetchSub(num_removed, .monotonic);
}
var unpark_buf: [128]UnparkTid = undefined;
var unpark_len: usize = 0;
// 最后,唤醒被挂起的线程。
while (waking_head) |node| {
waking_head = node.next;
const waiter: *Waiter = @fieldParentPtr("node", node);
unpark_buf[unpark_len] = waiter.tid;
if (need_unpark_flag) setUnparkFlag(waiter.unpark_flag);
unpark_len += 1;
if (unpark_len == unpark_buf.len) {
unpark(&unpark_buf, ptr);
unpark_len = 0;
}
}
if (unpark_len > 0) {
unpark(unpark_buf[0..unpark_len], ptr);
}
}
fn removeCanceledWaiter(waiter: *Waiter) void {
const bucket = bucketForAddress(waiter.address);
bucket.mutex.lock();
defer bucket.mutex.unlock();
bucket.waiters.remove(&waiter.node);
assert(bucket.num_waiters.fetchSub(1, .monotonic) > 0);
}
};
const parking_sleep = struct {
comptime {
assert(use_parking_sleep);
}
fn sleep(timeout: Io.Timeout) Io.Cancelable!void {
const opt_thread = Thread.current;
cancelable: {
const thread = opt_thread orelse break :cancelable;
switch (thread.cancel_protection) {
.blocked => break :cancelable,
.unblocked => {},
}
thread.futex_waiter = null;
{
const old_status = thread.status.fetchOr(
.{ .cancelation = @fromBackingInt(@intCast(0b001)), .awaitable = .null },
.release, // 释放 `thread.futex_waiter`
);
switch (old_status.cancelation) {
.none => {}, // 状态现在为 `.parked`
.canceling => return error.Canceled, // 状态现在为 `.canceled`
.canceled => break :cancelable, // 状态仍为 `.canceled`
.parked => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_alertable_canceling => unreachable,
.blocked_canceling => unreachable,
}
}
if (park(timeout, null, if (need_unpark_flag) &thread.unpark_flag)) {
// 唯一可能导致此情况的原因是取消。
const old_status = thread.status.load(.monotonic);
assert(old_status.cancelation == .canceling);
thread.status.store(
.{ .cancelation = .canceled, .awaitable = old_status.awaitable },
.monotonic,
);
return error.Canceled;
} else |err| switch (err) {
error.Timeout => {
// 问题尚未解决:取消停驻操作可能与超时发生竞态。
const old_status = thread.status.fetchAnd(
.{ .cancelation = @fromBackingInt(@intCast(0b110)), .awaitable = .all_ones },
.monotonic,
);
switch (old_status.cancelation) {
.parked => return, // 无竞态条件;新状态为 `.none`
.canceling => {
// 竞态条件:先达到超时期限,随后其他线程尝试因取消而唤回
// 当前线程。该线程会调用 `unpark`,因此
// 通过等待来消费此唤回请求。
// 状态仍为 `.canceling`。
park(.none, null, if (need_unpark_flag) &thread.unpark_flag) catch |e| switch (e) {
error.Timeout => unreachable,
};
return;
},
.none => unreachable,
.canceled => unreachable,
.blocked => unreachable,
.blocked_alertable => unreachable,
.blocked_canceling => unreachable,
.blocked_alertable_canceling => unreachable,
}
},
}
}
// 不可取消的休眠;预期不会被手动取消停驻。
// 在停驻线程需要一次性设置操作(例如创建信号量)的系统上,
// 必须确保在调用 `park` 之前完成该设置。
_ = getParkTid();
var dummy_flag: UnparkFlag = unpark_flag_init;
if (park(timeout, null, if (need_unpark_flag) &dummy_flag)) {
unreachable; // 意外的 unpark
} else |err| switch (err) {
error.Timeout => return,
}
}
};
const ParkingMutex = struct {
state: std.atomic.Value(State),
const init: ParkingMutex = .{ .state = .init(.unlocked) };
comptime {
assert(use_parking_futex);
}
const State = enum(usize) {
unlocked = 1,
/// 此值有意设为 0,以使 `waiter` 返回 `null`。
locked_once = 0,
/// 存在竞争;值为 `*Waiter`。
_,
/// 返回等待者链表的头部。`s == .unlocked` 时调用属于非法操作。
fn waiter(s: State) ?*Waiter {
return @ptrFromInt(@backingInt(s));
}
/// 返回 `w` 正在竞争锁的锁定状态。
/// 若 `w` 为 `null`,则返回 `.locked_once`。
fn fromWaiter(w: ?*Waiter) State {
return @fromBackingInt(@intCast(@intFromPtr(w)));
}
};
const Waiter = struct {
unpark_flag: UnparkFlag,
/// `Waiter` 加入链表之后,此值不再修改。
next: ?*Waiter,
/// `Waiter` 加入链表之后,此值不再修改。
tid: ParkTid,
};
fn lock(m: *ParkingMutex) void {
state: switch (State.unlocked) { // 假定为 'unlocked',以优化无竞争情况。
.unlocked => continue :state m.state.cmpxchgWeak(
.unlocked,
.locked_once,
.acquire, // 获取锁
.monotonic,
) orelse {
@branchHint(.likely);
return;
},
.locked_once, _ => |last_state| {
const old_waiter = last_state.waiter();
const self_tid = getParkTid();
var waiter: Waiter = .{
.next = old_waiter,
.unpark_flag = unpark_flag_init,
.tid = self_tid,
};
if (m.state.cmpxchgWeak(
.fromWaiter(old_waiter),
.fromWaiter(&waiter),
.release, // 释放 `waiter`
.monotonic,
)) |new_state| {
continue :state new_state;
}
// 现已进入等待者列表——挂起,直到获得锁。
park(.none, m, if (need_unpark_flag) &waiter.unpark_flag) catch |err| switch (err) {
error.Timeout => unreachable,
};
return;
},
}
}
fn unlock(m: *ParkingMutex) void {
state: switch (State.locked_once) { // 假定为 'locked_once',以优化无竞争情况
.unlocked => unreachable, // 当前持有锁
.locked_once => continue :state m.state.cmpxchgWeak(
.locked_once,
.unlocked,
.release, // 释放锁
.acquire, // 获取任意 `Waiter` 的内存
) orelse {
@branchHint(.likely);
return;
},
_ => |last_state| {
// 此处逻辑不存在 ABA 问题,并且有些访问不是原子操作,
// 因为等待者进入链表后,`Waiter.next` 就由持锁者(即当前线程)拥有,
// 直到我们唤醒该等待者为止。
// 遍历等待者列表直到末尾,以确保公平性。这显然并不
// 理想,但只要临界区足够小,实际影响应当不大
// (这样就不会有过多线程同时争用互斥锁)。
// 此使用场景*可能*允许使用后进先出队列,但
// 这里不冒这个风险。
var parent: ?*Waiter = null;
var waiter: *Waiter = last_state.waiter().?;
while (waiter.next) |next| {
parent = waiter;
waiter = next;
}
// `waiter` 是下一个将获得锁的等待者。将其从列表移除。
if (parent) |p| {
assert(p.next == waiter);
p.next = null;
} else {
// 正在唤醒最后一个等待者,因此清空链表头。
if (m.state.cmpxchgWeak(
.fromWaiter(last_state.waiter().?),
.locked_once,
.acquire,
.acquire, // 获取新的 `Waiter` 内存
)) |new_state| {
continue :state new_state;
}
}
// 现在可以真正将锁交给它们。
const tid = waiter.tid; // 在下方可能使 `waiter` 失效的取消停驻操作之前加载。
if (need_unpark_flag) setUnparkFlag(&waiter.unpark_flag);
unpark(&.{tid}, m);
return;
},
}
}
};
fn timeoutToWindowsInterval(timeout: Io.Timeout) ?windows.LARGE_INTEGER {
// ntdll 只支持两种组合:
// * 使用绝对截止时间的实时时钟(`.real`)睡眠
// * 使用相对时长的单调时钟(`.awake`/`.boot`)睡眠
const clock = switch (timeout) {
.none => return null,
.duration => |d| d.clock,
.deadline => |d| d.clock,
};
switch (clock) {
.cpu_process, .cpu_thread => unreachable, // 不能因 CPU 时间而休眠
.real => {
const deadline = switch (timeout) {
.none => unreachable,
.duration => |d| nowWindows(clock).addDuration(d.raw),
.deadline => |d| d.raw,
};
const epoch_ns = std.time.epoch.windows * std.time.ns_per_s;
return @intCast(@max(@divTrunc(deadline.nanoseconds - epoch_ns, 100), 0));
},
.awake, .boot => {
const duration = switch (timeout) {
.none => unreachable,
.duration => |d| d.raw,
.deadline => |d| nowWindows(clock).durationTo(d.raw),
};
return @intCast(@min(@divTrunc(-duration.nanoseconds, 100), -1));
},
}
}
/// NetBSD 和 Illumos 上的接口存在问题,可能产生虚假的解除停放。严格来说,接口本身不会如此,但信号引起的解除阻塞无法与之区分,而 libpthread 经常留下待处理的解除停放操作。
/// 因此,仅在这些目标上,需要传递一个标志,跟踪线程是否“确实”被解除停放。
///
///
const need_unpark_flag = switch (native_os) {
.netbsd, .illumos => true,
else => false,
};
const UnparkFlag = if (need_unpark_flag) std.atomic.Value(bool) else void;
const unpark_flag_init: UnparkFlag = if (need_unpark_flag) .init(false);
/// 必须在 `unpark` 前调用。调用后,线程随时可能被解除停驻,
/// 因此调用者不得引用该线程栈上的值。
fn setUnparkFlag(f: *UnparkFlag) void {
f.store(true, .release);
}
/// 传入 `unpark` 的线程标识类型。直觉上它应是 `std.Thread.Id`,
/// 但 Microsoft 的实现似乎未遵循自身线程标识的预期大小。
const UnparkTid = switch (native_os) {
.windows => usize,
else => ParkTid,
};
const ParkTid = switch (native_os) {
.haiku => std.c.sem_id,
else => std.Thread.Id,
};
threadlocal var park_sem: std.c.sem_id = -1;
fn getParkTid() ParkTid {
switch (native_os) {
.haiku => {
if (park_sem == -1) {
park_sem = std.c._kern_create_sem(0, null);
if (park_sem < 0) @panic("_kern_create_sem failed");
_ = std.c.on_exit_thread(destroyParkSem, null);
}
return park_sem;
},
else => {
return if (Thread.current) |thread| thread.id else std.Thread.getCurrentId();
},
}
}
fn destroyParkSem(_: ?*anyopaque) callconv(.c) void {
_ = std.c._kern_delete_sem(park_sem);
}
fn park(
timeout: Io.Timeout,
/// 此值不影响语义,但可能允许操作系统优化该操作。
addr_hint: ?*const anyopaque,
unpark_flag: if (need_unpark_flag) *UnparkFlag else void,
) error{Timeout}!void {
comptime assert(use_parking_futex or use_parking_sleep);
switch (native_os) {
.windows => {
const raw_timeout = timeoutToWindowsInterval(timeout);
// `RtlWaitOnAddress` 将 futex 地址作为此调用的第一个参数传入,但其实际作用尚不明确,尤其是 `NtAlertThreadByThreadId` 不接受该地址,因此内核实际上无法将其作为提示使用。微软一篇旧博客讨论了内核中更传统的类似 futex 的机制,但那显然不是当今 `RtlWaitOnAddress` 的工作方式:
//
// https://devblogs.microsoft.com/oldnewthing/20160826-00/?p=94185
//
// ……因此,这个参数可能只是已经失去作用的遗留参数,也许实现曾在开发期间改变,却忘记移除参数。不过,为谨慎起见,仍应与 `RtlWaitOnAddress` 的行为一致并传入该指针,以防内核尝试解引用它等不当操作。
//
//
//
//
//
//
//
//
switch (windows.ntdll.NtWaitForAlertByThreadId(
addr_hint,
if (raw_timeout) |*t| t else null,
)) {
.ALERTED => return,
.TIMEOUT => return error.Timeout,
else => unreachable,
}
},
.netbsd => {
var ts_buf: posix.timespec = undefined;
const ts: ?*posix.timespec, const abstime: bool, const clock_real: bool = switch (timeout) {
.none => .{ null, false, false },
.deadline => |timestamp| timeout: {
ts_buf = timestampToPosix(timestamp.raw.nanoseconds);
break :timeout .{ &ts_buf, true, timestamp.clock == .real };
},
.duration => |duration| timeout: {
ts_buf = timestampToPosix(duration.raw.nanoseconds);
break :timeout .{ &ts_buf, false, duration.clock == .real };
},
};
// 可在循环中传入同一个超时值。若它是相对时长,操作系统会在系统调用返回时将剩余时间写入缓冲区。
//
while (!unpark_flag.swap(false, .acquire)) {
switch (posix.errno(std.c._lwp_park(
if (clock_real) .REALTIME else .MONOTONIC,
.{ .ABSTIME = abstime },
ts,
0,
addr_hint,
null,
))) {
.SUCCESS, .ALREADY, .INTR => {},
.TIMEDOUT => return error.Timeout,
.INVAL => unreachable,
.SRCH => unreachable,
else => unreachable,
}
}
},
.illumos => @panic("TODO: illumos lwp_park"),
.haiku => {
const timeout_flags: u32, const timeout_us = switch (timeout) {
.none => .{ 0, 0 },
.deadline => |deadline| .{
if (deadline.clock == .real) std.c.B_ABSOLUTE_TIMEOUT | std.c.B_TIMEOUT_REAL_TIME_BASE else std.c.B_ABSOLUTE_TIMEOUT,
deadline.raw.toMicroseconds(),
},
.duration => |duration| .{
if (duration.clock == .real) std.c.B_ABSOLUTE_TIMEOUT | std.c.B_TIMEOUT_REAL_TIME_BASE else std.c.B_ABSOLUTE_TIMEOUT,
nowPosix(duration.clock).addDuration(duration.raw).toMicroseconds(),
},
};
while (true) {
switch (std.c._kern_acquire_sem_etc(park_sem, 1, timeout_flags, timeout_us)) {
0 => return,
std.c.E.B_TIMED_OUT => return error.Timeout,
std.c.E.B_INTERRUPTED => {},
else => unreachable,
}
}
},
else => comptime unreachable,
}
}
/// `addr_hint` 不影响语义,但可能使操作系统能够优化此操作。
fn unpark(tids: []const UnparkTid, addr_hint: ?*const anyopaque) void {
comptime assert(use_parking_futex or use_parking_sleep);
switch (native_os) {
.windows => {
// TODO: 目前禁用此条件,因为 mingw-w64 不包含此
// 符号。添加后,应启用此检查,尽可能使用新的批量接口。
if (false and (builtin.os.version_range.windows.isAtLeast(.win11_dt) orelse false)) {
_ = windows.ntdll.NtAlertMultipleThreadByThreadId(tids.ptr, @intCast(tids.len), null, null);
} else {
for (tids) |tid| {
_ = windows.ntdll.NtAlertThreadByThreadId(@intCast(tid));
}
}
},
.netbsd => {
switch (posix.errno(std.c._lwp_unpark_all(@ptrCast(tids.ptr), tids.len, addr_hint))) {
.SUCCESS => return,
// 发生错误时,继续执行遍历 `tids` 的循环;但预计只有
// ENOMEM(甚至这点也存疑)和 ESRCH(见下方注释)可能出现。
.SRCH => {},
.FAULT => recoverableOsBugDetected(),
.INVAL => recoverableOsBugDetected(),
.NOMEM => {},
else => recoverableOsBugDetected(),
}
for (tids) |tid| {
switch (posix.errno(std.c._lwp_unpark(@bitCast(tid), addr_hint))) {
.SUCCESS => {},
.SRCH => {
// 这可能发生在罕见的竞态中:线程可能被伪唤醒,
// 因而已观察到状态变化,随后
// 退出。这没有问题,因为线程已按预期醒来。
},
else => recoverableOsBugDetected(),
}
}
},
.illumos => @panic("TODO: illumos lwp_unpark"),
.haiku => {
for (tids) |tid| {
switch (std.c._kern_release_sem_etc(tid, 1, 0)) {
0 => {},
else => recoverableOsBugDetected(),
}
}
},
else => comptime unreachable,
}
}
pub const PipeError = error{
SystemFdQuotaExceeded,
ProcessFdQuotaExceeded,
} || Io.UnexpectedError;
pub fn pipe2(flags: posix.O) PipeError![2]posix.fd_t {
var fds: [2]posix.fd_t = undefined;
if (@TypeOf(posix.system.pipe2) != void) {
switch (posix.errno(posix.system.pipe2(&fds, flags))) {
.SUCCESS => return fds,
.INVAL => |err| return errnoBug(err), // 无效的标志
.NFILE => return error.SystemFdQuotaExceeded,
.MFILE => return error.ProcessFdQuotaExceeded,
else => |err| return posix.unexpectedErrno(err),
}
}
switch (posix.errno(posix.system.pipe(&fds))) {
.SUCCESS => {},
.NFILE => return error.SystemFdQuotaExceeded,
.MFILE => return error.ProcessFdQuotaExceeded,
else => |err| return posix.unexpectedErrno(err),
}
errdefer {
closeFd(fds[0]);
closeFd(fds[1]);
}
// https://github.com/ziglang/zig/issues/18882
if (@as(u32, @bitCast(flags)) == 0) return fds;
// CLOEXEC 特殊:它是文件描述符标志,必须使用 F.SETFD 设置。
//
if (flags.CLOEXEC) for (fds) |fd| {
switch (posix.errno(posix.system.fcntl(fd, posix.F.SETFD, @as(u32, posix.FD_CLOEXEC)))) {
.SUCCESS => {},
else => |err| return posix.unexpectedErrno(err),
}
};
const new_flags: u32 = f: {
var new_flags = flags;
new_flags.CLOEXEC = false;
break :f @bitCast(new_flags);
};
// 使用 F.SETFL 设置其他影响文件状态的所有标志。
if (new_flags != 0) for (fds) |fd| {
switch (posix.errno(posix.system.fcntl(fd, posix.F.SETFL, new_flags))) {
.SUCCESS => {},
.INVAL => |err| return errnoBug(err),
else => |err| return posix.unexpectedErrno(err),
}
};
return fds;
}
pub const DupError = error{
ProcessFdQuotaExceeded,
SystemResources,
} || Io.UnexpectedError || Io.Cancelable;
pub fn dup2(old_fd: posix.fd_t, new_fd: posix.fd_t) DupError!void {
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.dup2(old_fd, new_fd))) {
.SUCCESS => return syscall.finish(),
.BUSY, .INTR => {
try syscall.checkCancel();
continue;
},
.INVAL => |err| return syscall.errnoBug(err), // 无效参数
.BADF => |err| return syscall.errnoBug(err), // 释放后使用
.MFILE => return syscall.fail(error.ProcessFdQuotaExceeded),
.NOMEM => return syscall.fail(error.SystemResources),
else => |err| return syscall.unexpectedErrno(err),
};
}
pub const FchdirError = error{
AccessDenied,
NotDir,
FileSystem,
} || Io.Cancelable || Io.UnexpectedError;
pub fn fchdir(fd: posix.fd_t) FchdirError!void {
if (fd == posix.AT.FDCWD) return;
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.fchdir(fd))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.NOTDIR => return syscall.fail(error.NotDir),
.IO => return syscall.fail(error.FileSystem),
.BADF => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
};
}
pub const ChdirError = error{
AccessDenied,
FileSystem,
SymLinkLoop,
NameTooLong,
FileNotFound,
SystemResources,
NotDir,
BadPathName,
} || Io.Cancelable || Io.UnexpectedError;
pub fn chdir(dir_path: []const u8) ChdirError!void {
var path_buffer: [posix.PATH_MAX]u8 = undefined;
const dir_path_posix = try pathToPosix(dir_path, &path_buffer);
const syscall: Syscall = try .start();
while (true) switch (posix.errno(posix.system.chdir(dir_path_posix))) {
.SUCCESS => return syscall.finish(),
.INTR => {
try syscall.checkCancel();
continue;
},
.ACCES => return syscall.fail(error.AccessDenied),
.IO => return syscall.fail(error.FileSystem),
.LOOP => return syscall.fail(error.SymLinkLoop),
.NAMETOOLONG => return syscall.fail(error.NameTooLong),
.NOENT => return syscall.fail(error.FileNotFound),
.NOMEM => return syscall.fail(error.SystemResources),
.NOTDIR => return syscall.fail(error.NotDir),
.ILSEQ => return syscall.fail(error.BadPathName),
.FAULT => |err| return syscall.errnoBug(err),
else => |err| return syscall.unexpectedErrno(err),
};
}
fn fileMemoryMapCreate(
userdata: ?*anyopaque,
file: File,
options: File.MemoryMap.CreateOptions,
) File.MemoryMap.CreateError!File.MemoryMap {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const offset = options.offset;
const len = options.len;
if (!t.disable_memory_mapping) {
if (createFileMap(file, options.protection, offset, options.populate, len)) |result| {
return result;
} else |err| switch (err) {
error.Unseekable, error.Canceled, error.AccessDenied => |e| return e,
error.OperationUnsupported => {},
else => {
if (builtin.mode == .debug)
std.log.warn("memory mapping failed with {t}, falling back to file operations", .{err});
},
}
}
const gpa = t.allocator;
const page_size = std.heap.pageSize();
const alignment: Alignment = .fromByteUnits(page_size);
const memory = m: {
const ptr = gpa.rawAlloc(len, alignment, @returnAddress()) orelse return error.OutOfMemory;
break :m ptr[0..len];
};
errdefer gpa.rawFree(memory, alignment, @returnAddress());
if (!options.undefined_contents) try mmSyncRead(file, memory, offset);
return .{
.file = file,
.offset = offset,
.memory = @alignCast(memory),
.section = null,
};
}
const CreateFileMapError = error{
/// MaximumSize 大于系统定义的节大小上限,或
/// 大于指定文件的大小且该节不可写。
SectionOversize,
/// 文件描述符引用非普通文件;或请求文件映射,
/// 但文件描述符未以读取方式打开;或请求 `MAP.SHARED`
/// 并设置 `PROT_WRITE`,但文件描述符未以 `RDWR` 模式打开;
/// 或设置 `PROT_WRITE`,但文件仅允许追加。
AccessDenied,
/// `prot` 参数请求 `PROT_EXEC`,但映射区域属于
/// 挂载为禁止执行的文件系统中的文件。
PermissionDenied,
FileBusy,
LockedMemoryLimitExceeded,
OperationUnsupported,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
OutOfMemory,
MappingAlreadyExists,
Unseekable,
LockViolation,
} || Io.Cancelable || Io.UnexpectedError;
fn createFileMap(
file: File,
protection: process.MemoryProtection,
offset: u64,
populate: bool,
len: usize,
) CreateFileMapError!File.MemoryMap {
if (is_windows) {
try Thread.checkCancel();
var section = windows.INVALID_HANDLE_VALUE;
const section_size: windows.LARGE_INTEGER = @intCast(len);
const page = windows.PAGE.fromProtection(protection) orelse return error.AccessDenied;
switch (windows.ntdll.NtCreateSection(
§ion,
.{
.SPECIFIC = .{ .SECTION = .{
.QUERY = true,
.MAP_WRITE = protection.write,
.MAP_READ = protection.read,
.MAP_EXECUTE = protection.execute,
.EXTEND_SIZE = true,
} },
.STANDARD = .{ .RIGHTS = .REQUIRED },
},
null,
§ion_size,
page,
.{
// 使用文件句柄调用 NtCreateSection 时必须设置此位,否则
// 该调用会以 INVALID_PARAMETER_6 失败。较高层的
// `CreateFileMapping` 函数在调用 NtCreateSection 时会为你设置此位。
//
.COMMIT = true,
},
file.handle,
)) {
.SUCCESS => {},
.FILE_LOCK_CONFLICT => return error.LockViolation,
.INVALID_FILE_FOR_SECTION => return error.OperationUnsupported,
.ACCESS_DENIED => return error.AccessDenied,
.SECTION_TOO_BIG => return error.SectionOversize,
else => |status| return windows.unexpectedStatus(status),
}
var contents_ptr: ?[*]align(std.heap.page_size_min) u8 = null;
var contents_len = len;
switch (windows.ntdll.NtMapViewOfSection(
section,
windows.current_process,
@ptrCast(&contents_ptr),
null,
0,
null,
&contents_len,
.Unmap,
.{},
page,
)) {
.SUCCESS => {},
.CONFLICTING_ADDRESSES => return error.MappingAlreadyExists,
.SECTION_PROTECTION => return error.PermissionDenied,
.ACCESS_DENIED => return error.AccessDenied,
.INVALID_VIEW_SIZE => |status| return windows.statusBug(status),
else => |status| return windows.unexpectedStatus(status),
}
if (builtin.mode == .debug) {
const page_size = std.heap.pageSize();
const alignment: Alignment = .fromByteUnits(page_size);
assert(contents_len == alignment.forward(len));
}
if (populate) {
const addresses = [_]windows.MEMORY_RANGE_ENTRY{
.{ .VirtualAddress = contents_ptr.?, .NumberOfBytes = len },
};
var info: windows.VIRTUAL_MEMORY.MEMORY_PREFETCH_INFORMATION = .{
.Flags = .{
// 此标志要求 Windows 11 >= 24H4。在较早版本上设置它,
// 会导致 NtSetInformationVirtualMemory 以 INVALID_PARAMETER_5 失败。
.TO_WORKING_SET = false,
},
};
// 此函数的有效性曾受到质疑:
// https://github.com/microsoft/Windows-Dev-Performance/issues/108
//
// 但测试表明,若映射文件不在
// 缓存中,调用此函数可将原本可能发生的硬
// 缺页变为软缺页。不论如何,调用它仍有助于
// 准确表达意图。
switch (windows.ntdll.NtSetInformationVirtualMemory(
windows.current_process,
.Prefetch,
1,
&addresses,
&info,
@sizeOf(windows.VIRTUAL_MEMORY.MEMORY_PREFETCH_INFORMATION),
)) {
.SUCCESS => {},
else => |status| return windows.unexpectedStatus(status),
}
}
return .{
.file = file,
.offset = offset,
.memory = contents_ptr.?[0..len],
.section = section,
};
} else if (have_mmap) {
const prot: posix.PROT = .{
.READ = protection.read,
.WRITE = protection.write,
.EXEC = protection.execute,
};
const flags: posix.MAP = switch (native_os) {
.linux => .{
.TYPE = .SHARED_VALIDATE,
.POPULATE = populate,
},
else => .{
.TYPE = .SHARED,
},
};
const page_align = std.heap.page_size_min;
const contents = while (true) {
const syscall: Syscall = try .start();
const casted_offset = std.math.cast(i64, offset) orelse return error.Unseekable;
const rc = mmap_sym(null, len, prot, flags, file.handle, casted_offset);
syscall.finish();
const err: posix.E = if (builtin.link_libc) e: {
if (rc != std.c.MAP_FAILED) {
break @as([*]align(page_align) u8, @ptrCast(@alignCast(rc)))[0..len];
}
break :e @fromBackingInt(@intCast(posix.system._errno().*));
} else e: {
const err = posix.errno(rc);
if (err == .SUCCESS) {
break @as([*]align(page_align) u8, @ptrFromInt(rc))[0..len];
}
break :e err;
};
switch (err) {
.SUCCESS => unreachable,
.INTR => continue,
.ACCES => return error.AccessDenied,
.AGAIN => return error.LockedMemoryLimitExceeded,
.EXIST => return error.MappingAlreadyExists,
.MFILE => return error.ProcessFdQuotaExceeded,
.NFILE => return error.SystemFdQuotaExceeded,
.NODEV => return error.OperationUnsupported,
.NOMEM => return error.OutOfMemory,
.PERM => return error.PermissionDenied,
.TXTBSY => return error.FileBusy,
.OVERFLOW => return error.Unseekable,
.BADF => return errnoBug(err), // 始终存在竞态条件。
.INVAL => return errnoBug(err), // mmap() 的参数无效
.OPNOTSUPP => return errnoBug(err), // 在 Linux 上与 MAP.SHARED_VALIDATE 一起使用了无效标志。
else => return posix.unexpectedErrno(err),
}
};
return .{
.file = file,
.offset = offset,
.memory = contents,
.section = {},
};
}
return error.OperationUnsupported;
}
fn fileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const memory = mm.memory;
if (mm.section) |section| switch (native_os) {
.windows => {
if (section == windows.INVALID_HANDLE_VALUE) return;
_ = windows.ntdll.NtUnmapViewOfSection(windows.current_process, memory.ptr);
windows.CloseHandle(section);
},
.wasi => unreachable,
else => {
if (memory.len == 0) return;
switch (posix.errno(posix.system.munmap(memory.ptr, memory.len))) {
.SUCCESS => {},
else => |e| {
if (builtin.mode == .debug)
std.log.err("failed to unmap {d} bytes at {*}: {t}", .{ memory.len, memory.ptr, e });
},
}
},
} else {
const gpa = t.allocator;
gpa.rawFree(memory, .fromByteUnits(std.heap.pageSize()), @returnAddress());
}
mm.* = undefined;
}
fn fileMemoryMapSetLength(
userdata: ?*anyopaque,
mm: *File.MemoryMap,
new_len: usize,
) File.MemoryMap.SetLengthError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
const page_size = std.heap.pageSize();
const alignment: Alignment = .fromByteUnits(page_size);
const page_align = std.heap.page_size_min;
const old_memory = mm.memory;
if (mm.section) |section| {
_ = section;
if (alignment.forward(new_len) == alignment.forward(old_memory.len)) {
mm.memory.len = new_len;
return;
}
switch (native_os) {
.wasi => unreachable,
.linux => {
const flags: posix.MREMAP = .{ .MAYMOVE = true };
const addr_hint: ?[*]const u8 = null;
const new_memory = while (true) {
const syscall: Syscall = try .start();
const rc = posix.system.mremap(old_memory.ptr, old_memory.len, new_len, flags, addr_hint);
syscall.finish();
const err: posix.E = if (builtin.link_libc) e: {
if (rc != std.c.MAP_FAILED) break @as([*]align(page_align) u8, @ptrCast(@alignCast(rc)))[0..new_len];
break :e @fromBackingInt(@intCast(posix.system._errno().*));
} else e: {
const err = posix.errno(rc);
if (err == .SUCCESS) break @as([*]align(page_align) u8, @ptrFromInt(rc))[0..new_len];
break :e err;
};
switch (err) {
.SUCCESS => unreachable,
.INTR => continue,
.AGAIN => return error.LockedMemoryLimitExceeded,
.NOMEM => return error.OutOfMemory,
.INVAL => return errnoBug(err),
.FAULT => return errnoBug(err),
else => return posix.unexpectedErrno(err),
}
};
mm.memory = new_memory;
return;
},
else => return error.OperationUnsupported,
}
} else {
const gpa = t.allocator;
if (gpa.rawRemap(old_memory, alignment, new_len, @returnAddress())) |new_ptr| {
mm.memory = @alignCast(new_ptr[0..new_len]);
} else {
const new_ptr: [*]align(page_align) u8 = @alignCast(
gpa.rawAlloc(new_len, alignment, @returnAddress()) orelse return error.OutOfMemory,
);
const copy_len = @min(new_len, old_memory.len);
@memcpy(new_ptr[0..copy_len], old_memory[0..copy_len]);
mm.memory = new_ptr[0..new_len];
gpa.rawFree(old_memory, alignment, @returnAddress());
}
}
}
fn fileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const section = mm.section orelse return mmSyncRead(mm.file, mm.memory, mm.offset);
_ = section;
}
fn fileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void {
const t: *Threaded = @ptrCast(@alignCast(userdata));
_ = t;
const section = mm.section orelse return mmSyncWrite(mm.file, mm.memory, mm.offset);
_ = section;
}
fn mmSyncRead(file: File, memory: []u8, offset: u64) File.ReadPositionalError!void {
if (is_windows) {
var i: usize = 0;
while (true) {
const buf = memory[i..];
if (buf.len == 0) break;
const n = try readFilePositionalWindows(file, buf, offset + i);
if (n == 0) {
@memset(memory[i..], 0);
break;
}
i += n;
}
} else if (native_os == .wasi and !builtin.link_libc) {
var i: usize = 0;
const syscall: Syscall = try .start();
while (true) {
const buf = memory[i..];
if (buf.len == 0) {
syscall.finish();
break;
}
var n: usize = undefined;
const vec: std.os.wasi.iovec_t = .{ .base = buf.ptr, .len = buf.len };
switch (std.os.wasi.fd_pread(file.handle, (&vec)[0..1], 1, offset + i, &n)) {
.SUCCESS => {
if (n == 0) {
syscall.finish();
@memset(memory[i..], 0);
break;
}
i += n;
try syscall.checkCancel();
continue;
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.NOTCONN => |err| return syscall.errnoBug(err), // 不是套接字
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字
.BADF => |err| return syscall.errnoBug(err), // 释放后使用
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err), // 段错误
.AGAIN => |err| return syscall.errnoBug(err),
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
.NOTCAPABLE => return syscall.fail(error.AccessDenied),
else => |err| return syscall.unexpectedErrno(err),
}
}
} else {
var i: usize = 0;
const syscall: Syscall = try .start();
while (true) {
const buf = memory[i..];
if (buf.len == 0) {
syscall.finish();
break;
}
const rc = pread_sym(file.handle, buf.ptr, buf.len, @intCast(offset + i));
switch (posix.errno(rc)) {
.SUCCESS => {
const n: usize = @intCast(rc);
if (n == 0) {
syscall.finish();
@memset(memory[i..], 0);
break;
}
i += n;
try syscall.checkCancel();
continue;
},
.INTR, .TIMEDOUT => {
try syscall.checkCancel();
continue;
},
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
.NOBUFS => return syscall.fail(error.SystemResources),
.NOMEM => return syscall.fail(error.SystemResources),
.AGAIN => return syscall.fail(error.WouldBlock),
.IO => return syscall.fail(error.InputOutput),
.ISDIR => return syscall.fail(error.IsDir),
.NOTCONN => |err| return syscall.errnoBug(err), // 不是套接字
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.BADF => |err| return syscall.errnoBug(err), // 释放后使用
else => |err| return syscall.unexpectedErrno(err),
}
}
}
}
fn mmSyncWrite(file: File, memory: []u8, offset: u64) File.WritePositionalError!void {
if (is_windows) {
var i: usize = 0;
while (true) {
const buf = memory[i..];
if (buf.len == 0) break;
i += try writeFilePositionalWindows(file, memory[i..], offset + i);
}
} else if (native_os == .wasi and !builtin.link_libc) {
var i: usize = 0;
var n: usize = undefined;
const syscall: Syscall = try .start();
while (true) {
const buf = memory[i..];
if (buf.len == 0) {
syscall.finish();
break;
}
const iovec: std.os.wasi.ciovec_t = .{ .base = buf.ptr, .len = buf.len };
switch (std.os.wasi.fd_pwrite(file.handle, (&iovec)[0..1], 1, offset + i, &n)) {
.SUCCESS => {
i += n;
try syscall.checkCancel();
continue;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.DQUOT => return syscall.fail(error.DiskQuota),
.FBIG => return syscall.fail(error.FileTooBig),
.IO => return syscall.fail(error.InputOutput),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.PERM => return syscall.fail(error.PermissionDenied),
.PIPE => return syscall.fail(error.BrokenPipe),
.NOTCAPABLE => return syscall.fail(error.AccessDenied),
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.AGAIN => |err| return syscall.errnoBug(err),
.BADF => |err| return syscall.errnoBug(err), // 释放后使用
.DESTADDRREQ => |err| return syscall.errnoBug(err), // 不是套接字
else => |err| return syscall.unexpectedErrno(err),
}
}
} else {
var i: usize = 0;
const syscall: Syscall = try .start();
while (true) {
const buf = memory[i..];
if (buf.len == 0) {
syscall.finish();
break;
}
const rc = pwrite_sym(file.handle, buf.ptr, buf.len, @intCast(offset + i));
switch (posix.errno(rc)) {
.SUCCESS => {
const n: usize = @bitCast(rc);
i += n;
try syscall.checkCancel();
continue;
},
.INTR => {
try syscall.checkCancel();
continue;
},
.INVAL => |err| return syscall.errnoBug(err),
.FAULT => |err| return syscall.errnoBug(err),
.DESTADDRREQ => |err| return syscall.errnoBug(err), // 不是套接字
.CONNRESET => |err| return syscall.errnoBug(err), // 不是套接字
.BADF => return syscall.fail(error.NotOpenForWriting),
.AGAIN => return syscall.fail(error.WouldBlock),
.DQUOT => return syscall.fail(error.DiskQuota),
.FBIG => return syscall.fail(error.FileTooBig),
.IO => return syscall.fail(error.InputOutput),
.NOSPC => return syscall.fail(error.NoSpaceLeft),
.PERM => return syscall.fail(error.PermissionDenied),
.PIPE => return syscall.fail(error.BrokenPipe),
.BUSY => return syscall.fail(error.DeviceBusy),
.TXTBSY => return syscall.fail(error.FileBusy),
.NXIO => return syscall.fail(error.Unseekable),
.SPIPE => return syscall.fail(error.Unseekable),
.OVERFLOW => return syscall.fail(error.Unseekable),
else => |err| return syscall.unexpectedErrno(err),
}
}
}
}
fn deviceIoControl(o: *const Io.Operation.DeviceIoControl) Io.Cancelable!Io.Operation.DeviceIoControl.Result {
if (is_windows) {
const NtControlFile = switch (o.code.DeviceType) {
.FILE_SYSTEM, .NAMED_PIPE => &windows.ntdll.NtFsControlFile,
else => &windows.ntdll.NtDeviceIoControlFile,
};
var iosb: windows.IO_STATUS_BLOCK = undefined;
if (o.file.flags.nonblocking) {
var done: bool = false;
switch (NtControlFile(
o.file.handle,
null, // 事件
flagApc,
&done, // APC 上下文
&iosb,
o.code,
if (o.in.len > 0) o.in.ptr else null,
@intCast(o.in.len),
if (o.out.len > 0) o.out.ptr else null,
@intCast(o.out.len),
)) {
// 必须等待 APC 例程。
.PENDING, .SUCCESS => while (!done) {
// 一旦执行到这里,就必须等到操作完成后才可返回,从而释放对 io_status_block 的引用。
//
const alertable_syscall = AlertableSyscall.start() catch |err| switch (err) {
error.Canceled => |e| {
var cancel_iosb: windows.IO_STATUS_BLOCK = undefined;
_ = windows.ntdll.NtCancelIoFileEx(o.file.handle, &iosb, &cancel_iosb);
while (!done) waitForApcOrAlert();
return e;
},
};
waitForApcOrAlert();
alertable_syscall.finish();
},
else => |status| iosb.u.Status = status,
}
} else {
const syscall: Syscall = try .start();
while (true) switch (NtControlFile(
o.file.handle,
null, // 事件
null, // APC 例程
null, // APC 上下文
&iosb,
o.code,
if (o.in.len > 0) o.in.ptr else null,
@intCast(o.in.len),
if (o.out.len > 0) o.out.ptr else null,
@intCast(o.out.len),
)) {
.PENDING => unreachable, // 不可恢复:异步标志错误
.CANCELLED => {
try syscall.checkCancel();
continue;
},
else => |status| {
syscall.finish();
iosb.u.Status = status;
break;
},
};
}
return iosb;
} else {
const syscall: Syscall = try .start();
while (true) {
const rc = posix.system.ioctl(o.file.handle, @bitCast(o.code), @intFromPtr(o.arg));
switch (posix.errno(rc)) {
.SUCCESS => {
syscall.finish();
if (@TypeOf(rc) == usize) return @bitCast(@as(u32, @truncate(rc)));
return rc;
},
.INTR => {
try syscall.checkCancel();
continue;
},
else => |err| {
syscall.finish();
return -@as(i32, @backingInt(err));
},
}
}
}
}
const WaitGroup = struct {
state: std.atomic.Value(usize),
event: Io.Event,
const init: WaitGroup = .{ .state = .{ .raw = 0 }, .event = .unset };
const is_waiting: usize = 1 << 0;
const one_pending: usize = 1 << 1;
fn start(wg: *WaitGroup) void {
const prev_state = wg.state.fetchAdd(one_pending, .monotonic);
assert((prev_state / one_pending) < (std.math.maxInt(usize) / one_pending));
}
fn value(wg: *WaitGroup) usize {
return wg.state.load(.monotonic) / one_pending;
}
fn wait(wg: *WaitGroup) void {
const prev_state = wg.state.fetchAdd(is_waiting, .acquire);
assert(prev_state & is_waiting == 0);
if ((prev_state / one_pending) > 0) eventWait(&wg.event);
}
fn finish(wg: *WaitGroup) void {
const state = wg.state.fetchSub(one_pending, .acq_rel);
assert((state / one_pending) > 0);
if (state == (one_pending | is_waiting)) {
eventSet(&wg.event);
}
}
};
/// 与 `Io.Event.wait` 相同,但绕过虚函数表。
fn eventWait(event: *Io.Event) void {
if (@cmpxchgStrong(Io.Event, event, .unset, .waiting, .acquire, .acquire)) |prev| switch (prev) {
.unset => unreachable,
.waiting => {},
.is_set => return,
};
while (true) {
Thread.futexWaitUncancelable(@ptrCast(event), @backingInt(Io.Event.waiting), null);
switch (@atomicLoad(Io.Event, event, .acquire)) {
.unset => unreachable, // 在待处理的 `wait` 返回之前调用了 `reset`
.waiting => continue,
.is_set => return,
}
}
}
/// 与 `Io.Event.set` 相同,但绕过虚函数表。
fn eventSet(event: *Io.Event) void {
switch (@atomicRmw(Io.Event, event, .Xchg, .is_set, .release)) {
.unset, .is_set => {},
.waiting => Thread.futexWake(@ptrCast(event), std.math.maxInt(u32)),
}
}
/// 与 `Io.Condition.broadcast` 相同,但绕过虚函数表。
fn condBroadcast(cond: *Io.Condition) void {
var prev_state = cond.state.load(.monotonic);
while (prev_state.waiters > prev_state.signals) {
@branchHint(.unlikely);
prev_state = cond.state.cmpxchgWeak(prev_state, .{
.waiters = prev_state.waiters,
.signals = prev_state.waiters,
}, .release, .monotonic) orelse {
// 更新纪元值,以告知等待线程有新的信号。
// 注意,如果线程在观察纪元值与开始等待之间,*恰好*发生 (1<<32)-1 次唤醒,
// 等待线程就可能漏掉一次获取;但由于要求如此精确的
// 调用次数,发生概率极低。
_ = cond.epoch.fetchAdd(1, .release); // 使用 `.release`,确保排序在 `state` 更新之后
Thread.futexWake(&cond.epoch.raw, prev_state.waiters - prev_state.signals);
return;
};
}
}
/// 与 `Io.Condition.signal` 相同,但绕过虚函数表。
fn condSignal(cond: *Io.Condition) void {
var prev_state = cond.state.load(.monotonic);
while (prev_state.waiters > prev_state.signals) {
@branchHint(.unlikely);
prev_state = cond.state.cmpxchgWeak(prev_state, .{
.waiters = prev_state.waiters,
.signals = prev_state.signals + 1,
}, .release, .monotonic) orelse {
// 更新纪元值,以告知等待线程有新的信号。
// 注意,如果线程在观察纪元值与开始等待之间,*恰好*发生 (1<<32)-1 次唤醒,
// 等待线程就可能漏掉一次获取;但由于要求如此精确的
// 调用次数,发生概率极低。
_ = cond.epoch.fetchAdd(1, .release); // 使用 `.release`,确保排序在 `state` 更新之后
Thread.futexWake(&cond.epoch.raw, 1);
return;
};
}
}
/// 与 `Io.Condition.waitUncancelable` 相同,但绕过虚函数表。
fn condWait(cond: *Io.Condition, mutex: *Io.Mutex) void {
var epoch = cond.epoch.load(.acquire); // 使用 `.acquire`,确保排序在状态加载之前。
{
const prev_state = cond.state.fetchAdd(.{ .waiters = 1, .signals = 0 }, .monotonic);
assert(prev_state.waiters < std.math.maxInt(u16)); // 等待方过多导致溢出
}
mutexUnlock(mutex);
defer mutexLockUncancelable(mutex);
while (true) {
Thread.futexWaitUncancelable(&cond.epoch.raw, epoch, null);
epoch = cond.epoch.load(.acquire); // 使用 `.acquire`,确保顺序位于 `state` 加载之前
var prev_state = cond.state.load(.monotonic);
while (prev_state.signals > 0) {
prev_state = cond.state.cmpxchgWeak(prev_state, .{
.waiters = prev_state.waiters - 1,
.signals = prev_state.signals - 1,
}, .acquire, .monotonic) orelse {
// 成功消耗了一个信号。
return;
};
}
}
}
/// 与 `Io.Mutex.lock` 相同,但绕过虚函数表。
pub fn mutexLock(m: *Io.Mutex) Io.Cancelable!void {
const initial_state = m.state.cmpxchgStrong(
.unlocked,
.locked_once,
.acquire,
.monotonic,
) orelse {
@branchHint(.likely);
return;
};
if (initial_state == .contended) {
try Thread.futexWait(@ptrCast(&m.state.raw), @backingInt(Io.Mutex.State.contended), null);
}
while (m.state.swap(.contended, .acquire) != .unlocked) {
try Thread.futexWait(@ptrCast(&m.state.raw), @backingInt(Io.Mutex.State.contended), null);
}
}
/// 与 `Io.Mutex.lockUncancelable` 相同,但绕过虚函数表。
pub fn mutexLockUncancelable(m: *Io.Mutex) void {
const initial_state = m.state.cmpxchgStrong(
.unlocked,
.locked_once,
.acquire,
.monotonic,
) orelse {
@branchHint(.likely);
return;
};
if (initial_state == .contended) {
Thread.futexWaitUncancelable(@ptrCast(&m.state.raw), @backingInt(Io.Mutex.State.contended), null);
}
while (m.state.swap(.contended, .acquire) != .unlocked) {
Thread.futexWaitUncancelable(@ptrCast(&m.state.raw), @backingInt(Io.Mutex.State.contended), null);
}
}
/// 与 `Io.Mutex.unlock` 相同,但绕过虚函数表。
pub fn mutexUnlock(m: *Io.Mutex) void {
switch (m.state.swap(.unlocked, .release)) {
.unlocked => unreachable,
.locked_once => {},
.contended => {
@branchHint(.unlikely);
Thread.futexWake(@ptrCast(&m.state.raw), 1);
},
}
}
const OpenError = error{
IsDir,
NotDir,
FileNotFound,
NoDevice,
AccessDenied,
PipeBusy,
PathAlreadyExists,
WouldBlock,
NetworkNotFound,
AntivirusInterference,
FileBusy,
} || Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;
const OpenFileOptions = struct {
access_mask: windows.ACCESS_MASK,
dir: ?windows.HANDLE = null,
sa: ?*const windows.SECURITY_ATTRIBUTES = null,
share_access: windows.FILE.SHARE = .VALID_FLAGS,
creation: windows.FILE.CREATE_DISPOSITION,
filter: Filter = .non_directory_only,
/// 如果为 false,则尝试以重解析点形式打开路径,不解引用。
/// 默认为 true。
follow_symlinks: bool = true,
pub const Filter = enum {
/// 若打开的句柄对应目录,使 `OpenFile` 返回 `error.IsDir`。
non_directory_only,
/// 若打开的句柄不是目录,则使 `OpenFile` 返回 `error.NotDir`。
dir_only,
/// `OpenFile` 不区分打开文件还是目录。
any,
};
};
/// TODO: 在所有位置内联此逻辑,并删除此函数。
fn OpenFile(sub_path_w: []const u16, options: OpenFileOptions) OpenError!windows.HANDLE {
if (std.mem.eql(u16, sub_path_w, &.{'.'}) and options.filter == .non_directory_only) {
return error.IsDir;
}
if (std.mem.eql(u16, sub_path_w, &.{ '.', '.' }) and options.filter == .non_directory_only) {
return error.IsDir;
}
var result: windows.HANDLE = undefined;
const attr: windows.OBJECT.ATTRIBUTES = .{
.RootDirectory = if (Dir.path.isAbsoluteWindowsWtf16(sub_path_w)) null else options.dir,
.Attributes = .{ .INHERIT = if (options.sa) |sa| sa.bInheritHandle.toBool() else false },
.ObjectName = @constCast(&windows.UNICODE_STRING.init(sub_path_w)),
.SecurityDescriptor = if (options.sa) |ptr| ptr.lpSecurityDescriptor else null,
};
var iosb: windows.IO_STATUS_BLOCK = undefined;
var attempt: u5 = 0;
var syscall: Syscall = try .start();
while (true) {
switch (windows.ntdll.NtCreateFile(
&result,
options.access_mask,
&attr,
&iosb,
null,
.{ .NORMAL = true },
options.share_access,
options.creation,
.{
.DIRECTORY_FILE = options.filter == .dir_only,
.NON_DIRECTORY_FILE = options.filter == .non_directory_only,
.IO = .SYNCHRONOUS_NONALERT,
.OPEN_REPARSE_POINT = !options.follow_symlinks,
},
null,
0,
)) {
.SUCCESS => {
syscall.finish();
return result;
},
.CANCELLED => {
try syscall.checkCancel();
continue;
},
.SHARING_VIOLATION => {
// 尝试打开正在运行的可执行文件时会发生此错误。
// 但存在内核缺陷:可执行文件关闭后,在长短不确定的一段时间内仍可能错误返回此错误。
// 这里通过重试规避该内核缺陷。
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.DELETE_PENDING => {
// 此错误表示文件系统的该位置原先存在文件,但已被删除。然而,操作系统尚未完成删除操作,因此本次 CreateFile 调用失败。
// 除了等待操作系统完成删除后重试创建之外,没有合理的处理方式。
//
//
//
//
syscall.finish();
if (max_windows_kernel_bug_retries - attempt == 0) return error.FileBusy;
try parking_sleep.sleep(.{ .duration = .{
.raw = .fromMilliseconds((@as(u32, 1) << attempt) >> 1),
.clock = .awake,
} });
attempt += 1;
syscall = try .start();
continue;
},
.OBJECT_NAME_INVALID => return syscall.fail(error.BadPathName),
.OBJECT_NAME_NOT_FOUND => return syscall.fail(error.FileNotFound),
.OBJECT_PATH_NOT_FOUND => return syscall.fail(error.FileNotFound),
.BAD_NETWORK_PATH => return syscall.fail(error.NetworkNotFound), // 未找到 \\server
.BAD_NETWORK_NAME => return syscall.fail(error.NetworkNotFound), // 找到 \\server,但未找到 \\server\share
.NO_MEDIA_IN_DEVICE => return syscall.fail(error.NoDevice),
.ACCESS_DENIED => return syscall.fail(error.AccessDenied),
.PIPE_BUSY => return syscall.fail(error.PipeBusy),
.PIPE_NOT_AVAILABLE => return syscall.fail(error.NoDevice),
.OBJECT_NAME_COLLISION => return syscall.fail(error.PathAlreadyExists),
.FILE_IS_A_DIRECTORY => return syscall.fail(error.IsDir),
.NOT_A_DIRECTORY => return syscall.fail(error.NotDir),
.USER_MAPPED_FILE => return syscall.fail(error.AccessDenied),
.VIRUS_INFECTED, .VIRUS_DELETED => return syscall.fail(error.AntivirusInterference),
.INVALID_PARAMETER => |status| return syscall.ntstatusBug(status),
.OBJECT_PATH_SYNTAX_BAD => |status| return syscall.ntstatusBug(status),
.INVALID_HANDLE => |status| return syscall.ntstatusBug(status),
else => |status| return syscall.unexpectedNtstatus(status),
}
}
}
pub fn closeFd(fd: posix.fd_t) void {
if (native_os == .wasi and !builtin.link_libc) {
switch (std.os.wasi.fd_close(fd)) {
.SUCCESS, .INTR => {},
.BADF => recoverableOsBugDetected(), // 释放后使用
else => recoverableOsBugDetected(), // 意外失败
}
} else switch (posix.errno(posix.system.close(fd))) {
.SUCCESS, .INTR => {}, // INTR 仍表示成功,参见 https://github.com/ziglang/zig/issues/2425
.BADF => recoverableOsBugDetected(), // 释放后使用
else => recoverableOsBugDetected(), // 意外失败
}
}