system/windows

A Win32 HANDLE: an opaque kernel object, never dereferenced.

COORD: a console cell position or size.

Field names are the C ones because a mirror copies BY NAME; the snake_case rule does not reach across the boundary.

SMALL_RECT: an inclusive rectangle of console cells.

CONSOLE_SCREEN_BUFFER_INFO. Mirrored WHOLE rather than as a prefix: every member but wAttributes is itself a struct, so a prefix would have to stop before the one that matters.

SECURITY_ATTRIBUTES, mirrored for the two members a pipe needs.

EVERY member, in order, not a prefix of the useful ones. The interpreter lays a mirror out from its DECLARED fields alone, at natural alignment from zero, so skipping lpSecurityDescriptor put bInheritHandle at 4 where C has it at 16: the callee read a zero, made the pipe non-inheritable, and reported success. Native was unaffected (the shim copies by name) which is exactly what kept it invisible. The offset _Static_assert catches it now.

lpSecurityDescriptor is a u64 because it is RESERVED, never read: it only has to occupy its eight bytes and stay zero, which is the NULL the call wants.

STARTUPINFOA, mirrored for the members a redirected child needs.

EVERY member up to hStdError, for the reason spelled out on SecurityAttributes: eleven precede dwFlags in the real struct, and naming only the useful ones put every one of them at the wrong offset in the interpreter's block.

The reserved ones are machine words that stay zero, which is what CreateProcess expects of a plain console child. cb must be sizeof(STARTUPINFOA) (104 on x86_64) and is the one member the callee validates.

PROCESS_INFORMATION: what CreateProcess hands back.

GetStdHandle. Returns INVALID_HANDLE_VALUE on failure.

GetActiveProcessorCount. Logical processors active in group; 0 on failure.

GetModuleFileNameW. Writes the running module's path into buf and returns its length; 0 on failure, or size exactly when it was truncated.

GetCurrentDirectoryW. Writes the working directory into buf and returns its length; 0 on failure, or a length >= size when buf is too small.

SetCurrentDirectoryW. Zero on failure.

GetTempPathW. Writes the temp directory, trailing backslash included, into buf. Returns its length, 0 on failure, or a length >= size when buf is too small: in both of which cases nothing usable was written.

CreateDirectoryW. False on failure, ERROR_ALREADY_EXISTS included: the caller re-tests the path rather than reading GetLastError.

GetFileAttributesExW. False when the path cannot be queried.

data crosses as the nine DWORDs of a WIN32_FILE_ATTRIBUTE_DATA, which has no padding : ftLastWriteTime is cells 5 (low half) and 6 (high half).

GetFileAttributesW. INVALID_FILE_ATTRIBUTES when the path cannot be queried, which is how existence is tested, there being no access here.

DeleteFileW. Zero on failure. Refuses a directory outright, which is the behaviour std/io::remove_file promises.

GetLastError. The calling thread's last Win32 error code.

⚠️ Read it IMMEDIATELY after the call that failed: any Win32 call in between may overwrite it.

WriteFile. False on failure: the caller reads GetLastError.

written is Win32's lpNumberOfBytesWritten, which a synchronous call may NOT pass as null.

written is a one-element array so the count READS BACK, the same shape read_file uses. A @c_pointer scalar would not: the callee writes through it and the value is discarded.

MultiByteToWideChar. With src_len of -1 the input is read up to its NUL and the terminator is written too, so the result is usable as LPCWSTR.

WideCharToMultiByte. The two trailing lpDefaultChar / lpUsedDefaultChar arguments must be null for CP_UTF8; Windows fails the call otherwise.

CreateFileW. Returns INVALID_HANDLE_VALUE on failure: test it with i64(h) == INVALID_HANDLE, never against null.

Unlike fopen there is no text mode, so nothing ever rewrites a \n.

FindFirstFileW. The pattern is a directory path with \* appended.

Returns INVALID_HANDLE_VALUE on failure: test it with i64(h) == INVALID_HANDLE, never against null.

FindNextFileW. False once the search is exhausted.

FindClose. Pairs with find_first_file.

The cFileName of a filled WIN32_FIND_DATAW, as a Vader string.

The Windows twin of system/posix::dirent_name, and it exists for the same reason: reading a NAMED member of a C struct is the one step a Vader FFI call cannot take for itself. It has to be a CALL, not a read of the struct: the interpreter has no C layout but resolves an @extern by name out of the running process. It carries the UTF-16 to UTF-8 conversion with it.

The bytes are valid until the next call, which is also cFileName's own contract: find_next_file overwrites it. The shim interns before either.

GetConsoleScreenBufferInfo. False when the handle is not a console.

srWindow is the VISIBLE window, which is what a width should be measured from: the buffer (dwSize) is often far wider, and wrapping follows what is on screen.

PeekNamedPipe. Reports how many bytes are readable WITHOUT consuming them.

