This file contains thin wrappers around OS-specific APIs, with these specific goals in mind:

  • Convert “errno”-style error codes into Zig errors.
  • When null-terminated byte buffers are required, provide APIs which accept slices as well as APIs which accept null-terminated byte buffers. Same goes for UTF-16LE encoding.
  • Where operating systems share APIs, e.g. POSIX, these thin wrappers provide cross platform abstracting.
  • When there exists a corresponding libc function and linking libc, the libc implementation is used. Exceptions are made for known buggy areas of libc. On Linux libc can be side-stepped by using std.os.linux directly.
  • For Windows, this file represents the API that libc would provide for Windows. For thin wrappers around Windows-specific APIs, see std.os.windows. Note: The Zig standard library does not support POSIX thread cancellation, and in general EINTR is handled by trying again.

Global Variables

argv
[][*:0]u8

Populated by startup code before main(). Not available on WASI or Windows witho…

environ
[][*:0]u8

See also getenv. Populated by startup code before main(). TODO this is a foot…

Functions

fn abort() noreturn

Causes abnormal process termination. If linking against libc, this calls the ab…

Causes abnormal process termination. If linking against libc, this calls the abort() libc function. Otherwise it raises SIGABRT followed by SIGKILL and finally lo Invokes the current signal handler for SIGABRT, if any.

fn accept(sock: socket_t, addr: ?*sockaddr, addr_size: ?*socklen_t, flags: u32) AcceptError!socket_t

Accept a connection on a socket. If sockfd is opened in non blocking mode, th…

Accept a connection on a socket. If sockfd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received.

fn access(path: []const u8, mode: u32) AccessError!void

check user’s permissions for a file TODO currently this assumes mode is `F.OK…

check user’s permissions for a file TODO currently this assumes mode is F.OK on Windows.

fn accessW(path: [*:0]const u16, mode: u32) windows.GetFileAttributesError!void

Call from Windows-specific code if you already have a UTF-16LE encoded, null ter…

Call from Windows-specific code if you already have a UTF-16LE encoded, null terminated string. Otherwise use access or accessC. TODO currently this ignores mode.

fn accessZ(path: [*:0]const u8, mode: u32) AccessError!void

Same as access except path is null-terminated.

fn bind(sock: socket_t, addr: *const sockaddr, len: socklen_t) BindError!void

addr is *const T where T is one of the sockaddr

fn chdir(dir_path: []const u8) ChangeCurDirError!void

Changes the current working directory of the calling process. dir_path is rec…

Changes the current working directory of the calling process. dir_path is recommended to be a UTF-8 encoded string.

fn chdirW(dir_path: []const u16) ChangeCurDirError!void

Windows-only. Same as chdir except the parameter is WTF16 encoded.

fn chdirZ(dir_path: [*:0]const u8) ChangeCurDirError!void

Same as chdir except the parameter is null-terminated.

fn clock_getres(clk_id: i32, res: *timespec) ClockGetTimeError!void

No documentation provided.

fn clock_gettime(clk_id: i32, tp: *timespec) ClockGetTimeError!void

TODO: change this to return the timespec as a return value TODO: look into maki…

TODO: change this to return the timespec as a return value TODO: look into making clk_id an enum

fn close(fd: fd_t) void

Closes the file descriptor. This function is not capable of returning any indic…

Closes the file descriptor. This function is not capable of returning any indication of failure. An application which wants to ensure writes have succeeded before closing must call fsync before close. Note: The Zig standard library does not support POSIX thread cancellation.

fn closeSocket(sock: socket_t) void

No documentation provided.

fn connect(sock: socket_t, sock_addr: *const sockaddr, len: socklen_t) ConnectError!void

Initiate a connection on a socket. If sockfd is opened in non blocking mode, …

Initiate a connection on a socket. If sockfd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN or EINPROGRESS is received.

fn copy_file_range(fd_in: fd_t, off_in: u64, fd_out: fd_t, off_out: u64, len: usize, flags: u32) CopyFileRangeError!usize

Transfer data between file descriptors at specified offsets. Returns the number…

Transfer data between file descriptors at specified offsets. Returns the number of bytes written, which can less than requested.

The copy_file_range call copies len bytes from one file descriptor to another. When possible, this is done within the operating system kernel, which can provide better performance characteristics than transferring data from kernel to user space and back, such as with pread and pwrite calls.

fd_in must be a file descriptor opened for reading, and fd_out must be a file descriptor opened for writing. They may be any kind of file descriptor; however, if fd_in is not a regular file system file, it may cause this function to fall back to calling pread and pwrite, in which case atomicity guarantees no longer apply.

If fd_in and fd_out are the same, source and target ranges must not overlap. The file descriptor seek positions are ignored and not updated. When off_in is past the end of the input file, it successfully reads 0 bytes.

flags has different meanings per operating system; refer to the respective man pages.

These systems support in-kernel data copying:

  • Linux 4.5 (cross-filesystem 5.3)
  • FreeBSD 13.0

Other systems fall back to calling pread / pwrite.

Maximum offsets on Linux and FreeBSD are math.maxInt(i64).

fn dl_iterate_phdr(context: anytype, comptime Error: type, comptime callback: fn (*dl_phdr_info, usize, @TypeOf(context)) Error!void) Error!void

No documentation provided.

fn dn_expand(msg: []const u8, comp_dn: []const u8, exp_dn: []u8) DnExpandError!usize

No documentation provided.

fn dup(old_fd: fd_t) !fd_t

No documentation provided.

fn dup2(old_fd: fd_t, new_fd: fd_t) !void

No documentation provided.

fn epoll_create1(flags: u32) EpollCreateError!i32

No documentation provided.

fn epoll_ctl(epfd: i32, op: u32, fd: i32, event: ?*linux.epoll_event) EpollCtlError!void

No documentation provided.

fn epoll_wait(epfd: i32, events: []linux.epoll_event, timeout: i32) usize

Waits for an I/O event on an epoll file descriptor. Returns the number of file …

Waits for an I/O event on an epoll file descriptor. Returns the number of file descriptors ready for the requested I/O, or zero if no file descriptor became ready during the requested timeout milliseconds.

fn eventfd(initval: u32, flags: u32) EventFdError!i32

No documentation provided.

fn execveZ(path: [*:0]const u8, child_argv: [*:null]const ?[*:0]const u8, envp: [*:null]const ?[*:0]const u8) ExecveError

This function ignores PATH environment variable. See execvpeZ for that.

fn execvpeZ(file: [*:0]const u8, argv_ptr: [*:null]const ?[*:0]const u8, envp: [*:null]const ?[*:0]const u8) ExecveError

This function also uses the PATH environment variable to get the full path to th…

This function also uses the PATH environment variable to get the full path to the executable. If file is an absolute path, this is the same as execveZ.

fn execvpeZ_expandArg0(comptime arg0_expand: Arg0Expand, file: [*:0]const u8, child_argv: anytype, envp: [*:null]const ?[*:0]const u8) ExecveError

Like execvpeZ except if arg0_expand is .expand, then argv is mutable, a…

Like execvpeZ except if arg0_expand is .expand, then argv is mutable, and argv[0] is expanded to be the same absolute path that is passed to the execve syscall. If this function returns with an error, argv[0] will be restored to the value it was when it was passed in.

fn exit(status: u8) noreturn

Exits the program cleanly with the specified status code.

fn faccessat(dirfd: fd_t, path: []const u8, mode: u32, flags: u32) AccessError!void

Check user’s permissions for a file, based on an open directory handle. TODO cu…

Check user’s permissions for a file, based on an open directory handle. TODO currently this ignores mode and flags on Windows.

fn faccessatW(dirfd: fd_t, sub_path_w: [*:0]const u16, mode: u32, flags: u32) AccessError!void

Same as faccessat except asserts the target is Windows and the path parameter …

Same as faccessat except asserts the target is Windows and the path parameter is NtDll-prefixed, null-terminated, WTF-16 encoded. TODO currently this ignores mode and flags

fn faccessatZ(dirfd: fd_t, path: [*:0]const u8, mode: u32, flags: u32) AccessError!void

Same as faccessat except the path parameter is null-terminated.

fn fchdir(dirfd: fd_t) FchdirError!void

No documentation provided.

fn fchmod(fd: fd_t, mode: mode_t) FChmodError!void

Changes the mode of the file referred to by the file descriptor. The process mu…

Changes the mode of the file referred to by the file descriptor. The process must have the correct privileges in order to do this successfully, or must have the effective user ID matching the owner of the file.

fn fchmodat(dirfd: fd_t, path: []const u8, mode: mode_t, flags: u32) FChmodAtError!void

No documentation provided.

fn fchown(fd: fd_t, owner: ?uid_t, group: ?gid_t) FChownError!void

Changes the owner and group of the file referred to by the file descriptor. The…

Changes the owner and group of the file referred to by the file descriptor. The process must have the correct privileges in order to do this successfully. The group may be changed by the owner of the directory to any group of which the owner is a member. If the owner or group is specified as null, the ID is not changed.

fn fcntl(fd: fd_t, cmd: i32, arg: usize) FcntlError!usize

No documentation provided.

fn fdatasync(fd: fd_t) SyncError!void

Write all pending file contents for the specified file descriptor to the underly…

Write all pending file contents for the specified file descriptor to the underlying filesystem, but not necessarily the metadata.

fn flock(fd: fd_t, operation: i32) FlockError!void

Depending on the operating system flock may or may not interact with fcntl

Depending on the operating system flock may or may not interact with fcntl locks made by other processes.

fn fork() ForkError!pid_t

No documentation provided.

fn fstat(fd: fd_t) FStatError!Stat

Return information about a file descriptor.

fn fstatat(dirfd: fd_t, pathname: []const u8, flags: u32) FStatAtError!Stat

Similar to fstat, but returns stat of a resource pointed to by pathname whi…

Similar to fstat, but returns stat of a resource pointed to by pathname which is relative to dirfd handle. See also fstatatZ and fstatatWasi.

fn fstatatWasi(dirfd: fd_t, pathname: []const u8, flags: u32) FStatAtError!Stat

WASI-only. Same as fstatat but targeting WASI. See also fstatat.

fn fstatatZ(dirfd: fd_t, pathname: [*:0]const u8, flags: u32) FStatAtError!Stat

Same as fstatat but pathname is null-terminated. See also fstatat.

fn fsync(fd: fd_t) SyncError!void

Write all pending file contents and metadata modifications for the specified fil…

Write all pending file contents and metadata modifications for the specified file descriptor to the underlying filesystem.

fn ftruncate(fd: fd_t, length: u64) TruncateError!void

No documentation provided.

fn futimens(fd: fd_t, times: *const [2]timespec) FutimensError!void

No documentation provided.

fn getFdPath(fd: fd_t, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8

Return canonical path of handle fd. This function is very host-specific and i…

Return canonical path of handle fd. This function is very host-specific and is not universally supported by all hosts. For example, while it generally works on Linux, macOS, FreeBSD or Windows, it is unsupported on WASI.

fn getcwd(out_buffer: []u8) GetCwdError![]u8

The result is a slice of out_buffer, indexed from 0.

fn getenv(key: []const u8) ?[:0]const u8

Get an environment variable. See also getenvZ.

fn getenvW(key: [*:0]const u16) ?[:0]const u16

Windows-only. Get an environment variable with a null-terminated, WTF-16 encoded…

Windows-only. Get an environment variable with a null-terminated, WTF-16 encoded name. See also getenv. This function performs a Unicode-aware case-insensitive lookup using RtlEqualUnicodeString.

fn getenvZ(key: [*:0]const u8) ?[:0]const u8

Get an environment variable with a null-terminated name. See also getenv.

fn gethostname(name_buffer: *[HOST_NAME_MAX]u8) GetHostNameError![]u8

No documentation provided.

fn getpeername(sock: socket_t, addr: *sockaddr, addrlen: *socklen_t) GetSockNameError!void

No documentation provided.

fn getrandom(buffer: []u8) GetRandomError!void

Obtain a series of random bytes. These bytes can be used to seed user-space ran…

Obtain a series of random bytes. These bytes can be used to seed user-space random number generators or for cryptographic purposes. When linking against libc, this calls the appropriate OS-specific library call. Otherwise it uses the zig standard library implementation.

fn getrlimit(resource: rlimit_resource) GetrlimitError!rlimit

No documentation provided.

fn getrusage(who: i32) rusage

No documentation provided.

fn getsockname(sock: socket_t, addr: *sockaddr, addrlen: *socklen_t) GetSockNameError!void

No documentation provided.

fn getsockoptError(sockfd: fd_t) ConnectError!void

No documentation provided.

fn gettimeofday(tv: ?*timeval, tz: ?*timezone) void

No documentation provided.

fn inotify_add_watch(inotify_fd: i32, pathname: []const u8, mask: u32) INotifyAddWatchError!i32

add a watch to an initialized inotify instance

fn inotify_add_watchZ(inotify_fd: i32, pathname: [*:0]const u8, mask: u32) INotifyAddWatchError!i32

Same as inotify_add_watch except pathname is null-terminated.

fn inotify_init1(flags: u32) INotifyInitError!i32

initialize an inotify instance

fn inotify_rm_watch(inotify_fd: i32, wd: i32) void

remove an existing watch from an inotify instance

fn ioctl_SIOCGIFINDEX(fd: fd_t, ifr: *ifreq) IoCtl_SIOCGIFINDEX_Error!void

No documentation provided.

fn isCygwinPty(handle: fd_t) bool

No documentation provided.

fn isatty(handle: fd_t) bool

Test whether a file descriptor refers to a terminal.

fn kevent(kq: i32, changelist: []const Kevent, eventlist: []Kevent, timeout: ?*const timespec) KEventError!usize

No documentation provided.

fn kill(pid: pid_t, sig: u8) KillError!void

No documentation provided.

fn kqueue() KQueueError!i32

No documentation provided.

fn link(oldpath: []const u8, newpath: []const u8, flags: i32) LinkError!void

No documentation provided.

fn linkZ(oldpath: [*:0]const u8, newpath: [*:0]const u8, flags: i32) LinkError!void

No documentation provided.

fn linkat(olddir: fd_t, oldpath: []const u8, newdir: fd_t, newpath: []const u8, flags: i32) LinkatError!void

No documentation provided.

fn linkatWasi(old: RelativePathWasi, new: RelativePathWasi, flags: i32) LinkatError!void

WASI-only. The same as linkat but targeting WASI. See also linkat.

fn linkatZ(olddir: fd_t, oldpath: [*:0]const u8, newdir: fd_t, newpath: [*:0]const u8, flags: i32) LinkatError!void

No documentation provided.

fn listen(sock: socket_t, backlog: u31) ListenError!void

No documentation provided.

fn lseek_CUR(fd: fd_t, offset: i64) SeekError!void

Repositions read/write file offset relative to the current offset.

fn lseek_CUR_get(fd: fd_t) SeekError!u64

Returns the read/write file offset relative to the beginning.

fn lseek_END(fd: fd_t, offset: i64) SeekError!void

Repositions read/write file offset relative to the end.

fn lseek_SET(fd: fd_t, offset: u64) SeekError!void

Repositions read/write file offset relative to the beginning.

fn madvise(ptr: [*]align(mem.page_size) u8, length: usize, advice: u32) MadviseError!void

Give advice about use of memory. This syscall is optional and is sometimes conf…

Give advice about use of memory. This syscall is optional and is sometimes configured to be disabled.

fn maybeIgnoreSigpipe() void

On default executed by posix startup code before main(), if SIGPIPE is supported…

On default executed by posix startup code before main(), if SIGPIPE is supported.

fn memfd_create(name: []const u8, flags: u32) !fd_t

No documentation provided.

fn memfd_createZ(name: [*:0]const u8, flags: u32) MemFdCreateError!fd_t

No documentation provided.

fn mincore(ptr: [*]align(mem.page_size) u8, length: usize, vec: [*]u8) MincoreError!void

Determine whether pages are resident in memory.

fn mkdir(dir_path: []const u8, mode: u32) MakeDirError!void

Create a directory. mode is ignored on Windows and WASI.

fn mkdirW(dir_path_w: []const u16, mode: u32) MakeDirError!void

Windows-only. Same as mkdir but the parameters is WTF16 encoded.

fn mkdirZ(dir_path: [*:0]const u8, mode: u32) MakeDirError!void

Same as mkdir but the parameter is a null-terminated UTF8-encoded string.

fn mkdirat(dir_fd: fd_t, sub_dir_path: []const u8, mode: u32) MakeDirError!void

No documentation provided.

fn mkdiratW(dir_fd: fd_t, sub_path_w: []const u16, mode: u32) MakeDirError!void

No documentation provided.

fn mkdiratWasi(dir_fd: fd_t, sub_dir_path: []const u8, mode: u32) MakeDirError!void

No documentation provided.

fn mkdiratZ(dir_fd: fd_t, sub_dir_path: [*:0]const u8, mode: u32) MakeDirError!void

No documentation provided.

fn mmap(ptr: ?[*]align(mem.page_size) u8, length: usize, prot: u32, flags: u32, fd: fd_t, offset: u64) MMapError![]align(mem.page_size) u8

Map files or devices into memory. length does not need to be aligned. Use of…

Map files or devices into memory. length does not need to be aligned. Use of a mapped region can result in these signals:

  • SIGSEGV - Attempted write into a region mapped as read-only.
  • SIGBUS - Attempted access to a portion of the buffer that does not correspond to the file
fn mprotect(memory: []align(mem.page_size) u8, protection: u32) MProtectError!void

memory.len must be page-aligned.

fn msync(memory: []align(mem.page_size) u8, flags: i32) MSyncError!void

No documentation provided.

fn munmap(memory: []const align(mem.page_size) u8) void

Deletes the mappings for the specified address range, causing further reference…

Deletes the mappings for the specified address range, causing further references to addresses within the range to generate invalid memory references. Note that while POSIX allows unmapping a region in the middle of an existing mapping, Zig’s munmap function does not, for two reasons:

  • It violates the Zig principle that resource deallocation must succeed.
  • The Windows function, VirtualFree, has this restriction.
fn nanosleep(seconds: u64, nanoseconds: u64) void

Spurious wakeups are possible and no precision of timing is guaranteed.

fn open(file_path: []const u8, flags: u32, perm: mode_t) OpenError!fd_t

Open and possibly create a file. Keeps trying if it gets interrupted. See also …

Open and possibly create a file. Keeps trying if it gets interrupted. See also openZ.

fn openW(file_path_w: []const u16, flags: u32, perm: mode_t) OpenError!fd_t

Windows-only. The path parameter is [WTF-16](https://simonsapin.github.io/wtf-8…

Windows-only. The path parameter is WTF-16 encoded. Translates the POSIX open API call to a Windows API call. TODO currently, this function does not handle all flag combinations or makes use of perm argument.

fn openZ(file_path: [*:0]const u8, flags: u32, perm: mode_t) OpenError!fd_t

Open and possibly create a file. Keeps trying if it gets interrupted. See also …

Open and possibly create a file. Keeps trying if it gets interrupted. See also open.

fn openat(dir_fd: fd_t, file_path: []const u8, flags: u32, mode: mode_t) OpenError!fd_t

Open and possibly create a file. Keeps trying if it gets interrupted. `file_pat…