It works on an anonymous pipe too, despite the name, which is what makes it the console-less way to ask "is there input". False when the handle is not a pipe (a console, a redirected file) or the peer closed it; a caller reads that as "go ahead and read", never as "idle".

Sleep. Milliseconds, and it is the only wait Win32 offers without a handle.

CreatePipe.

The two ends are separate HANDLE* out-parameters, not one struct, so each is its own one-word buffer. Read the handle back with ptr_at.

The i-th pointer-sized word of a lent buffer, as a handle.

CPointer cannot be built from an integer (T3010) and a lent array yields integers, so a HANDLE an out-parameter wrote is otherwise unreachable.

SetHandleInformation. Used to CLEAR the inherit flag on a pipe's read end.

The pipe is created inheritable so the child receives its write end; without this the child (and every sibling launched after it) also receives the READ ends, which are the parent's alone.

CreateProcessA. Launches command_line, inheriting the handles named in startup.

The ANSI form: the argument vector is one command line by then, and the wide form would need it widened for nothing the child can see.

WaitForSingleObject. WAIT_OBJECT_0 once the process has exited.

GetExitCodeProcess.

TerminateProcess.

GetConsoleMode. False when the handle is not a console, which is also how a caller tests for one, a redirected stream having no mode to read.

SetConsoleMode. False on failure: an old console refusing a mode bit it does not know, which is what tells a caller ANSI is unavailable.

WriteConsoleW: UTF-16 text to a console, which renders it whatever its code page. False on failure, and on a handle that is not a console.

ReadConsoleW: what was typed at a console, as UTF-16 whatever its code page. False on failure, and on a handle that is not a console.

FlushConsoleInputBuffer: drop what was typed at the console h and not read yet. False on failure.

ReadFile. False on failure; a synchronous read returning true with read short of count has reached end of file.

GetFileType. FILE_TYPE_DISK for a file on disk, whose size says how much a read will find; another value for a pipe, a console or a device.

GetFileSizeEx. False on failure.

GetFinalPathNameByHandleW. Writes the path of the file h names, links followed and NUL-terminated, into buf.

CloseHandle. False on failure, which a caller that is done with the file has nothing to do about.

GetSystemTimePreciseAsFileTime. Fills ft with 100-ns ticks since 1601.

QueryPerformanceCounter. Fills counter; false on failure.

QueryPerformanceFrequency. Fills freq with counts per second; false on failure.

nStdHandle selectors. DWORD is unsigned, so the negative constants are written in their two's-complement form.

See STD_OUTPUT_HANDLE.

See STD_OUTPUT_HANDLE.

ALL_PROCESSOR_GROUPS: asks GetActiveProcessorCount for every group, not just the caller's (a group holds at most 64 processors).

FILE_ATTRIBUTE_DIRECTORY: set when the entry is a directory.

What GetFileAttributesW returns for a path it cannot query.

GetFileExInfoStandard, the GET_FILEEX_INFO_LEVELS that fills a WIN32_FILE_ATTRIBUTE_DATA.

Win32 error codes std/io classifies. Unlike errno these are stable across Windows versions, so they are plain literals.

CP_UTF8: the code page identifier for UTF-8.

INVALID_HANDLE_VALUE, as the integer i64(handle) yields. Win32 reports a failed CreateFileW with this and NOT with NULL, which is why the handle is tested through i64 rather than a CPointer | null.

dwDesiredAccess bits.

See GENERIC_READ.

dwShareMode: let other readers in while we hold the file.

See FILE_SHARE_READ.

See FILE_SHARE_READ: let a rename or a delete in too.

dwCreationDisposition: truncate an existing file, create it otherwise.

See CREATE_ALWAYS: open only what already exists.

dwFlagsAndAttributes: no special semantics.

dwFlagsAndAttributes: open a directory as well as a file.

Bytes to reserve for a WIN32_FIND_DATAW.

An OPAQUE buffer: Vader never looks inside it, FindFirstFileW fills it and find_data_name reads the one member a listing needs. Nothing checks this number (the callee writes sizeof(WIN32_FIND_DATAW) bytes whatever it says) so it is taken HIGH on purpose. The real size is 592 on x86_64 (measured against the mingw headers, and it is 320 for the ANSI twin); over-reserving wastes a few hundred bytes on the stack, under-reserving corrupts.

⚠️ Do NOT narrow this to what one toolchain reports.

STARTF_USESTDHANDLES: hStdInput / hStdOutput / hStdError are used.

WAIT_OBJECT_0: the object is signalled, i.e. the process has exited.

INFINITE: a wait with no timeout.

HANDLE_FLAG_INHERIT.

Console INPUT mode bits raw mode turns off (line buffering, echo, and the translation of Ctrl-C into a signal) plus the one it turns on, so escape sequences arrive as bytes.

Bit enabling ANSI escape interpretation on a console output handle. Only with it set do escapes render rather than print literally.

What get_file_type answers for a file on disk.

See get_final_path_name_by_handle_w: a volume named by its drive letter.