Open and possibly create a file. Keeps trying if it gets interrupted. file_path is relative to the open directory handle dir_fd. See also openatZ.

fn openatW(dir_fd: fd_t, file_path_w: []const u16, flags: u32, mode: mode_t) OpenError!fd_t

Windows-only. Similar to openat but with pathname argument null-terminated WT…

Windows-only. Similar to openat but with pathname argument null-terminated WTF16 encoded. TODO currently, this function does not handle all flag combinations or makes use of perm argument.

fn openatWasi(dir_fd: fd_t, file_path: []const u8, lookup_flags: lookupflags_t, oflags: oflags_t, fdflags: fdflags_t, base: rights_t, inheriting: rights_t) OpenError!fd_t

Open and possibly create a file in WASI.

fn openatZ(dir_fd: fd_t, file_path: [*:0]const u8, flags: u32, mode: mode_t) OpenError!fd_t

Open and possibly create a file. Keeps trying if it gets interrupted. `file_pat…

Open and possibly create a file. Keeps trying if it gets interrupted. file_path is relative to the open directory handle dir_fd. See also openat.

fn perf_event_open(attr: *linux.perf_event_attr, pid: pid_t, cpu: i32, group_fd: fd_t, flags: usize) PerfEventOpenError!fd_t

No documentation provided.

fn pipe() PipeError![2]fd_t

Creates a unidirectional data channel that can be used for interprocess communic…

Creates a unidirectional data channel that can be used for interprocess communication.

fn pipe2(flags: u32) PipeError![2]fd_t

No documentation provided.

fn poll(fds: []pollfd, timeout: i32) PollError!usize

No documentation provided.

fn ppoll(fds: []pollfd, timeout: ?*const timespec, mask: ?*const sigset_t) PPollError!usize

No documentation provided.

fn prctl(option: PR, args: anytype) PrctlError!u31

No documentation provided.

fn pread(fd: fd_t, buf: []u8, offset: u64) PReadError!usize

Number of bytes read is returned. Upon reading end-of-file, zero is returned.

Number of bytes read is returned. Upon reading end-of-file, zero is returned.

Retries when interrupted by a signal.

For POSIX systems, if fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received. On Windows, if the application has a global event loop enabled, I/O Completion Ports are used to perform the I/O. error.WouldBlock is not possible on Windows.

Linux has a limit on how many bytes may be transferred in one pread call, which is 0x7ffff000 on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as well as stuffing the errno codes into the last 4096 values. This is noted on the read man page. The limit on Darwin is 0x7fffffff, trying to read more than that returns EINVAL. The corresponding POSIX limit is math.maxInt(isize).

fn preadv(fd: fd_t, iov: []const iovec, offset: u64) PReadError!usize

Number of bytes read is returned. Upon reading end-of-file, zero is returned.

Number of bytes read is returned. Upon reading end-of-file, zero is returned.

Retries when interrupted by a signal.

For POSIX systems, if fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received. On Windows, if the application has a global event loop enabled, I/O Completion Ports are used to perform the I/O. error.WouldBlock is not possible on Windows.

This operation is non-atomic on the following systems:

  • Darwin
  • Windows On these systems, the read races with concurrent writes to the same file descriptor.
fn ptrace(request: u32, pid: pid_t, addr: usize, signal: usize) PtraceError!void

No documentation provided.

fn pwrite(fd: fd_t, bytes: []const u8, offset: u64) PWriteError!usize

Write to a file descriptor, with a position offset. Retries when interrupted by…

Write to a file descriptor, with a position offset. Retries when interrupted by a signal. Returns the number of bytes written. If nonzero bytes were supplied, this will be nonzero.

Note that a successful write() may transfer fewer bytes than supplied. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before it had transferred all of the requested bytes. In the event of a partial write, the caller can make another write() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full).

For POSIX systems, if fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received. On Windows, if the application has a global event loop enabled, I/O Completion Ports are used to perform the I/O. error.WouldBlock is not possible on Windows.

Linux has a limit on how many bytes may be transferred in one pwrite call, which is 0x7ffff000 on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as well as stuffing the errno codes into the last 4096 values. This is noted on the write man page. The limit on Darwin is 0x7fffffff, trying to write more than that returns EINVAL. The corresponding POSIX limit is math.maxInt(isize).

fn pwritev(fd: fd_t, iov: []const iovec_const, offset: u64) PWriteError!usize

Write multiple buffers to a file descriptor, with a position offset. Retries wh…

Write multiple buffers to a file descriptor, with a position offset. Retries when interrupted by a signal. Returns the number of bytes written. If nonzero bytes were supplied, this will be nonzero.

Note that a successful write() may transfer fewer than count bytes. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before it had transferred all of the requested bytes. In the event of a partial write, the caller can make another write() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full).

If fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received.

The following systems do not have this syscall, and will return partial writes if more than one vector is provided:

  • Darwin
  • Windows

If iov.len is larger than IOV_MAX, a partial write will occur.

fn raise(sig: u8) RaiseError!void

No documentation provided.

fn read(fd: fd_t, buf: []u8) ReadError!usize

Returns the number of bytes that were read, which can be less than buf.len. If …

Returns the number of bytes that were read, which can be less than buf.len. If 0 bytes were read, that means EOF. If fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received.

Linux has a limit on how many bytes may be transferred in one read call, which is 0x7ffff000 on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as well as stuffing the errno codes into the last 4096 values. This is noted on the read man page. The limit on Darwin is 0x7fffffff, trying to read more than that returns EINVAL. The corresponding POSIX limit is math.maxInt(isize).

fn readlink(file_path: []const u8, out_buffer: []u8) ReadLinkError![]u8

Read value of a symbolic link. The return value is a slice of out_buffer from…

Read value of a symbolic link. The return value is a slice of out_buffer from index 0.

fn readlinkW(file_path: []const u16, out_buffer: []u8) ReadLinkError![]u8

Windows-only. Same as readlink except file_path is WTF16 encoded. See also …

Windows-only. Same as readlink except file_path is WTF16 encoded. See also readlinkZ.

fn readlinkZ(file_path: [*:0]const u8, out_buffer: []u8) ReadLinkError![]u8

Same as readlink except file_path is null-terminated.

fn readlinkat(dirfd: fd_t, file_path: []const u8, out_buffer: []u8) ReadLinkError![]u8

Similar to readlink except reads value of a symbolink link relative to `di…

Similar to readlink except reads value of a symbolink link relative to dirfd directory handle. The return value is a slice of out_buffer from index 0. See also readlinkatWasi, realinkatZ and realinkatW.

fn readlinkatW(dirfd: fd_t, file_path: []const u16, out_buffer: []u8) ReadLinkError![]u8

Windows-only. Same as readlinkat except file_path is null-terminated, WTF16 …

Windows-only. Same as readlinkat except file_path is null-terminated, WTF16 encoded. See also readlinkat.

fn readlinkatWasi(dirfd: fd_t, file_path: []const u8, out_buffer: []u8) ReadLinkError![]u8

WASI-only. Same as readlinkat but targets WASI. See also readlinkat.

fn readlinkatZ(dirfd: fd_t, file_path: [*:0]const u8, out_buffer: []u8) ReadLinkError![]u8

Same as readlinkat except file_path is null-terminated. See also `readlinka…

Same as readlinkat except file_path is null-terminated. See also readlinkat.

fn readv(fd: fd_t, iov: []const iovec) ReadError!usize

Number of bytes read is returned. Upon reading end-of-file, zero is returned.

Number of bytes read is returned. Upon reading end-of-file, zero is returned.

For POSIX systems, if fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received. On Windows, if the application has a global event loop enabled, I/O Completion Ports are used to perform the I/O. error.WouldBlock is not possible on Windows.

This operation is non-atomic on the following systems:

  • Windows On these systems, the read races with concurrent writes to the same file descriptor.

This function assumes that all vectors, including zero-length vectors, have a pointer within the address space of the application.

fn realpath(pathname: []const u8, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8

Return the canonicalized absolute pathname. Expands all symbolic links and reso…

Return the canonicalized absolute pathname. Expands all symbolic links and resolves references to ., .., and extra / characters in pathname. The return value is a slice of out_buffer, but not necessarily from the beginning. See also realpathZ and realpathW.

fn realpathW(pathname: []const u16, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8

Same as realpath except pathname is UTF16LE-encoded.

fn realpathZ(pathname: [*:0]const u8, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8

Same as realpath except pathname is null-terminated.

fn reboot(cmd: RebootCommand) RebootError!void

No documentation provided.

fn recv(sock: socket_t, buf: []u8, flags: u32) RecvFromError!usize

No documentation provided.

fn recvfrom(sockfd: socket_t, buf: []u8, flags: u32, src_addr: ?*sockaddr, addrlen: ?*socklen_t) RecvFromError!usize

If sockfd is opened in non blocking mode, the function will return error.Woul…

If sockfd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received.

fn rename(old_path: []const u8, new_path: []const u8) RenameError!void

Change the name or location of a file.

fn renameW(old_path: [*:0]const u16, new_path: [*:0]const u16) RenameError!void

Same as rename except the parameters are null-terminated UTF16LE encoded byte …

Same as rename except the parameters are null-terminated UTF16LE encoded byte arrays. Assumes target is Windows.

fn renameZ(old_path: [*:0]const u8, new_path: [*:0]const u8) RenameError!void

Same as rename except the parameters are null-terminated byte arrays.

fn renameat(old_dir_fd: fd_t, old_path: []const u8, new_dir_fd: fd_t, new_path: []const u8) RenameError!void

Change the name or location of a file based on an open directory handle.

fn renameatW(old_dir_fd: fd_t, old_path_w: []const u16, new_dir_fd: fd_t, new_path_w: []const u16, ReplaceIfExists: windows.BOOLEAN) RenameError!void

Same as renameat but Windows-only and the path parameters are [WTF-16](https:…

Same as renameat but Windows-only and the path parameters are WTF-16 encoded.

fn renameatWasi(old: RelativePathWasi, new: RelativePathWasi) RenameError!void

WASI-only. Same as renameat expect targeting WASI. See also renameat.

fn renameatZ(old_dir_fd: fd_t, old_path: [*:0]const u8, new_dir_fd: fd_t, new_path: [*:0]const u8) RenameError!void

Same as renameat except the parameters are null-terminated byte arrays.

fn res_mkquery(op: u4, dname: []const u8, class: u8, ty: u8, data: []const u8, newrr: ?[*]const u8, buf: []u8) usize

No documentation provided.

fn rmdir(dir_path: []const u8) DeleteDirError!void

Deletes an empty directory.

fn rmdirW(dir_path_w: []const u16) DeleteDirError!void

Windows-only. Same as rmdir except the parameter is WTF16 encoded.

fn rmdirZ(dir_path: [*:0]const u8) DeleteDirError!void

Same as rmdir except the parameter is null-terminated.

fn sched_getaffinity(pid: pid_t) SchedGetAffinityError!cpu_set_t

No documentation provided.

fn send(sockfd: socket_t, buf: []const u8, flags: u32) SendError!usize

Transmit a message to another socket.

Transmit a message to another socket.

The send call may be used only when the socket is in a connected state (so that the intended recipient is known). The only difference between send and write is the presence of flags. With a zero flags argument, send is equivalent to write. Also, the following call

 send(sockfd, buf, len, flags);

is equivalent to

 sendto(sockfd, buf, len, flags, NULL, 0);

There is no indication of failure to deliver.

When the message does not fit into the send buffer of the socket, send normally blocks, unless the socket has been placed in nonblocking I/O mode. In nonblocking mode it would fail with SendError.WouldBlock. The select call may be used to determine when it is possible to send more data.

fn sendfile(out_fd: fd_t, in_fd: fd_t, in_offset: u64, in_len: u64, headers: []const iovec_const, trailers: []const iovec_const, flags: u32) SendFileError!usize

Transfer data between file descriptors, with optional headers and trailers. Ret…

Transfer data between file descriptors, with optional headers and trailers. Returns the number of bytes written, which can be zero.

The sendfile call copies in_len bytes from one file descriptor to another. When possible, this is done within the operating system kernel, which can provide better performance characteristics than transferring data from kernel to user space and back, such as with read and write calls. When in_len is 0, it means to copy until the end of the input file has been reached. Note, however, that partial writes are still possible in this case.

in_fd must be a file descriptor opened for reading, and out_fd must be a file descriptor opened for writing. They may be any kind of file descriptor; however, if in_fd is not a regular file system file, it may cause this function to fall back to calling read and write, in which case atomicity guarantees no longer apply.

Copying begins reading at in_offset. The input file descriptor seek position is ignored and not updated. If the output file descriptor has a seek position, it is updated as bytes are written. When in_offset is past the end of the input file, it successfully reads 0 bytes.

flags has different meanings per operating system; refer to the respective man pages.

These systems support atomically sending everything, including headers and trailers:

  • macOS
  • FreeBSD

These systems support in-kernel data copying, but headers and trailers are not sent atomically:

  • Linux

Other systems fall back to calling read / write.

Linux has a limit on how many bytes may be transferred in one sendfile call, which is 0x7ffff000 on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as well as stuffing the errno codes into the last 4096 values. This is noted on the sendfile man page. The limit on Darwin is 0x7fffffff, trying to write more than that returns EINVAL. The corresponding POSIX limit on this is math.maxInt(isize).

fn sendmsg(sockfd: socket_t, msg: *const msghdr_const, flags: u32) SendMsgError!usize

No documentation provided.

fn sendto(sockfd: socket_t, buf: []const u8, flags: u32, dest_addr: ?*const sockaddr, addrlen: socklen_t) SendToError!usize

Transmit a message to another socket.

Transmit a message to another socket.

The sendto call may be used only when the socket is in a connected state (so that the intended recipient is known). The following call

 send(sockfd, buf, len, flags);

is equivalent to

 sendto(sockfd, buf, len, flags, NULL, 0);

If sendto() is used on a connection-mode (SOCK.STREAM, SOCK.SEQPACKET) socket, the arguments dest_addr and addrlen are asserted to be null and 0 respectively, and asserted that the socket was actually connected. Otherwise, the address of the target is given by dest_addr with addrlen specifying its size.

If the message is too long to pass atomically through the underlying protocol, SendError.MessageTooBig is returned, and the message is not transmitted.

There is no indication of failure to deliver.

When the message does not fit into the send buffer of the socket, sendto normally blocks, unless the socket has been placed in nonblocking I/O mode. In nonblocking mode it would fail with SendError.WouldBlock. The select call may be used to determine when it is possible to send more data.

fn setegid(uid: uid_t) SetEidError!void

No documentation provided.

fn seteuid(uid: uid_t) SetEidError!void

No documentation provided.

fn setgid(gid: gid_t) SetIdError!void

No documentation provided.

fn setregid(rgid: gid_t, egid: gid_t) SetIdError!void

No documentation provided.

fn setreuid(ruid: uid_t, euid: uid_t) SetIdError!void

No documentation provided.

fn setrlimit(resource: rlimit_resource, limits: rlimit) SetrlimitError!void

No documentation provided.

fn setsockopt(fd: socket_t, level: u32, optname: u32, opt: []const u8) SetSockOptError!void

Set a socket’s options.

fn setuid(uid: uid_t) SetIdError!void

No documentation provided.

fn shutdown(sock: socket_t, how: ShutdownHow) ShutdownError!void

Shutdown socket send/receive operations

fn sigaction(sig: u6, act: ?*const Sigaction, oact: ?*Sigaction) error{OperationNotSupported}!void

Examine and change a signal action.

fn sigaltstack(ss: ?*stack_t, old_ss: ?*stack_t) SigaltstackError!void

No documentation provided.

fn signalfd(fd: fd_t, mask: *const sigset_t, flags: u32) !fd_t

No documentation provided.

fn sigprocmask(flags: u32, set: ?*const sigset_t, oldset: ?*sigset_t) void

Sets the thread signal mask.

fn socket(domain: u32, socket_type: u32, protocol: u32) SocketError!socket_t

No documentation provided.

fn symlink(target_path: []const u8, sym_link_path: []const u8) SymLinkError!void

Creates a symbolic link named sym_link_path which contains the string `target_…

Creates a symbolic link named sym_link_path which contains the string target_path. A symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one; the latter case is known as a dangling link. If sym_link_path exists, it will not be overwritten. See also `symlinkZ.

fn symlinkZ(target_path: [*:0]const u8, sym_link_path: [*:0]const u8) SymLinkError!void

This is the same as symlink except the parameters are null-terminated pointers…

This is the same as symlink except the parameters are null-terminated pointers. See also symlink.

fn symlinkat(target_path: []const u8, newdirfd: fd_t, sym_link_path: []const u8) SymLinkError!void

Similar to symlink, however, creates a symbolic link named sym_link_path whi…

Similar to symlink, however, creates a symbolic link named sym_link_path which contains the string target_path relative to newdirfd directory handle. A symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one; the latter case is known as a dangling link. If sym_link_path exists, it will not be overwritten. See also symlinkatWasi, symlinkatZ and symlinkatW.

fn symlinkatWasi(target_path: []const u8, newdirfd: fd_t, sym_link_path: []const u8) SymLinkError!void

WASI-only. The same as symlinkat but targeting WASI. See also symlinkat.

fn symlinkatZ(target_path: [*:0]const u8, newdirfd: fd_t, sym_link_path: [*:0]const u8) SymLinkError!void

The same as symlinkat except the parameters are null-terminated pointers. See…

The same as symlinkat except the parameters are null-terminated pointers. See also symlinkat.

fn sync() void

Write all pending file contents and metadata modifications to all filesystems.

fn syncfs(fd: fd_t) SyncError!void

Write all pending file contents and metadata modifications to the filesystem whi…

Write all pending file contents and metadata modifications to the filesystem which contains the specified file.

fn sysctl(name: []const c_int, oldp: ?*anyopaque, oldlenp: ?*usize, newp: ?*anyopaque, newlen: usize) SysCtlError!void

No documentation provided.

fn sysctlbynameZ(name: [*:0]const u8, oldp: ?*anyopaque, oldlenp: ?*usize, newp: ?*anyopaque, newlen: usize) SysCtlError!void

No documentation provided.

fn tcgetattr(handle: fd_t) TermiosGetError!termios

No documentation provided.

fn tcgetpgrp(handle: fd_t) TermioGetPgrpError!pid_t

Returns the process group ID for the TTY associated with the given handle.

fn tcsetattr(handle: fd_t, optional_action: TCSA, termios_p: termios) TermiosSetError!void

No documentation provided.

fn tcsetpgrp(handle: fd_t, pgrp: pid_t) TermioSetPgrpError!void

Sets the controlling process group ID for given TTY. handle must be valid fd_t …

Sets the controlling process group ID for given TTY. handle must be valid fd_t to a TTY associated with calling process. pgrp must be a valid process group, and the calling process must be a member of that group.

fn timerfd_create(clokid: i32, flags: u32) TimerFdCreateError!fd_t

No documentation provided.

fn timerfd_gettime(fd: i32) TimerFdGetError!linux.itimerspec

No documentation provided.

fn timerfd_settime(fd: i32, flags: u32, new_value: *const linux.itimerspec, old_value: ?*linux.itimerspec) TimerFdSetError!void

No documentation provided.

fn toPosixPath(file_path: []const u8) ![MAX_PATH_BYTES - 1:0]u8

Used to convert a slice to a null terminated slice on the stack. TODO https://g…

Used to convert a slice to a null terminated slice on the stack. TODO https://github.com/ziglang/zig/issues/287

fn uname() utsname

No documentation provided.

fn unexpectedErrno(err: E) UnexpectedError

Call this when you made a syscall or something that sets errno and you get an u…

Call this when you made a syscall or something that sets errno and you get an unexpected error.

fn unlink(file_path: []const u8) UnlinkError!void

Delete a name and possibly the file it refers to. See also unlinkZ.

fn unlinkW(file_path_w: []const u16) UnlinkError!void

Windows-only. Same as unlink except the parameter is null-terminated, WTF16 en…

Windows-only. Same as unlink except the parameter is null-terminated, WTF16 encoded.

fn unlinkZ(file_path: [*:0]const u8) UnlinkError!void

Same as unlink except the parameter is a null terminated UTF8-encoded string.

fn unlinkat(dirfd: fd_t, file_path: []const u8, flags: u32) UnlinkatError!void

Delete a file name and possibly the file it refers to, based on an open director…

Delete a file name and possibly the file it refers to, based on an open directory handle. Asserts that the path parameter has no null bytes.

fn unlinkatW(dirfd: fd_t, sub_path_w: []const u16, flags: u32) UnlinkatError!void

Same as unlinkat but sub_path_w is UTF16LE, NT prefixed. Windows only.

fn unlinkatWasi(dirfd: fd_t, file_path: []const u8, flags: u32) UnlinkatError!void

WASI-only. Same as unlinkat but targeting WASI. See also unlinkat.

fn unlinkatZ(dirfd: fd_t, file_path_c: [*:0]const u8, flags: u32) UnlinkatError!void

Same as unlinkat but file_path is a null-terminated string.

fn wait4(pid: pid_t, flags: u32, ru: ?*rusage) WaitPidResult

No documentation provided.

fn waitpid(pid: pid_t, flags: u32) WaitPidResult

Use this version of the waitpid wrapper if you spawned your child process usin…

Use this version of the waitpid wrapper if you spawned your child process using explicit fork and execve method.

fn write(fd: fd_t, bytes: []const u8) WriteError!usize

Write to a file descriptor. Retries when interrupted by a signal. Returns the …

Write to a file descriptor. Retries when interrupted by a signal. Returns the number of bytes written. If nonzero bytes were supplied, this will be nonzero.

Note that a successful write() may transfer fewer than count bytes. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before it had transferred all of the requested bytes. In the event of a partial write, the caller can make another write() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full).

For POSIX systems, if fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received. On Windows, if the application has a global event loop enabled, I/O Completion Ports are used to perform the I/O. error.WouldBlock is not possible on Windows.

Linux has a limit on how many bytes may be transferred in one write call, which is 0x7ffff000 on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as well as stuffing the errno codes into the last 4096 values. This is noted on the write man page. The limit on Darwin is 0x7fffffff, trying to read more than that returns EINVAL. The corresponding POSIX limit is math.maxInt(isize).

fn writev(fd: fd_t, iov: []const iovec_const) WriteError!usize

Write multiple buffers to a file descriptor. Retries when interrupted by a sign…

Write multiple buffers to a file descriptor. Retries when interrupted by a signal. Returns the number of bytes written. If nonzero bytes were supplied, this will be nonzero.

Note that a successful write() may transfer fewer bytes than supplied. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before it had transferred all of the requested bytes. In the event of a partial write, the caller can make another write() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full).

For POSIX systems, if fd is opened in non blocking mode, the function will return error.WouldBlock when EAGAIN is received. On Windows, if the application has a global event loop enabled, I/O Completion Ports are used to perform the I/O. error.WouldBlock is not possible on Windows.

If iov.len is larger than IOV_MAX, a partial write will occur.

This function assumes that all vectors, including zero-length vectors, have a pointer within the address space of the application.

Values

AF
undefined
AF_SUN
undefined
ARCH
undefined
AT
undefined
AT_SUN
undefined
AcceptError
type
AccessError
type
BindError
type
CLOCK
undefined
CPU_COUNT
undefined
CTL
undefined
ChangeCurDirError
type
ClockGetTimeError
type
ConnectError
type
CopyFileRangeError
type
DT
undefined
DeleteDirError
type
E
undefined
Elf_Symndx
undefined
EpollCreateError
type
EpollCtlError
type
EventFdError
type
ExecveError
type
F
undefined
FChmodError
type
FChownError
type
FD_CLOEXEC
undefined
FStatAtError
type
FStatError
type
F_OK
undefined
FchdirError
type
FcntlError
type
Flock
undefined
FlockError
type
ForkError
type
FutimensError
type
GetCwdError
type
GetHostNameError
type
GetRandomError
type
GetSockNameError
type
HOST_NAME_MAX
undefined
HW
type
IFNAMESIZE
undefined
INotifyAddWatchError
type
INotifyInitError
type
IOV_MAX
undefined
IPPROTO
undefined
IoCtl_SIOCGIFINDEX_Error
type
KERN
undefined
KQueueError
type
Kevent
undefined
KillError
type
LOCK
undefined
LinkError
type
LinkatError
type
ListenError
type
MADV
undefined
MAP
undefined
MAX_ADDR_LEN
undefined
MFD
undefined
MFD_MAX_NAME_LEN
type
MFD_NAME_PREFIX
*const [6:0]u8
MMAP2_UNIT
undefined
MMapError
type
MProtectError
type
MSF
undefined
MSG
undefined
MSyncError
type
MakeDirError
type
MemFdCreateError
type
MincoreError
type
NAME_MAX
undefined
O
type
OpenError
type
PATH_MAX
undefined
POLL
undefined
POSIX_FADV
undefined
PPollError
type
PR
undefined
PROT
undefined
PReadError
type
PWriteError
type
PerfEventOpenError
type
PipeError
type
PollError
type
PrctlError
type
PtraceError
type
REG
undefined
RIGHT
undefined
RLIM
undefined
RR
undefined
R_OK
undefined
ReadError
type
ReadLinkError
type
RealPathError
type
RebootCommand
type
RebootError
type
RecvFromError
type
RenameError
type
S
undefined
SA
undefined
SC
undefined
SEEK
undefined
SHUT
undefined
SIG
undefined
SIOCGIFINDEX
undefined
SO
undefined
SOCK
undefined
SOL
undefined
STDERR_FILENO
undefined
STDIN_FILENO
undefined
STDOUT_FILENO
undefined
SYS
undefined
SchedGetAffinityError
type
SeekError
type
SendError
type
SendFileError
type
SendMsgError
type
SendToError
type
SetEidError
type
SetIdError
type
SetSockOptError
type
SetrlimitError
type
ShutdownError
type
Sigaction
undefined
SigaltstackError
type
SocketError
type
Stat
undefined
SymLinkError
type
SyncError
type
SysCtlError
type
TCP
undefined
TCSA
undefined
TermioGetPgrpError
type
TermioSetPgrpError
type
TermiosGetError
type
TermiosSetError
type
TimerFdCreateError
type
TimerFdGetError
type
TimerFdSetError
type
TruncateError
type
UnlinkError
type
UnlinkatError
type
VDSO
undefined
W
undefined
W_OK
undefined
WriteError
type
X_OK
undefined
_SC
undefined
addrinfo
undefined
blkcnt_t
undefined
blksize_t
undefined
clock_t
undefined
cpu_set_t
undefined
dev_t
undefined
dl_phdr_info
undefined
empty_sigset
undefined
errno
undefined

To obtain errno, call this function with the return value of the system functio…

fd_t
undefined
fdflags_t
undefined
fdstat_t
undefined
file_obj
undefined
gid_t
undefined
have_sigpipe_support
bool
ifreq
undefined
ino_t
undefined
lookupflags_t
undefined
mcontext_t
undefined
mode_t
undefined
msghdr
undefined
msghdr_const
undefined
nfds_t
undefined
nlink_t
undefined
off_t
undefined
oflags_t
undefined
pid_t
undefined
pollfd
undefined
port_event
undefined
port_notify
undefined
port_t
undefined
rights_t
undefined
rlim_t
undefined
rlimit
undefined
rlimit_resource
undefined
rusage
undefined
sa_family_t
undefined
siginfo_t
undefined
sigset_t
undefined
sockaddr
undefined
socket_t
type
socklen_t
undefined
stack_t
undefined
system
type

Applications can override the system API layer in their root source file. Oth…

tcflag_t
undefined
termios
undefined
time_t
undefined
timespec
undefined
timestamp_t
undefined
timeval
undefined
timezone
undefined
ucontext_t
undefined
uid_t
undefined
unexpected_error_tracing
bool

Whether or not error.Unexpected will print its value and a stack trace. if this…

user_desc
undefined
utsname
undefined