Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/posix.zig

Source line 1

POSIX API layer.

This is more cross platform than using OS-specific APIs, however, it is lower-level and less portable than other namespaces such as std.Io and std.process.

These APIs are generally lowered to libc function calls if and only if libc is linked. Most operating systems other than Windows, Linux, and WASI require always linking libc because they use it as the stable syscall ABI.

std.posix._SC

constant

Source line 147

std.posix.ACCMODE

type

Source line 226

std.posix.addrinfo

constant

Source line 148

std.posix.AF

constant

Source line 72

std.posix.AF_SUN

constant

Source line 73

std.posix.AI

constant

Source line 74

std.posix.ARCH

constant

Source line 75

std.posix.assert

alias

Source line 18

Alias of std.debug.assert

std.posix.AT

constant

Source line 76

std.posix.AT_SUN

constant

Source line 77

std.posix.blkcnt_t

constant

Source line 149

std.posix.blksize_t

constant

Source line 150

std.posix.builtin

constant

Source line 10

std.posix.cast

alias

Source line 17

Alias of std.math.cast

std.posix.cc_t

constant

Source line 203

std.posix.CLOCK

constant

Source line 78

std.posix.clock_t

constant

Source line 151

std.posix.clockid_t

constant

Source line 152

std.posix.cmsg_align

constant

Source line 154

std.posix.cmsghdr

constant

Source line 153

std.posix.CPU_COUNT

constant

Source line 79

std.posix.cpu_set_t

constant

Source line 156

std.posix.CSIZE

constant

Source line 201

std.posix.CTL

constant

Source line 80

std.posix.dev_t

constant

Source line 157

std.posix.dl_iterate_phdr

function

Source line 785

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

Parameters

Error: type
callback: fn (info: *dl_phdr_info, size: usize, context: @TypeOf(context)) Error!void

std.posix.dl_iterate_phdr.callbackC

function

Source line 801

fn callbackC(info: *dl_phdr_info, size: usize, data: ?*anyopaque) callconv(.c) c_int

Parameters

info: *dl_phdr_info
size: usize
data: ?*anyopaque

std.posix.dl_phdr_info

constant

Source line 158

std.posix.DT

constant

Source line 81

std.posix.E

constant

Source line 82

std.posix.Elf_Symndx

constant

Source line 83

std.posix.errno

constant

Source line 298

Obtains errno from the return value of a system function call.

For some systems this will obtain the value directly from the syscall return value; for others it will use a thread-local errno variable. Therefore, this function only returns a well-defined value when it is called directly after the system function call whose errno value is intended to be observed.

std.posix.F

constant

Source line 84

std.posix.F_OK

constant

Source line 211

std.posix.fanotify_init

function

Source line 552

pub fn fanotify_init(flags: std.os.linux.fanotify.InitFlags, event_f_flags: u32) FanotifyInitError!i32

Parameters

flags: std.os.linux.fanotify.InitFlags
event_f_flags: u32

Errors

PermissionDenied
ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnsupportedFlags

The kernel does not recognize the flags passed, likely because it is an older version.

std.posix.fanotify_mark

function

Source line 579

pub fn fanotify_mark( fanotify_fd: fd_t, flags: std.os.linux.fanotify.MarkFlags, mask: std.os.linux.fanotify.MarkMask, dirfd: fd_t, pathname: ?[]const u8, ) FanotifyMarkError!void

Parameters

fanotify_fd: fd_t
flags: std.os.linux.fanotify.MarkFlags
mask: std.os.linux.fanotify.MarkMask
dirfd: fd_t
pathname: ?[]const u8

Errors

CrossDevice
FileNotFound
IsDir
MarkAlreadyExists
NameTooLong
NotAssociatedWithFileSystem
NotDir
OperationUnsupported
PermissionDenied
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UserMarkQuotaExceeded

std.posix.fanotify_markZ

function

Source line 594

pub fn fanotify_markZ( fanotify_fd: fd_t, flags: std.os.linux.fanotify.MarkFlags, mask: std.os.linux.fanotify.MarkMask, dirfd: fd_t, pathname: ?[*:0]const u8, ) FanotifyMarkError!void

Parameters

fanotify_fd: fd_t
flags: std.os.linux.fanotify.MarkFlags
mask: std.os.linux.fanotify.MarkMask
dirfd: fd_t
pathname: ?[*:0]const u8

Errors

CrossDevice
FileNotFound
IsDir
MarkAlreadyExists
NameTooLong
NotAssociatedWithFileSystem
NotDir
OperationUnsupported
PermissionDenied
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UserMarkQuotaExceeded

std.posix.FanotifyInitError

error-set

Source line 542

Errors

PermissionDenied
ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnsupportedFlags

The kernel does not recognize the flags passed, likely because it is an older version.

std.posix.FanotifyMarkError

error-set

Source line 565

Errors

CrossDevice
FileNotFound
IsDir
MarkAlreadyExists
NameTooLong
NotAssociatedWithFileSystem
NotDir
OperationUnsupported
PermissionDenied
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UserMarkQuotaExceeded

std.posix.FD_CLOEXEC

constant

Source line 85

std.posix.fd_t

constant

Source line 159

std.posix.fdatasync

function

Source line 1265

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

pub fn fdatasync(fd: fd_t) SyncError!void

Parameters

fd: fd_t

Errors

AccessDenied SyncError
Canceled Cancelable

Caller has requested the async operation to stop.

DiskQuota SyncError
InputOutput SyncError
NoSpaceLeft SyncError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.file_obj

constant

Source line 160

std.posix.Flock

constant

Source line 86

std.posix.gethostname

function

Source line 967

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

Parameters

name_buffer: *[HOST_NAME_MAX]u8

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.GetHostNameError

error-set

Source line 965

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.getpeername

function

Source line 523

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

Parameters

sock: socket_t
addr: *sockaddr
addrlen: *socklen_t

Errors

FileDescriptorNotASocket
NetworkDown

The network subsystem has failed.

SocketNotBound

Socket hasn't been bound yet

SocketUnconnected

The socket is not connected (connection-oriented sockets only).

SystemResources

Insufficient resources were available in the system to perform the operation.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.getppid

function

Source line 503

pub fn getppid() pid_t

std.posix.getrlimit

function

Source line 1321

pub fn getrlimit(resource: rlimit_resource) GetrlimitError!rlimit

Parameters

resource: rlimit_resource

Errors

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.GetrlimitError

alias

Source line 1319

Alias of std.posix.UnexpectedError

std.posix.getrusage

function

Source line 1150

pub fn getrusage(who: i32) rusage

Parameters

who: i32

std.posix.getSelfPhdrs

function

Source line 778

pub fn getSelfPhdrs() []std.elf.ElfN.Phdr

std.posix.GetSockNameError

error-set

Source line 507

Errors

FileDescriptorNotASocket
NetworkDown

The network subsystem has failed.

SocketNotBound

Socket hasn't been bound yet

SocketUnconnected

The socket is not connected (connection-oriented sockets only).

SystemResources

Insufficient resources were available in the system to perform the operation.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.gid_t

constant

Source line 161

std.posix.HOST_NAME_MAX

constant

Source line 87

std.posix.HW

constant

Source line 88

std.posix.IFF

constant

Source line 126

std.posix.IFNAMESIZE

constant

Source line 89

std.posix.ifreq

constant

Source line 162

std.posix.in_pktinfo

constant

Source line 163

std.posix.in6_pktinfo

constant

Source line 164

std.posix.ino_t

constant

Source line 165

std.posix.Io

alias

Source line 14

Alias of std.Io

std.posix.IOV_MAX

constant

Source line 90

std.posix.iovec

container

Source line 216

Fields

base: [*]u8
len: usize

std.posix.iovec_const

container

Source line 221

Fields

base: [*]const u8
len: usize

std.posix.IP

constant

Source line 91

std.posix.IPPROTO

constant

Source line 93

std.posix.IPTOS

constant

Source line 94

std.posix.IPV6

constant

Source line 92

std.posix.KERN

constant

Source line 95

std.posix.Kevent

constant

Source line 96

std.posix.kill

function

Source line 380

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

Parameters

pid: pid_t
sig: SIG

Errors

PermissionDenied
ProcessNotFound
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.KillError

error-set

Source line 378

Errors

PermissionDenied
ProcessNotFound
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.lfs64_abi

constant

Source line 1665

std.posix.linger

constant

Source line 166

std.posix.linux

alias

Source line 31

Alias of std.os.linux

std.posix.LOCK

namespace

Source line 264

std.posix.LOCK.EX

constant

Source line 266

std.posix.LOCK.NB

constant

Source line 267

std.posix.LOCK.SH

constant

Source line 265

std.posix.LOCK.UN

constant

Source line 268

std.posix.LOG

namespace

Source line 271

std.posix.LOG.ALERT

constant

Source line 275

action must be taken immediately

std.posix.LOG.CRIT

constant

Source line 277

critical conditions

std.posix.LOG.DEBUG

constant

Source line 287

debug-level messages

std.posix.LOG.EMERG

constant

Source line 273

system is unusable

std.posix.LOG.ERR

constant

Source line 279

error conditions

std.posix.LOG.INFO

constant

Source line 285

informational

std.posix.LOG.NOTICE

constant

Source line 283

normal but significant condition

std.posix.LOG.WARNING

constant

Source line 281

warning conditions

std.posix.MADV

constant

Source line 97

std.posix.madvise

function

Source line 1410

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

pub fn madvise(ptr: [*]align(page_size_min) u8, length: usize, advice: u32) MadviseError!void

Parameters

ptr: [*]align(page_size_min) u8
length: usize
advice: u32

Errors

AccessDenied

advice is MADV.REMOVE, but the specified address range is not a shared writable mapping.

InvalidSyscall

One of the following:

  • addr is not page-aligned or length is negative
  • advice is not valid
  • advice is MADV.DONTNEED or MADV.REMOVE and the specified address range includes locked, Huge TLB pages, or VM_PFNMAP pages.
  • advice is MADV.MERGEABLE or MADV.UNMERGEABLE, but the kernel was not configured with CONFIG_KSM.
  • advice is MADV.FREE or MADV.WIPEONFORK but the specified address range includes file, Huge TLB, MAP.SHARED, or VM_PFNMAP ranges.
MadviseUnavailable

The madvise syscall is not available on this version and configuration of the Linux kernel.

OutOfMemory

One of the following:

  • (for MADV.WILLNEED) Not enough memory: paging in failed.
  • Addresses in the specified range are not currently mapped, or are outside the address space of the process.
PermissionDenied

advice is MADV.HWPOISON, but the caller does not have the CAP_SYS_ADMIN capability.

SystemResources

A kernel resource was temporarily unavailable.

Unexpected

The operating system returned an undocumented error code.

WouldExceedMaximumResidentSetSize

(for MADV.WILLNEED) Paging in this area would exceed the process's maximum resident set size.

std.posix.MadviseError

error-set

Source line 1376

Errors

AccessDenied

advice is MADV.REMOVE, but the specified address range is not a shared writable mapping.

InvalidSyscall

One of the following:

  • addr is not page-aligned or length is negative
  • advice is not valid
  • advice is MADV.DONTNEED or MADV.REMOVE and the specified address range includes locked, Huge TLB pages, or VM_PFNMAP pages.
  • advice is MADV.MERGEABLE or MADV.UNMERGEABLE, but the kernel was not configured with CONFIG_KSM.
  • advice is MADV.FREE or MADV.WIPEONFORK but the specified address range includes file, Huge TLB, MAP.SHARED, or VM_PFNMAP ranges.
MadviseUnavailable

The madvise syscall is not available on this version and configuration of the Linux kernel.

OutOfMemory

One of the following:

  • (for MADV.WILLNEED) Not enough memory: paging in failed.
  • Addresses in the specified range are not currently mapped, or are outside the address space of the process.
PermissionDenied

advice is MADV.HWPOISON, but the caller does not have the CAP_SYS_ADMIN capability.

SystemResources

A kernel resource was temporarily unavailable.

Unexpected

The operating system returned an undocumented error code.

WouldExceedMaximumResidentSetSize

(for MADV.WILLNEED) Paging in this area would exceed the process's maximum resident set size.

std.posix.MAP

constant

Source line 98

std.posix.MAX_ADDR_LEN

constant

Source line 99

std.posix.maxInt

alias

Source line 16

Alias of std.math.maxInt

std.posix.MCL

constant

Source line 100

std.posix.mem

alias

Source line 15

Alias of std.mem

std.posix.memfd_create

function

Source line 1142

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

Parameters

name: []const u8
flags: u32

Errors

NameTooLong

Either the name provided exceeded NAME_MAX, or invalid flags were passed.

OutOfMemory
ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemOutdated
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.memfd_createZ

function

Source line 1107

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

Parameters

name: [*:0]const u8
flags: u32

Errors

NameTooLong

Either the name provided exceeded NAME_MAX, or invalid flags were passed.

OutOfMemory
ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemOutdated
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MemFdCreateError

error-set

Source line 1098

Errors

NameTooLong

Either the name provided exceeded NAME_MAX, or invalid flags were passed.

OutOfMemory
ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemOutdated
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MFD

constant

Source line 101

std.posix.mincore

function

Source line 1364

Determine whether pages are resident in memory.

pub fn mincore(ptr: [*]align(page_size_min) u8, length: usize, vec: [*]u8) MincoreError!void

Parameters

ptr: [*]align(page_size_min) u8
length: usize
vec: [*]u8

Errors

InvalidAddress

vec points to an invalid address.

InvalidSyscall

addr is not page-aligned.

MincoreUnavailable

The mincore syscall is not available on this version and configuration of this UNIX-like kernel.

OutOfMemory

One of the following:

  • length is greater than user space TASK_SIZE - addr
  • addr + length contains unmapped memory
SystemResources

A kernel resource was temporarily unavailable.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MincoreError

error-set

Source line 1347

Errors

InvalidAddress

vec points to an invalid address.

InvalidSyscall

addr is not page-aligned.

MincoreUnavailable

The mincore syscall is not available on this version and configuration of this UNIX-like kernel.

OutOfMemory

One of the following:

  • length is greater than user space TASK_SIZE - addr
  • addr + length contains unmapped memory
SystemResources

A kernel resource was temporarily unavailable.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MLOCK

constant

Source line 102

std.posix.mmap

function

Source line 644

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
pub fn mmap( ptr: ?[*]align(page_size_min) u8, length: usize, prot: PROT, flags: MAP, fd: fd_t, offset: u64, ) MMapError![]align(page_size_min) u8

Parameters

ptr: ?[*]align(page_size_min) u8
length: usize
prot: PROT
flags: MAP
fd: fd_t
offset: u64

Errors

AccessDenied

A file descriptor refers to a non-regular file. Or a file mapping was requested, but the file descriptor is not open for reading. Or MAP.SHARED was requested and PROT_WRITE is set, but the file descriptor is not open in RDWR mode. Or PROT_WRITE is set, but the file is append-only.

LockedMemoryLimitExceeded
MappingAlreadyExists

Using FIXED_NOREPLACE flag and the process has already mapped memory at the given address

MemoryMappingNotSupported

The underlying filesystem of the specified file does not support memory mapping.

OutOfMemory
PermissionDenied

The prot argument asks for PROT_EXEC but the mapped area belongs to a file on a filesystem that was mounted no-exec.

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MMapError

error-set

Source line 620

Errors

AccessDenied

A file descriptor refers to a non-regular file. Or a file mapping was requested, but the file descriptor is not open for reading. Or MAP.SHARED was requested and PROT_WRITE is set, but the file descriptor is not open in RDWR mode. Or PROT_WRITE is set, but the file is append-only.

LockedMemoryLimitExceeded
MappingAlreadyExists

Using FIXED_NOREPLACE flag and the process has already mapped memory at the given address

MemoryMappingNotSupported

The underlying filesystem of the specified file does not support memory mapping.

OutOfMemory
PermissionDenied

The prot argument asks for PROT_EXEC but the mapped area belongs to a file on a filesystem that was mounted no-exec.

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.mode_t

constant

Source line 167

std.posix.mremap

function

Source line 705

pub fn mremap( old_address: ?[*]align(page_size_min) u8, old_len: usize, new_len: usize, flags: system.MREMAP, new_address: ?[*]align(page_size_min) u8, ) MRemapError![]align(page_size_min) u8

Parameters

old_address: ?[*]align(page_size_min) u8
old_len: usize
new_len: usize
flags: system.MREMAP
new_address: ?[*]align(page_size_min) u8

Errors

InvalidSyscallParameters

Either a bug in the calling code, or the operating system abused the EINVAL error code.

LockedMemoryLimitExceeded
OutOfMemory
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MREMAP

constant

Source line 103

std.posix.MRemapError

error-set

Source line 697

Errors

InvalidSyscallParameters

Either a bug in the calling code, or the operating system abused the EINVAL error code.

LockedMemoryLimitExceeded
OutOfMemory
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.MSF

constant

Source line 104

std.posix.MSG

constant

Source line 105

std.posix.msghdr

constant

Source line 168

std.posix.msghdr_const

constant

Source line 169

std.posix.msync

function

Source line 736

pub fn msync(memory: []align(page_size_min) u8, flags: i32) MSyncError!void

Parameters

memory: []align(page_size_min) u8
flags: i32

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnmappedMemory

std.posix.MSyncError

error-set

Source line 731

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnmappedMemory

std.posix.munmap

function

Source line 686

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, NtFreeVirtualMemory, has this restriction.
pub fn munmap(memory: []align(page_size_min) const u8) void

Parameters

memory: []align(page_size_min) const u8

std.posix.NAME_MAX

constant

Source line 106

std.posix.name_to_handle_at

function

Source line 1635

pub fn name_to_handle_at( dirfd: fd_t, pathname: []const u8, handle: *std.os.linux.file_handle, mount_id: *i32, flags: u32, ) NameToFileHandleAtError!void

Parameters

dirfd: fd_t
pathname: []const u8
handle: *std.os.linux.file_handle
mount_id: *i32
flags: u32

Errors

FileNotFound
NameTooLong
NotDir
OperationUnsupported
Unexpected

std.posix.name_to_handle_atZ

function

Source line 1646

pub fn name_to_handle_atZ( dirfd: fd_t, pathname_z: [*:0]const u8, handle: *std.os.linux.file_handle, mount_id: *i32, flags: u32, ) NameToFileHandleAtError!void

Parameters

dirfd: fd_t
pathname_z: [*:0]const u8
handle: *std.os.linux.file_handle
mount_id: *i32
flags: u32

Errors

FileNotFound
NameTooLong
NotDir
OperationUnsupported
Unexpected

std.posix.NameToFileHandleAtError

error-set

Source line 1627

Errors

FileNotFound
NameTooLong
NotDir
OperationUnsupported
Unexpected

std.posix.native_os

constant

Source line 11

std.posix.NCCS

constant

Source line 202

std.posix.nfds_t

constant

Source line 170

std.posix.nlink_t

constant

Source line 171

std.posix.NSIG

constant

Source line 107

std.posix.O

constant

Source line 108

std.posix.off_t

constant

Source line 172

std.posix.openat

function

Source line 443

Open and possibly create a file. Keeps trying if it gets interrupted. file_path is relative to the open directory handle dir_fd. On Windows, file_path should be encoded as WTF-8. On WASI, file_path should be encoded as valid UTF-8. On other platforms, file_path is an opaque sequence of bytes with no particular encoding. See also openatZ.

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

Parameters

dir_fd: fd_t
file_path: []const u8
flags: O
mode: mode_t

Errors

AccessDenied OpenError

In WASI, this error may occur when the file descriptor does not hold the required rights to open a new resource relative to it.

AntivirusInterference OpenError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy OpenError
FileBusy OpenError

One of these three things:

  • pathname refers to an executable image which is currently being executed and write access was requested.
  • pathname refers to a file that is currently in use as a swap file, and the O_TRUNC flag was specified.
  • pathname refers to a file that is currently being read by the kernel (e.g., for module/firmware loading), and write access was requested.
FileLocksUnsupported OpenError
FileNotFound OpenError

Either:

  • One of the path components does not exist.
  • Cwd was used, but cwd has been deleted.
  • The path associated with the open directory handle has been deleted.
  • On macOS, multiple processes or threads raced to create the same file with O.EXCL set to false.
FileTooBig OpenError

The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.

IsDir OpenError

Either:

  • The path refers to a directory and write permissions were requested.
  • The path refers to a directory and allow_directory was set to false.
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound OpenError

On Windows, \\server or \\server\share was not found.

NoDevice OpenError
NoSpaceLeft OpenError

A new path cannot be created because the device has no room for the new file. This error is only reachable when the CREAT flag is provided.

NotDir OpenError

A component used as a directory in the path was not, in fact, a directory, or DIRECTORY was specified and the path was not a directory.

PathAlreadyExists OpenError

The path already exists and the CREAT and EXCL flags were provided.

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

The path exceeded max_path_bytes bytes. Insufficient kernel memory was available, or the named file is a FIFO and per-user hard limit on memory allocation for pipes has been reached.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock OpenError

Non-blocking was requested and the operation cannot return immediately.

std.posix.openatZ

function

Source line 459

Open and possibly create a file. Keeps trying if it gets interrupted. file_path is relative to the open directory handle dir_fd. On Windows, file_path should be encoded as WTF-8. On WASI, file_path should be encoded as valid UTF-8. On other platforms, file_path is an opaque sequence of bytes with no particular encoding. See also openat.

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

Parameters

dir_fd: fd_t
file_path: [*:0]const u8
flags: O
mode: mode_t

Errors

AccessDenied OpenError

In WASI, this error may occur when the file descriptor does not hold the required rights to open a new resource relative to it.

AntivirusInterference OpenError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy OpenError
FileBusy OpenError

One of these three things:

  • pathname refers to an executable image which is currently being executed and write access was requested.
  • pathname refers to a file that is currently in use as a swap file, and the O_TRUNC flag was specified.
  • pathname refers to a file that is currently being read by the kernel (e.g., for module/firmware loading), and write access was requested.
FileLocksUnsupported OpenError
FileNotFound OpenError

Either:

  • One of the path components does not exist.
  • Cwd was used, but cwd has been deleted.
  • The path associated with the open directory handle has been deleted.
  • On macOS, multiple processes or threads raced to create the same file with O.EXCL set to false.
FileTooBig OpenError

The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.

IsDir OpenError

Either:

  • The path refers to a directory and write permissions were requested.
  • The path refers to a directory and allow_directory was set to false.
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound OpenError

On Windows, \\server or \\server\share was not found.

NoDevice OpenError
NoSpaceLeft OpenError

A new path cannot be created because the device has no room for the new file. This error is only reachable when the CREAT flag is provided.

NotDir OpenError

A component used as a directory in the path was not, in fact, a directory, or DIRECTORY was specified and the path was not a directory.

PathAlreadyExists OpenError

The path already exists and the CREAT and EXCL flags were provided.

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

The path exceeded max_path_bytes bytes. Insufficient kernel memory was available, or the named file is a FIFO and per-user hard limit on memory allocation for pipes has been reached.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock OpenError

Non-blocking was requested and the operation cannot return immediately.

std.posix.OpenError

error-set

Source line 435

Errors

AccessDenied OpenError

In WASI, this error may occur when the file descriptor does not hold the required rights to open a new resource relative to it.

AntivirusInterference OpenError

On Windows, antivirus software is enabled by default. It can be disabled, but Windows Update sometimes ignores the user's preference and re-enables it. When enabled, antivirus software on Windows intercepts file system operations and makes them significantly slower in addition to possibly failing with this error code.

BadPathName PathNameError

File system cannot encode the requested file name bytes. Could be due to invalid WTF-8 on Windows, invalid UTF-8 on WASI, invalid characters on Windows, etc. Filesystem and operating specific.

Canceled Cancelable

Caller has requested the async operation to stop.

DeviceBusy OpenError
FileBusy OpenError

One of these three things:

  • pathname refers to an executable image which is currently being executed and write access was requested.
  • pathname refers to a file that is currently in use as a swap file, and the O_TRUNC flag was specified.
  • pathname refers to a file that is currently being read by the kernel (e.g., for module/firmware loading), and write access was requested.
FileLocksUnsupported OpenError
FileNotFound OpenError

Either:

  • One of the path components does not exist.
  • Cwd was used, but cwd has been deleted.
  • The path associated with the open directory handle has been deleted.
  • On macOS, multiple processes or threads raced to create the same file with O.EXCL set to false.
FileTooBig OpenError

The file is too large to be opened. This error is unreachable for 64-bit targets, as well as when opening directories.

IsDir OpenError

Either:

  • The path refers to a directory and write permissions were requested.
  • The path refers to a directory and allow_directory was set to false.
NameTooLong PathNameError

Returned when an insufficient buffer is provided that cannot fit the path name.

NetworkNotFound OpenError

On Windows, \\server or \\server\share was not found.

NoDevice OpenError
NoSpaceLeft OpenError

A new path cannot be created because the device has no room for the new file. This error is only reachable when the CREAT flag is provided.

NotDir OpenError

A component used as a directory in the path was not, in fact, a directory, or DIRECTORY was specified and the path was not a directory.

PathAlreadyExists OpenError

The path already exists and the CREAT and EXCL flags were provided.

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

The path exceeded max_path_bytes bytes. Insufficient kernel memory was available, or the named file is a FIFO and per-user hard limit on memory allocation for pipes has been reached.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock OpenError

Non-blocking was requested and the operation cannot return immediately.

std.posix.page_size_min

alias

Source line 19

Alias of std.heap.page_size_min

std.posix.PATH_MAX

constant

Source line 109

std.posix.perf_event_open

function

Source line 1479

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

Parameters

attr: *system.perf_event_attr
pid: pid_t
cpu: i32
group_fd: fd_t
flags: usize

Errors

DeviceBusy

Returned if another event already has exclusive access to the PMU.

EventNotSupported

Returned if an event requiring a specific hardware feature is requested but there is no hardware support. This includes re‐ questing low-skid events if not supported, branch tracing if it is not available, sampling if no PMU interrupt is available, and branch stacks for software events.

EventRequiresUnsupportedCpuFeature
PermissionDenied

Returned when the requested event requires CAP_SYS_ADMIN permis‐ sions (or a more permissive perf_event paranoid setting). Some common cases where an unprivileged process may encounter this error: attaching to a process owned by a different user; moni‐ toring all processes on a given CPU (i.e., specifying the pid argument as -1); and not setting exclude_kernel when the para‐ noid setting requires it. Also: Returned on many (but not all) architectures when an unsupported exclude_hv, exclude_idle, exclude_user, or exclude_kernel set‐ ting is specified. It can also happen, as with EACCES, when the requested event re‐ quires CAP_SYS_ADMIN permissions (or a more permissive perf_event paranoid setting). This includes setting a break‐ point on a kernel address, and (since Linux 3.13) setting a ker‐ nel function-trace tracepoint.

ProcessNotFound

Returned if attempting to attach to a process that does not exist.

ProcessResources

Each opened event uses one file descriptor. If a large number of events are opened, the per-process limit on the number of open file descriptors will be reached, and no more events can be created.

SampleMaxStackOverflow

Returned if PERF_SAMPLE_CALLCHAIN is requested and sam‐ ple_max_stack is larger than the maximum specified in /proc/sys/kernel/perf_event_max_stack.

SampleStackNotSupported

Returned if PERF_SAMPLE_STACK_USER is set in sample_type and it is not supported by hardware.

TooBig

Returned if the perf_event_attr size value is too small (smaller than PERF_ATTR_SIZE_VER0), too big (larger than the page size), or larger than the kernel supports and the extra bytes are not zero. When E2BIG is returned, the perf_event_attr size field is overwritten by the kernel to be the size of the structure it was expecting.

TooManyBreakpoints

Returned if you try to add more breakpoint events than supported by the hardware.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.PerfEventOpenError

error-set

Source line 1425

Errors

DeviceBusy

Returned if another event already has exclusive access to the PMU.

EventNotSupported

Returned if an event requiring a specific hardware feature is requested but there is no hardware support. This includes re‐ questing low-skid events if not supported, branch tracing if it is not available, sampling if no PMU interrupt is available, and branch stacks for software events.

EventRequiresUnsupportedCpuFeature
PermissionDenied

Returned when the requested event requires CAP_SYS_ADMIN permis‐ sions (or a more permissive perf_event paranoid setting). Some common cases where an unprivileged process may encounter this error: attaching to a process owned by a different user; moni‐ toring all processes on a given CPU (i.e., specifying the pid argument as -1); and not setting exclude_kernel when the para‐ noid setting requires it. Also: Returned on many (but not all) architectures when an unsupported exclude_hv, exclude_idle, exclude_user, or exclude_kernel set‐ ting is specified. It can also happen, as with EACCES, when the requested event re‐ quires CAP_SYS_ADMIN permissions (or a more permissive perf_event paranoid setting). This includes setting a break‐ point on a kernel address, and (since Linux 3.13) setting a ker‐ nel function-trace tracepoint.

ProcessNotFound

Returned if attempting to attach to a process that does not exist.

ProcessResources

Each opened event uses one file descriptor. If a large number of events are opened, the per-process limit on the number of open file descriptors will be reached, and no more events can be created.

SampleMaxStackOverflow

Returned if PERF_SAMPLE_CALLCHAIN is requested and sam‐ ple_max_stack is larger than the maximum specified in /proc/sys/kernel/perf_event_max_stack.

SampleStackNotSupported

Returned if PERF_SAMPLE_STACK_USER is set in sample_type and it is not supported by hardware.

TooBig

Returned if the perf_event_attr size value is too small (smaller than PERF_ATTR_SIZE_VER0), too big (larger than the page size), or larger than the kernel supports and the extra bytes are not zero. When E2BIG is returned, the perf_event_attr size field is overwritten by the kernel to be the size of the structure it was expecting.

TooManyBreakpoints

Returned if you try to add more breakpoint events than supported by the hardware.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.pid_t

constant

Source line 173

std.posix.poll

function

Source line 1005

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

Parameters

fds: []pollfd
timeout: i32

Errors

NetworkDown

The network subsystem has failed.

SystemResources

The kernel had no space to allocate file descriptor tables.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.POLL

constant

Source line 110

std.posix.PollError

error-set

Source line 997

Errors

NetworkDown

The network subsystem has failed.

SystemResources

The kernel had no space to allocate file descriptor tables.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.pollfd

constant

Source line 174

std.posix.port_event

constant

Source line 175

std.posix.port_notify

constant

Source line 176

std.posix.port_t

constant

Source line 177

std.posix.POSIX_FADV

constant

Source line 111

std.posix.ppoll

function

Source line 1032

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

Parameters

fds: []pollfd
timeout: ?*const timespec
mask: ?*const sigset_t

Errors

SignalInterrupt

The operation was interrupted by a delivery of a signal before it could complete.

SystemResources

The kernel had no space to allocate file descriptor tables.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.PPollError

error-set

Source line 1024

Errors

SignalInterrupt

The operation was interrupted by a delivery of a signal before it could complete.

SystemResources

The kernel had no space to allocate file descriptor tables.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.PR

constant

Source line 112

std.posix.prctl

function

Source line 1292

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

Parameters

option: PR

Errors

AccessDenied

Can only occur with PR_SET_SECCOMP/SECCOMP_MODE_FILTER or PR_SET_MM/PR_SET_MM_EXE_FILE

InvalidAddress
InvalidFileDescriptor

Can only occur with PR_SET_MM/PR_SET_MM_EXE_FILE

OperationUnsupported

Can only occur with PR_SET_FP_MODE

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnsupportedFeature

Can only occur with PR_SET_SPECULATION_CTRL, PR_MPX_ENABLE_MANAGEMENT, or PR_MPX_DISABLE_MANAGEMENT

std.posix.PrctlError

error-set

Source line 1277

Errors

AccessDenied

Can only occur with PR_SET_SECCOMP/SECCOMP_MODE_FILTER or PR_SET_MM/PR_SET_MM_EXE_FILE

InvalidAddress
InvalidFileDescriptor

Can only occur with PR_SET_MM/PR_SET_MM_EXE_FILE

OperationUnsupported

Can only occur with PR_SET_FP_MODE

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnsupportedFeature

Can only occur with PR_SET_SPECULATION_CTRL, PR_MPX_ENABLE_MANAGEMENT, or PR_MPX_DISABLE_MANAGEMENT

std.posix.PROT

constant

Source line 113

std.posix.ptrace

function

Source line 1523

pub fn ptrace(request: u32, pid: pid_t, addr: usize, data: usize) PtraceError!void

Parameters

request: u32
pid: pid_t
addr: usize
data: usize

Errors

DeadLock
DeviceBusy
InputOutput
NameTooLong
OperationUnsupported
OutOfMemory
PermissionDenied
ProcessNotFound
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.PtraceError

error-set

Source line 1512

Errors

DeadLock
DeviceBusy
InputOutput
NameTooLong
OperationUnsupported
OutOfMemory
PermissionDenied
ProcessNotFound
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.R_OK

constant

Source line 212

std.posix.raise

function

Source line 352

pub fn raise(sig: SIG) RaiseError!void

Parameters

sig: SIG

Errors

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.RaiseError

alias

Source line 350

Alias of std.posix.UnexpectedError

std.posix.read

function

Source line 402

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 maxInt(isize).

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

Parameters

fd: fd_t
buf: []u8

Errors

AccessDenied UnendingError

In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer UnendingError
InputOutput UnendingError
IsDir UnendingError

Trying to read a directory file descriptor as if it were a file.

LockViolation UnendingError

Unable to read file due to lock. Depending on the Io implementation, reading from a locked file may return this error, or may ignore the lock.

NotOpenForReading UnendingError

File was not opened with read capability.

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock UnendingError

Non-blocking has been enabled, and reading from the file descriptor would block.

std.posix.ReadError

alias

Source line 390

Alias of std.Io.File.Reader.Error

std.posix.reboot

function

Source line 318

pub fn reboot(cmd: RebootCommand) RebootError!void

Parameters

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.RebootCommand

type

Source line 304

std.posix.RebootError

error-set

Source line 300

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.RLIM

constant

Source line 114

std.posix.rlim_t

constant

Source line 178

std.posix.rlimit

constant

Source line 179

std.posix.rlimit_resource

constant

Source line 180

std.posix.rusage

constant

Source line 181

std.posix.S

constant

Source line 115

std.posix.SA

constant

Source line 116

std.posix.sa_family_t

constant

Source line 182

std.posix.SC

constant

Source line 117

std.posix.sched_getaffinity

function

Source line 857

pub fn sched_getaffinity(pid: pid_t) SchedGetAffinityError!cpu_set_t

Parameters

pid: pid_t

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SchedGetAffinityError

error-set

Source line 855

Errors

PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SCM

constant

Source line 118

std.posix.SEEK

constant

Source line 119

std.posix.setrlimit

function

Source line 1335

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

Parameters

resource: rlimit_resource
limits: rlimit

Errors

LimitTooBig
PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SetrlimitError

error-set

Source line 1333

Errors

LimitTooBig
PermissionDenied
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.setsockopt

function

Source line 1075

Set a socket's options.

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

Parameters

fd: socket_t
level: i32
optname: u32
opt: []const u8

Errors

AlreadyConnected

The socket is already connected, and a specified option cannot be set while the socket is connected.

FileDescriptorNotASocket
InvalidProtocolOption

The option is not supported by the protocol.

NetworkDown
NoDevice
OperationUnsupported
PermissionDenied

Setting the socket option requires more elevated permissions.

SocketNotBound
SystemResources

Insufficient resources are available in the system to complete the call.

TimeoutTooBig

The send and receive timeout values are too big to fit into the timeout fields in the socket structure.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SetSockOptError

error-set

Source line 1051

Errors

AlreadyConnected

The socket is already connected, and a specified option cannot be set while the socket is connected.

FileDescriptorNotASocket
InvalidProtocolOption

The option is not supported by the protocol.

NetworkDown
NoDevice
OperationUnsupported
PermissionDenied

Setting the socket option requires more elevated permissions.

SocketNotBound
SystemResources

Insufficient resources are available in the system to complete the call.

TimeoutTooBig

The send and receive timeout values are too big to fit into the timeout fields in the socket structure.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SHUT

constant

Source line 120

std.posix.SIG

constant

Source line 121

std.posix.sigaction

function

Source line 944

Examine and change a signal action.

pub fn sigaction(sig: SIG, noalias act: ?*const Sigaction, noalias oact: ?*Sigaction) void

Parameters

sig: SIG
act: ?*const Sigaction
oact: ?*Sigaction

std.posix.Sigaction

constant

Source line 131

std.posix.sigaddset

function

Source line 912

pub fn sigaddset(set: *sigset_t, sig: SIG) void

Parameters

set: *sigset_t
sig: SIG

std.posix.sigaltstack

function

Source line 877

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

Parameters

ss: ?*const stack_t
old_ss: ?*stack_t

Errors

PermissionDenied

Attempted to change the signal stack while it was active.

SizeTooSmall

The supplied stack size was less than MINSIGSTKSZ.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SigaltstackError

error-set

Source line 869

Errors

PermissionDenied

Attempted to change the signal stack while it was active.

SizeTooSmall

The supplied stack size was less than MINSIGSTKSZ.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.sigdelset

function

Source line 922

pub fn sigdelset(set: *sigset_t, sig: SIG) void

Parameters

set: *sigset_t
sig: SIG

std.posix.sigemptyset

function

Source line 901

Return an empty sigset_t.

pub fn sigemptyset() sigset_t

std.posix.sigfillset

function

Source line 889

Return a filled sigset_t.

pub fn sigfillset() sigset_t

std.posix.siginfo_t

constant

Source line 183

std.posix.sigismember

function

Source line 932

pub fn sigismember(set: *const sigset_t, sig: SIG) bool

Parameters

set: *const sigset_t
sig: SIG

std.posix.signalfd

function

Source line 1231

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

Parameters

fd: fd_t
mask: *const sigset_t
flags: u32

std.posix.sigprocmask

function

Source line 956

Sets the thread signal mask.

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

Parameters

flags: u32
set: ?*const sigset_t
oldset: ?*sigset_t

std.posix.sigrtmax

constant

Source line 186

std.posix.sigrtmin

constant

Source line 185

std.posix.sigset_t

constant

Source line 184

std.posix.SIOCGIFINDEX

constant

Source line 122

std.posix.SO

constant

Source line 123

std.posix.SOCK

constant

Source line 124

std.posix.sockaddr

constant

Source line 187

std.posix.socket_t

alias

Source line 290

Alias of std.posix.fd_t

std.posix.socklen_t

constant

Source line 188

std.posix.SOL

constant

Source line 125

std.posix.speed_t

constant

Source line 205

std.posix.stack_t

constant

Source line 189

std.posix.Stat

type

Source line 138

Windows has no concept of stat.

On Linux, the stat bits/wrappers are removed due to having to maintain the different varying stat structs per target and libc, leading to runtime errors. Users targeting Linux should add a comptime check and use statx, similar to how Io.File.stat does.

std.posix.std

alias

Source line 13

Alias of std

std.posix.STDERR_FILENO

constant

Source line 127

std.posix.STDIN_FILENO

constant

Source line 128

std.posix.STDOUT_FILENO

constant

Source line 129

std.posix.sync

function

Source line 1247

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

pub fn sync() void

std.posix.SyncError

alias

Source line 1244

Alias of std.Io.File.SyncError

std.posix.syncfs

function

Source line 1252

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

pub fn syncfs(fd: fd_t) SyncError!void

Parameters

fd: fd_t

Errors

AccessDenied SyncError
Canceled Cancelable

Caller has requested the async operation to stop.

DiskQuota SyncError
InputOutput SyncError
NoSpaceLeft SyncError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.SYS

constant

Source line 130

std.posix.sysctl

function

Source line 753

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

Parameters

name: []const c_int
oldp: ?*anyopaque
oldlenp: ?*usize
newp: ?*anyopaque
newlen: usize

Errors

NameTooLong
PermissionDenied
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownName

std.posix.SysCtlError

error-set

Source line 746

Errors

NameTooLong
PermissionDenied
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

UnknownName

std.posix.system

type

Source line 36

A libc-compatible API layer.

std.posix.system.blksize_t

type

Source line 49

std.posix.system.blksize_t

type

Source line 65

std.posix.system.fd_t

type

Source line 42

std.posix.system.fd_t

type

Source line 60

std.posix.system.gid_t

type

Source line 46

std.posix.system.gid_t

type

Source line 62

std.posix.system.IFNAMESIZE

constant

Source line 51

std.posix.system.IFNAMESIZE

constant

Source line 67

std.posix.system.ino_t

type

Source line 50

std.posix.system.ino_t

type

Source line 66

std.posix.system.mode_t

type

Source line 47

std.posix.system.mode_t

type

Source line 63

std.posix.system.NAME_MAX

constant

Source line 55

std.posix.system.nlink_t

type

Source line 48

std.posix.system.nlink_t

type

Source line 64

std.posix.system.pid_t

type

Source line 43

std.posix.system.pid_t

type

Source line 58

std.posix.system.pollfd

type

Source line 44

std.posix.system.pollfd

type

Source line 59

std.posix.system.SIG

type

Source line 52

std.posix.system.SIG

type

Source line 68

std.posix.system.uid_t

type

Source line 45

std.posix.system.uid_t

type

Source line 61

std.posix.T

constant

Source line 143

std.posix.tc_cflag_t

constant

Source line 208

std.posix.tc_iflag_t

constant

Source line 206

std.posix.tc_lflag_t

constant

Source line 209

std.posix.tc_oflag_t

constant

Source line 207

std.posix.tcgetattr

function

Source line 1165

pub fn tcgetattr(handle: fd_t) TermiosGetError!termios

Parameters

handle: fd_t

Errors

NotATerminal TIOCError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.tcgetpgrp

function

Source line 1197

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

pub fn tcgetpgrp(handle: fd_t) TermioGetPgrpError!pid_t

Parameters

handle: fd_t

Errors

NotATerminal TIOCError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.TCP

constant

Source line 144

std.posix.TCSA

container

Source line 250

Fields

NOW
DRAIN
FLUSH
_

std.posix.tcsetattr

function

Source line 1180

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

Parameters

handle: fd_t
optional_action: TCSA
termios_p: termios

Errors

NotATerminal TIOCError
ProcessOrphaned
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.tcsetpgrp

function

Source line 1217

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.

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

Parameters

handle: fd_t
pgrp: pid_t

Errors

NotAPgrpMember
NotATerminal TIOCError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.TermioGetPgrpError

error-set

Source line 1194

Errors

NotATerminal TIOCError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.termios

constant

Source line 200

std.posix.TermioSetPgrpError

error-set

Source line 1211

Errors

NotAPgrpMember
NotATerminal TIOCError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.TermiosGetError

error-set

Source line 1163

Errors

NotATerminal TIOCError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.TermiosSetError

error-set

Source line 1178

Errors

NotATerminal TIOCError
ProcessOrphaned
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.posix.time_t

constant

Source line 190

std.posix.timerfd_clockid_t

constant

Source line 155

std.posix.timespec

constant

Source line 191

std.posix.timestamp_t

constant

Source line 192

std.posix.timeval

constant

Source line 193

std.posix.timezone

constant

Source line 194

std.posix.TIOCError

error-set

Source line 1161

Errors

NotATerminal

std.posix.toPosixPath

function

Source line 1680

Used to convert a slice to a null terminated slice on the stack.

pub fn toPosixPath(file_path: []const u8) error{NameTooLong}![PATH_MAX - 1:0]u8

Parameters

file_path: []const u8

Errors

NameTooLong

std.posix.uid_t

constant

Source line 196

std.posix.uname

function

Source line 988

pub fn uname() utsname

std.posix.unexpectedErrno

function

Source line 1671

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

pub fn unexpectedErrno(err: E) UnexpectedError

Parameters

err: E

std.posix.UnexpectedError

alias

Source line 1667

Alias of std.Io.UnexpectedError

std.posix.use_libc

constant

Source line 26

Whether to use libc for the POSIX API layer.

std.posix.user_desc

constant

Source line 197

std.posix.UTIME

constant

Source line 195

std.posix.utsname

constant

Source line 198

std.posix.V

constant

Source line 204

std.posix.VDSO

constant

Source line 145

std.posix.W

constant

Source line 146

std.posix.W_OK

constant

Source line 213

std.posix.wasi

alias

Source line 33

Alias of std.os.wasi

std.posix.windows

alias

Source line 32

Alias of std.os.windows

std.posix.winsize

container

Source line 257

Fields

row: u16
col: u16
xpixel: u16
ypixel: u16

std.posix.X_OK

constant

Source line 214

Source code

std/posix.zig

//! POSIX API layer.
//!
//! This is more cross platform than using OS-specific APIs, however, it is
//! lower-level and less portable than other namespaces such as `std.Io` and
//! `std.process`.
//!
//! These APIs are generally lowered to libc function calls if and only if libc
//! is linked. Most operating systems other than Windows, Linux, and WASI
//! require always linking libc because they use it as the stable syscall ABI.
const builtin = @import("builtin");
const native_os = builtin.os.tag;

const std = @import("std.zig");
const Io = std.Io;
const mem = std.mem;
const maxInt = std.math.maxInt;
const cast = std.math.cast;
const assert = std.debug.assert;
const page_size_min = std.heap.page_size_min;

test {
    _ = @import("posix/test.zig");
}

/// Whether to use libc for the POSIX API layer.
const use_libc = builtin.link_libc or switch (native_os) {
    .windows, .wasi => true,
    else => false,
};

const linux = std.os.linux;
const windows = std.os.windows;
const wasi = std.os.wasi;

/// A libc-compatible API layer.
pub const system = if (use_libc)
    std.c
else switch (native_os) {
    .linux => linux,
    .plan9 => std.os.plan9,
    .psp => struct {
        pub const fd_t = i32;
        pub const pid_t = void;
        pub const pollfd = void;
        pub const uid_t = void;
        pub const gid_t = void;
        pub const mode_t = u32;
        pub const nlink_t = u32;
        pub const blksize_t = u32;
        pub const ino_t = u64;
        pub const IFNAMESIZE = {};
        pub const SIG = void;

        // https://github.com/pspdev/newlib/blob/9e0a073634ad73e8e088f2e071c55a9fe5d39709/newlib/libc/sys/psp/sys/dirent.h#L19
        pub const NAME_MAX = 255;
    },
    else => struct {
        pub const pid_t = void;
        pub const pollfd = void;
        pub const fd_t = void;
        pub const uid_t = void;
        pub const gid_t = void;
        pub const mode_t = u0;
        pub const nlink_t = u0;
        pub const blksize_t = void;
        pub const ino_t = void;
        pub const IFNAMESIZE = {};
        pub const SIG = void;
    },
};

pub const AF = system.AF;
pub const AF_SUN = system.AF_SUN;
pub const AI = system.AI;
pub const ARCH = system.ARCH;
pub const AT = system.AT;
pub const AT_SUN = system.AT_SUN;
pub const CLOCK = system.CLOCK;
pub const CPU_COUNT = system.CPU_COUNT;
pub const CTL = system.CTL;
pub const DT = system.DT;
pub const E = system.E;
pub const Elf_Symndx = system.Elf_Symndx;
pub const F = system.F;
pub const FD_CLOEXEC = system.FD_CLOEXEC;
pub const Flock = system.Flock;
pub const HOST_NAME_MAX = system.HOST_NAME_MAX;
pub const HW = system.HW;
pub const IFNAMESIZE = system.IFNAMESIZE;
pub const IOV_MAX = system.IOV_MAX;
pub const IP = system.IP;
pub const IPV6 = system.IPV6;
pub const IPPROTO = system.IPPROTO;
pub const IPTOS = system.IPTOS;
pub const KERN = system.KERN;
pub const Kevent = system.Kevent;
pub const MADV = system.MADV;
pub const MAP = system.MAP;
pub const MAX_ADDR_LEN = system.MAX_ADDR_LEN;
pub const MCL = system.MCL;
pub const MFD = system.MFD;
pub const MLOCK = system.MLOCK;
pub const MREMAP = system.MREMAP;
pub const MSF = system.MSF;
pub const MSG = system.MSG;
pub const NAME_MAX = system.NAME_MAX;
pub const NSIG = system.NSIG;
pub const O = system.O;
pub const PATH_MAX = system.PATH_MAX;
pub const POLL = system.POLL;
pub const POSIX_FADV = system.POSIX_FADV;
pub const PR = system.PR;
pub const PROT = system.PROT;
pub const RLIM = system.RLIM;
pub const S = system.S;
pub const SA = system.SA;
pub const SC = system.SC;
pub const SCM = system.SCM;
pub const SEEK = system.SEEK;
pub const SHUT = system.SHUT;
pub const SIG = system.SIG;
pub const SIOCGIFINDEX = system.SIOCGIFINDEX;
pub const SO = system.SO;
pub const SOCK = system.SOCK;
pub const SOL = system.SOL;
pub const IFF = system.IFF;
pub const STDERR_FILENO = system.STDERR_FILENO;
pub const STDIN_FILENO = system.STDIN_FILENO;
pub const STDOUT_FILENO = system.STDOUT_FILENO;
pub const SYS = system.SYS;
pub const Sigaction = system.Sigaction;
/// Windows has no concept of `stat`.
///
/// On Linux, the `stat` bits/wrappers are removed due to having to maintain
/// the different varying stat structs per target and libc, leading to runtime
/// errors. Users targeting Linux should add a comptime check and use statx,
/// similar to how `Io.File.stat` does.
pub const Stat = switch (native_os) {
    .windows => void,
    .linux => void,
    else => system.Stat,
};
pub const T = system.T;
pub const TCP = system.TCP;
pub const VDSO = system.VDSO;
pub const W = system.W;
pub const _SC = system._SC;
pub const addrinfo = system.addrinfo;
pub const blkcnt_t = system.blkcnt_t;
pub const blksize_t = system.blksize_t;
pub const clock_t = system.clock_t;
pub const clockid_t = system.clockid_t;
pub const cmsghdr = system.cmsghdr;
pub const cmsg_align = system.cmsg_align;
pub const timerfd_clockid_t = system.timerfd_clockid_t;
pub const cpu_set_t = system.cpu_set_t;
pub const dev_t = system.dev_t;
pub const dl_phdr_info = system.dl_phdr_info;
pub const fd_t = system.fd_t;
pub const file_obj = system.file_obj;
pub const gid_t = system.gid_t;
pub const ifreq = system.ifreq;
pub const in_pktinfo = system.in_pktinfo;
pub const in6_pktinfo = system.in6_pktinfo;
pub const ino_t = system.ino_t;
pub const linger = system.linger;
pub const mode_t = system.mode_t;
pub const msghdr = system.msghdr;
pub const msghdr_const = system.msghdr_const;
pub const nfds_t = system.nfds_t;
pub const nlink_t = system.nlink_t;
pub const off_t = system.off_t;
pub const pid_t = system.pid_t;
pub const pollfd = system.pollfd;
pub const port_event = system.port_event;
pub const port_notify = system.port_notify;
pub const port_t = system.port_t;
pub const rlim_t = system.rlim_t;
pub const rlimit = system.rlimit;
pub const rlimit_resource = system.rlimit_resource;
pub const rusage = system.rusage;
pub const sa_family_t = system.sa_family_t;
pub const siginfo_t = system.siginfo_t;
pub const sigset_t = system.sigset_t;
pub const sigrtmin = system.sigrtmin;
pub const sigrtmax = system.sigrtmax;
pub const sockaddr = system.sockaddr;
pub const socklen_t = system.socklen_t;
pub const stack_t = system.stack_t;
pub const time_t = system.time_t;
pub const timespec = system.timespec;
pub const timestamp_t = system.timestamp_t;
pub const timeval = system.timeval;
pub const timezone = system.timezone;
pub const UTIME = system.UTIME;
pub const uid_t = system.uid_t;
pub const user_desc = system.user_desc;
pub const utsname = system.utsname;

pub const termios = system.termios;
pub const CSIZE = system.CSIZE;
pub const NCCS = system.NCCS;
pub const cc_t = system.cc_t;
pub const V = system.V;
pub const speed_t = system.speed_t;
pub const tc_iflag_t = system.tc_iflag_t;
pub const tc_oflag_t = system.tc_oflag_t;
pub const tc_cflag_t = system.tc_cflag_t;
pub const tc_lflag_t = system.tc_lflag_t;

pub const F_OK = system.F_OK;
pub const R_OK = system.R_OK;
pub const W_OK = system.W_OK;
pub const X_OK = system.X_OK;

pub const iovec = extern struct {
    base: [*]u8,
    len: usize,
};

pub const iovec_const = extern struct {
    base: [*]const u8,
    len: usize,
};

pub const ACCMODE = switch (native_os) {
    // POSIX has a note about the access mode values:
    //
    // In historical implementations the value of O_RDONLY is zero. Because of
    // that, it is not possible to detect the presence of O_RDONLY and another
    // option. Future implementations should encode O_RDONLY and O_WRONLY as
    // bit flags so that: O_RDONLY | O_WRONLY == O_RDWR
    //
    // In practice SerenityOS is the only system supported by Zig that
    // implements this suggestion.
    // https://github.com/SerenityOS/serenity/blob/4adc51fdf6af7d50679c48b39362e062f5a3b2cb/Kernel/API/POSIX/fcntl.h#L28-L30
    .serenity => enum(u2) {
        NONE = 0,
        RDONLY = 1,
        WRONLY = 2,
        RDWR = 3,
    },
    else => enum(u2) {
        RDONLY = 0,
        WRONLY = 1,
        RDWR = 2,
    },
};

pub const TCSA = enum(c_uint) {
    NOW,
    DRAIN,
    FLUSH,
    _,
};

pub const winsize = extern struct {
    row: u16,
    col: u16,
    xpixel: u16,
    ypixel: u16,
};

pub const LOCK = struct {
    pub const SH = 1;
    pub const EX = 2;
    pub const NB = 4;
    pub const UN = 8;
};

pub const LOG = struct {
    /// system is unusable
    pub const EMERG = 0;
    /// action must be taken immediately
    pub const ALERT = 1;
    /// critical conditions
    pub const CRIT = 2;
    /// error conditions
    pub const ERR = 3;
    /// warning conditions
    pub const WARNING = 4;
    /// normal but significant condition
    pub const NOTICE = 5;
    /// informational
    pub const INFO = 6;
    /// debug-level messages
    pub const DEBUG = 7;
};

pub const socket_t = fd_t;

/// Obtains errno from the return value of a system function call.
///
/// For some systems this will obtain the value directly from the syscall return value;
/// for others it will use a thread-local errno variable. Therefore, this
/// function only returns a well-defined value when it is called directly after
/// the system function call whose errno value is intended to be observed.
pub const errno = system.errno;

pub const RebootError = error{
    PermissionDenied,
} || UnexpectedError;

pub const RebootCommand = switch (native_os) {
    .linux => union(linux.LINUX_REBOOT.CMD) {
        RESTART: void,
        HALT: void,
        CAD_ON: void,
        CAD_OFF: void,
        POWER_OFF: void,
        RESTART2: [*:0]const u8,
        SW_SUSPEND: void,
        KEXEC: void,
    },
    else => @compileError("Unsupported OS"),
};

pub fn reboot(cmd: RebootCommand) RebootError!void {
    switch (native_os) {
        .linux => {
            switch (linux.errno(linux.reboot(
                .MAGIC1,
                .MAGIC2,
                cmd,
                switch (cmd) {
                    .RESTART2 => |s| s,
                    else => null,
                },
            ))) {
                .SUCCESS => {},
                .PERM => return error.PermissionDenied,
                else => |err| return std.posix.unexpectedErrno(err),
            }
            switch (cmd) {
                .CAD_OFF => {},
                .CAD_ON => {},
                .SW_SUSPEND => {},

                .HALT => unreachable,
                .KEXEC => unreachable,
                .POWER_OFF => unreachable,
                .RESTART => unreachable,
                .RESTART2 => unreachable,
            }
        },
        else => @compileError("Unsupported OS"),
    }
}

pub const RaiseError = UnexpectedError;

pub fn raise(sig: SIG) RaiseError!void {
    if (builtin.link_libc) {
        switch (errno(system.raise(sig))) {
            .SUCCESS => return,
            else => |err| return unexpectedErrno(err),
        }
    }

    if (native_os == .linux) {
        // Block all signals so a `fork` (from a signal handler) between the gettid() and kill() syscalls
        // cannot trigger an extra, unexpected, inter-process signal.  Signal paranoia inherited from Musl.
        const filled = linux.sigfillset();
        var orig: sigset_t = undefined;
        sigprocmask(SIG.BLOCK, &filled, &orig);
        const rc = linux.tkill(linux.gettid(), sig);
        sigprocmask(SIG.SETMASK, &orig, null);

        switch (errno(rc)) {
            .SUCCESS => return,
            else => |err| return unexpectedErrno(err),
        }
    }

    @compileError("std.posix.raise unimplemented for this target");
}

pub const KillError = error{ ProcessNotFound, PermissionDenied } || UnexpectedError;

pub fn kill(pid: pid_t, sig: SIG) KillError!void {
    switch (errno(system.kill(pid, sig))) {
        .SUCCESS => return,
        .INVAL => unreachable, // invalid signal
        .PERM => return error.PermissionDenied,
        .SRCH => return error.ProcessNotFound,
        else => |err| return unexpectedErrno(err),
    }
}

pub const ReadError = std.Io.File.Reader.Error;

/// 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 `maxInt(isize)`.
pub fn read(fd: fd_t, buf: []u8) ReadError!usize {
    if (buf.len == 0) return 0;
    if (native_os == .windows) @compileError("unsupported OS");
    if (native_os == .wasi) @compileError("unsupported OS");

    // Prevents EINVAL.
    const max_count = switch (native_os) {
        .linux => 0x7ffff000,
        .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => maxInt(i32),
        else => maxInt(isize),
    };
    while (true) {
        const rc = system.read(fd, buf.ptr, @min(buf.len, max_count));
        switch (errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => continue,
            .INVAL => unreachable,
            .FAULT => unreachable,
            .AGAIN => return error.WouldBlock,
            .CANCELED => return error.Canceled,
            .BADF => return error.Unexpected, // use after free
            .IO => return error.InputOutput,
            .ISDIR => return error.IsDir,
            .NOBUFS => return error.SystemResources,
            .NOMEM => return error.SystemResources,
            .NOTCONN => return error.SocketUnconnected,
            .CONNRESET => return error.ConnectionResetByPeer,
            .TIMEDOUT => return error.Unexpected,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub const OpenError = std.Io.File.OpenError || error{WouldBlock};

/// Open and possibly create a file. Keeps trying if it gets interrupted.
/// `file_path` is relative to the open directory handle `dir_fd`.
/// On Windows, `file_path` should be encoded as [WTF-8](https://wtf-8.codeberg.page/).
/// On WASI, `file_path` should be encoded as valid UTF-8.
/// On other platforms, `file_path` is an opaque sequence of bytes with no particular encoding.
/// See also `openatZ`.
pub fn openat(dir_fd: fd_t, file_path: []const u8, flags: O, mode: mode_t) OpenError!fd_t {
    if (native_os == .windows) {
        @compileError("Windows does not support POSIX; use Windows-specific API or cross-platform std.fs API");
    } else if (native_os == .wasi and !builtin.link_libc) {
        @compileError("use std.Io instead");
    }
    const file_path_c = try toPosixPath(file_path);
    return openatZ(dir_fd, &file_path_c, flags, mode);
}

/// Open and possibly create a file. Keeps trying if it gets interrupted.
/// `file_path` is relative to the open directory handle `dir_fd`.
/// On Windows, `file_path` should be encoded as [WTF-8](https://wtf-8.codeberg.page/).
/// On WASI, `file_path` should be encoded as valid UTF-8.
/// On other platforms, `file_path` is an opaque sequence of bytes with no particular encoding.
/// See also `openat`.
pub fn openatZ(dir_fd: fd_t, file_path: [*:0]const u8, flags: O, mode: mode_t) OpenError!fd_t {
    if (native_os == .windows) {
        @compileError("Windows does not support POSIX; use Windows-specific API or cross-platform std.fs API");
    } else if (native_os == .wasi and !builtin.link_libc) {
        return openat(dir_fd, mem.sliceTo(file_path, 0), flags, mode);
    }

    const openat_sym = if (lfs64_abi) system.openat64 else system.openat;
    while (true) {
        const rc = openat_sym(dir_fd, file_path, flags, mode);
        switch (errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => continue,

            .FAULT => unreachable,
            .INVAL => return error.BadPathName,
            .BADF => unreachable,
            .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,
            .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,
            .ILSEQ => return error.BadPathName,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub fn getppid() pid_t {
    return system.getppid();
}

pub const GetSockNameError = error{
    /// Insufficient resources were available in the system to perform the operation.
    SystemResources,

    /// The network subsystem has failed.
    NetworkDown,

    /// Socket hasn't been bound yet
    SocketNotBound,

    FileDescriptorNotASocket,

    /// The socket is not connected (connection-oriented sockets only).
    SocketUnconnected,
} || UnexpectedError;

pub fn getpeername(sock: socket_t, addr: *sockaddr, addrlen: *socklen_t) GetSockNameError!void {
    if (native_os == .windows) {
        @compileError("use std.Io instead");
    } else {
        const rc = system.getpeername(sock, addr, addrlen);
        switch (errno(rc)) {
            .SUCCESS => return,
            else => |err| return unexpectedErrno(err),

            .BADF => unreachable, // always a race condition
            .FAULT => unreachable,
            .INVAL => unreachable, // invalid parameters
            .NOTSOCK => return error.FileDescriptorNotASocket,
            .NOBUFS => return error.SystemResources,
            .NOTCONN => return error.SocketUnconnected,
        }
    }
}

pub const FanotifyInitError = error{
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    SystemResources,
    PermissionDenied,
    /// The kernel does not recognize the flags passed, likely because it is an
    /// older version.
    UnsupportedFlags,
} || UnexpectedError;

pub fn fanotify_init(flags: std.os.linux.fanotify.InitFlags, event_f_flags: u32) FanotifyInitError!i32 {
    const rc = system.fanotify_init(flags, event_f_flags);
    switch (errno(rc)) {
        .SUCCESS => return @intCast(rc),
        .INVAL => return error.UnsupportedFlags,
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOMEM => return error.SystemResources,
        .PERM => return error.PermissionDenied,
        else => |err| return unexpectedErrno(err),
    }
}

pub const FanotifyMarkError = error{
    MarkAlreadyExists,
    IsDir,
    NotAssociatedWithFileSystem,
    FileNotFound,
    SystemResources,
    UserMarkQuotaExceeded,
    NotDir,
    OperationUnsupported,
    PermissionDenied,
    CrossDevice,
    NameTooLong,
} || UnexpectedError;

pub fn fanotify_mark(
    fanotify_fd: fd_t,
    flags: std.os.linux.fanotify.MarkFlags,
    mask: std.os.linux.fanotify.MarkMask,
    dirfd: fd_t,
    pathname: ?[]const u8,
) FanotifyMarkError!void {
    if (pathname) |path| {
        const path_c = try toPosixPath(path);
        return fanotify_markZ(fanotify_fd, flags, mask, dirfd, &path_c);
    } else {
        return fanotify_markZ(fanotify_fd, flags, mask, dirfd, null);
    }
}

pub fn fanotify_markZ(
    fanotify_fd: fd_t,
    flags: std.os.linux.fanotify.MarkFlags,
    mask: std.os.linux.fanotify.MarkMask,
    dirfd: fd_t,
    pathname: ?[*:0]const u8,
) FanotifyMarkError!void {
    const rc = system.fanotify_mark(fanotify_fd, flags, mask, dirfd, pathname);
    switch (errno(rc)) {
        .SUCCESS => return,
        .BADF => unreachable,
        .EXIST => return error.MarkAlreadyExists,
        .INVAL => unreachable,
        .ISDIR => return error.IsDir,
        .NODEV => return error.NotAssociatedWithFileSystem,
        .NOENT => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .NOSPC => return error.UserMarkQuotaExceeded,
        .NOTDIR => return error.NotDir,
        .OPNOTSUPP => return error.OperationUnsupported,
        .PERM => return error.PermissionDenied,
        .XDEV => return error.CrossDevice,
        else => |err| return unexpectedErrno(err),
    }
}

pub const MMapError = error{
    /// The underlying filesystem of the specified file does not support memory mapping.
    MemoryMappingNotSupported,
    /// A file descriptor refers to a non-regular file. Or a file mapping was requested,
    /// but the file descriptor is not open for reading. Or `MAP.SHARED` was requested
    /// and `PROT_WRITE` is set, but the file descriptor is not open in `RDWR` mode.
    /// Or `PROT_WRITE` is set, but the file is append-only.
    AccessDenied,
    /// The `prot` argument asks for `PROT_EXEC` but the mapped area belongs to a file on
    /// a filesystem that was mounted no-exec.
    PermissionDenied,
    LockedMemoryLimitExceeded,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    OutOfMemory,
    /// Using FIXED_NOREPLACE flag and the process has already mapped memory at the given address
    MappingAlreadyExists,
} || UnexpectedError;

/// 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
pub fn mmap(
    ptr: ?[*]align(page_size_min) u8,
    length: usize,
    prot: PROT,
    flags: MAP,
    fd: fd_t,
    offset: u64,
) MMapError![]align(page_size_min) u8 {
    const mmap_sym = if (lfs64_abi) system.mmap64 else system.mmap;
    const rc = mmap_sym(ptr, length, prot, @bitCast(flags), fd, @bitCast(offset));
    const err: E = if (builtin.link_libc) blk: {
        if (rc != std.c.MAP_FAILED) return @as([*]align(page_size_min) u8, @ptrCast(@alignCast(rc)))[0..length];
        break :blk @fromBackingInt(@intCast(system._errno().*));
    } else blk: {
        const err = errno(rc);
        if (err == .SUCCESS) return @as([*]align(page_size_min) u8, @ptrFromInt(rc))[0..length];
        break :blk err;
    };
    switch (err) {
        .SUCCESS => unreachable,
        .TXTBSY => return error.AccessDenied,
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .AGAIN => return error.LockedMemoryLimitExceeded,
        .BADF => unreachable, // Always a race condition.
        .OVERFLOW => unreachable, // The number of pages used for length + offset would overflow.
        .NODEV => return error.MemoryMappingNotSupported,
        .INVAL => unreachable, // Invalid parameters to mmap()
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOMEM => return error.OutOfMemory,
        .EXIST => return error.MappingAlreadyExists,
        else => return unexpectedErrno(err),
    }
}

/// 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, NtFreeVirtualMemory, has this restriction.
pub fn munmap(memory: []align(page_size_min) const u8) void {
    switch (errno(system.munmap(memory.ptr, memory.len))) {
        .SUCCESS => return,
        .INVAL => unreachable, // Invalid parameters.
        .NOMEM => unreachable, // Attempted to unmap a region in the middle of an existing mapping.
        else => |e| if (std.options.unexpected_error_tracing) {
            std.debug.panic("unexpected errno: {d} ({t})", .{ @backingInt(e), e });
        } else unreachable,
    }
}

pub const MRemapError = error{
    LockedMemoryLimitExceeded,
    /// Either a bug in the calling code, or the operating system abused the
    /// EINVAL error code.
    InvalidSyscallParameters,
    OutOfMemory,
} || UnexpectedError;

pub fn mremap(
    old_address: ?[*]align(page_size_min) u8,
    old_len: usize,
    new_len: usize,
    flags: system.MREMAP,
    new_address: ?[*]align(page_size_min) u8,
) MRemapError![]align(page_size_min) u8 {
    const rc = system.mremap(old_address, old_len, new_len, flags, new_address);
    const err: E = if (builtin.link_libc) blk: {
        if (rc != std.c.MAP_FAILED) return @as([*]align(page_size_min) u8, @ptrCast(@alignCast(rc)))[0..new_len];
        break :blk @fromBackingInt(@intCast(system._errno().*));
    } else blk: {
        const err = errno(rc);
        if (err == .SUCCESS) return @as([*]align(page_size_min) u8, @ptrFromInt(rc))[0..new_len];
        break :blk err;
    };
    switch (err) {
        .SUCCESS => unreachable,
        .AGAIN => return error.LockedMemoryLimitExceeded,
        .INVAL => return error.InvalidSyscallParameters,
        .NOMEM => return error.OutOfMemory,
        .FAULT => unreachable,
        else => return unexpectedErrno(err),
    }
}

pub const MSyncError = error{
    UnmappedMemory,
    PermissionDenied,
} || UnexpectedError;

pub fn msync(memory: []align(page_size_min) u8, flags: i32) MSyncError!void {
    switch (errno(system.msync(memory.ptr, memory.len, flags))) {
        .SUCCESS => return,
        .PERM => return error.PermissionDenied,
        .NOMEM => return error.UnmappedMemory, // Unsuccessful, provided pointer does not point mapped memory
        .INVAL => unreachable, // Invalid parameters.
        else => unreachable,
    }
}

pub const SysCtlError = error{
    PermissionDenied,
    SystemResources,
    NameTooLong,
    UnknownName,
} || UnexpectedError;

pub fn sysctl(
    name: []const c_int,
    oldp: ?*anyopaque,
    oldlenp: ?*usize,
    newp: ?*anyopaque,
    newlen: usize,
) SysCtlError!void {
    if (native_os == .wasi) {
        @compileError("sysctl not supported on WASI");
    }
    if (native_os == .haiku) {
        @compileError("sysctl not supported on Haiku");
    }

    const name_len = cast(c_uint, name.len) orelse return error.NameTooLong;
    switch (errno(system.sysctl(name.ptr, name_len, oldp, oldlenp, newp, newlen))) {
        .SUCCESS => return,
        .FAULT => unreachable,
        .PERM => return error.PermissionDenied,
        .NOMEM => return error.SystemResources,
        .NOENT => return error.UnknownName,
        else => |err| return unexpectedErrno(err),
    }
}

pub fn getSelfPhdrs() []std.elf.ElfN.Phdr {
    const getauxval = if (builtin.link_libc) std.c.getauxval else std.os.linux.getauxval;
    assert(getauxval(std.elf.AT.PHENT) == @sizeOf(std.elf.ElfN.Phdr));
    const phdrs: [*]std.elf.ElfN.Phdr = @ptrFromInt(getauxval(std.elf.AT.PHDR));
    return phdrs[0..getauxval(std.elf.AT.PHNUM)];
}

pub fn dl_iterate_phdr(
    context: anytype,
    comptime Error: type,
    comptime callback: fn (info: *dl_phdr_info, size: usize, context: @TypeOf(context)) Error!void,
) Error!void {
    const Context = @TypeOf(context);
    const elf = std.elf;
    const dl = @import("dynamic_library.zig");

    switch (builtin.object_format) {
        .elf, .c => {},
        else => @compileError("dl_iterate_phdr is not available for this target"),
    }

    if (builtin.link_libc) {
        switch (system.dl_iterate_phdr(struct {
            fn callbackC(info: *dl_phdr_info, size: usize, data: ?*anyopaque) callconv(.c) c_int {
                const context_ptr: *const Context = @ptrCast(@alignCast(data));
                callback(info, size, context_ptr.*) catch |err| return @intFromError(err);
                return 0;
            }
        }.callbackC, @ptrCast(@constCast(&context)))) {
            0 => return,
            else => |err| return @as(Error, @errorCast(@errorFromInt(@as(@Int(.unsigned, @bitSizeOf(anyerror)), @intCast(err))))),
        }
    }

    var it = dl.linkmap_iterator() catch unreachable;

    // The executable has no dynamic link segment, create a single entry for
    // the whole ELF image.
    if (it.end()) {
        const getauxval = if (builtin.link_libc) std.c.getauxval else std.os.linux.getauxval;
        const phdrs = getSelfPhdrs();
        var info: dl_phdr_info = .{
            .addr = for (phdrs) |phdr| switch (phdr.type) {
                .PHDR => break @intFromPtr(phdrs.ptr) - phdr.vaddr,
                else => {},
            } else unreachable,
            .name = switch (getauxval(std.elf.AT.EXECFN)) {
                0 => "/proc/self/exe",
                else => |name| @ptrFromInt(name),
            },
            .phdr = phdrs.ptr,
            .phnum = @intCast(phdrs.len),
        };

        return callback(&info, @sizeOf(dl_phdr_info), context);
    }

    // Last return value from the callback function.
    while (it.next()) |entry| {
        const phdrs: []elf.ElfN.Phdr = if (entry.addr != 0) phdrs: {
            const ehdr: *elf.ElfN.Ehdr = @ptrFromInt(entry.addr);
            assert(mem.eql(u8, &ehdr.ident.magic, elf.MAGIC));
            const phdrs: [*]elf.ElfN.Phdr = @ptrFromInt(entry.addr + ehdr.phoff);
            break :phdrs phdrs[0..ehdr.phnum];
        } else getSelfPhdrs();

        var info: dl_phdr_info = .{
            .addr = entry.addr,
            .name = entry.name,
            .phdr = phdrs.ptr,
            .phnum = @intCast(phdrs.len),
        };

        try callback(&info, @sizeOf(dl_phdr_info), context);
    }
}

pub const SchedGetAffinityError = error{PermissionDenied} || UnexpectedError;

pub fn sched_getaffinity(pid: pid_t) SchedGetAffinityError!cpu_set_t {
    var set: cpu_set_t = undefined;
    switch (errno(system.sched_getaffinity(pid, @sizeOf(cpu_set_t), &set))) {
        .SUCCESS => return set,
        .FAULT => unreachable,
        .INVAL => unreachable,
        .SRCH => unreachable,
        .PERM => return error.PermissionDenied,
        else => |err| return unexpectedErrno(err),
    }
}

pub const SigaltstackError = error{
    /// The supplied stack size was less than MINSIGSTKSZ.
    SizeTooSmall,

    /// Attempted to change the signal stack while it was active.
    PermissionDenied,
} || UnexpectedError;

pub fn sigaltstack(ss: ?*const stack_t, old_ss: ?*stack_t) SigaltstackError!void {
    switch (errno(system.sigaltstack(ss, old_ss))) {
        .SUCCESS => return,
        .FAULT => unreachable,
        .INVAL => unreachable,
        .NOMEM => return error.SizeTooSmall,
        .PERM => return error.PermissionDenied,
        else => |err| return unexpectedErrno(err),
    }
}

/// Return a filled sigset_t.
pub fn sigfillset() sigset_t {
    if (builtin.link_libc) {
        var set: sigset_t = undefined;
        switch (errno(system.sigfillset(&set))) {
            .SUCCESS => return set,
            else => unreachable,
        }
    }
    return system.sigfillset();
}

/// Return an empty sigset_t.
pub fn sigemptyset() sigset_t {
    if (builtin.link_libc) {
        var set: sigset_t = undefined;
        switch (errno(system.sigemptyset(&set))) {
            .SUCCESS => return set,
            else => unreachable,
        }
    }
    return system.sigemptyset();
}

pub fn sigaddset(set: *sigset_t, sig: SIG) void {
    if (builtin.link_libc) {
        switch (errno(system.sigaddset(set, sig))) {
            .SUCCESS => return,
            else => unreachable,
        }
    }
    system.sigaddset(set, sig);
}

pub fn sigdelset(set: *sigset_t, sig: SIG) void {
    if (builtin.link_libc) {
        switch (errno(system.sigdelset(set, sig))) {
            .SUCCESS => return,
            else => unreachable,
        }
    }
    system.sigdelset(set, sig);
}

pub fn sigismember(set: *const sigset_t, sig: SIG) bool {
    if (builtin.link_libc) {
        const rc = system.sigismember(set, sig);
        switch (errno(rc)) {
            .SUCCESS => return rc == 1,
            else => unreachable,
        }
    }
    return system.sigismember(set, sig);
}

/// Examine and change a signal action.
pub fn sigaction(sig: SIG, noalias act: ?*const Sigaction, noalias oact: ?*Sigaction) void {
    switch (errno(system.sigaction(sig, act, oact))) {
        .SUCCESS => return,
        // EINVAL means the signal is either invalid or some signal that cannot have its action
        // changed. For POSIX, this means SIGKILL/SIGSTOP. For e.g. illumos, this also includes the
        // non-standard SIGWAITING, SIGCANCEL, and SIGLWP. Either way, programmer error.
        .INVAL => unreachable,
        else => unreachable,
    }
}

/// Sets the thread signal mask.
pub fn sigprocmask(flags: u32, noalias set: ?*const sigset_t, noalias oldset: ?*sigset_t) void {
    switch (errno(system.sigprocmask(@bitCast(flags), set, oldset))) {
        .SUCCESS => return,
        .FAULT => unreachable,
        .INVAL => unreachable,
        else => unreachable,
    }
}

pub const GetHostNameError = error{PermissionDenied} || UnexpectedError;

pub fn gethostname(name_buffer: *[HOST_NAME_MAX]u8) GetHostNameError![]u8 {
    if (builtin.link_libc) {
        switch (errno(system.gethostname(name_buffer, name_buffer.len))) {
            .SUCCESS => return mem.sliceTo(name_buffer, 0),
            .FAULT => unreachable,
            .NAMETOOLONG => unreachable, // HOST_NAME_MAX prevents this
            .PERM => return error.PermissionDenied,
            else => |err| return unexpectedErrno(err),
        }
    }
    if (native_os == .linux) {
        const uts = uname();
        const hostname = mem.sliceTo(&uts.nodename, 0);
        const result = name_buffer[0..hostname.len];
        @memcpy(result, hostname);
        return result;
    }

    @compileError("TODO implement gethostname for this OS");
}

pub fn uname() utsname {
    var uts: utsname = undefined;
    switch (errno(system.uname(&uts))) {
        .SUCCESS => return uts,
        .FAULT => unreachable,
        else => unreachable,
    }
}

pub const PollError = error{
    /// The network subsystem has failed.
    NetworkDown,

    /// The kernel had no space to allocate file descriptor tables.
    SystemResources,
} || UnexpectedError;

pub fn poll(fds: []pollfd, timeout: i32) PollError!usize {
    if (native_os == .windows) {
        @compileError("use std.Io instead");
    }
    while (true) {
        const fds_count = cast(nfds_t, fds.len) orelse return error.SystemResources;
        const rc = system.poll(fds.ptr, fds_count, timeout);
        switch (errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .FAULT => unreachable,
            .INTR => continue,
            .INVAL => unreachable,
            .NOMEM => return error.SystemResources,
            else => |err| return unexpectedErrno(err),
        }
    }
    unreachable;
}

pub const PPollError = error{
    /// The operation was interrupted by a delivery of a signal before it could complete.
    SignalInterrupt,

    /// The kernel had no space to allocate file descriptor tables.
    SystemResources,
} || UnexpectedError;

pub fn ppoll(fds: []pollfd, timeout: ?*const timespec, mask: ?*const sigset_t) PPollError!usize {
    var ts: timespec = undefined;
    var ts_ptr: ?*timespec = null;
    if (timeout) |timeout_ns| {
        ts_ptr = &ts;
        ts = timeout_ns.*;
    }
    const fds_count = cast(nfds_t, fds.len) orelse return error.SystemResources;
    const rc = system.ppoll(fds.ptr, fds_count, ts_ptr, mask);
    switch (errno(rc)) {
        .SUCCESS => return @intCast(rc),
        .FAULT => unreachable,
        .INTR => return error.SignalInterrupt,
        .INVAL => unreachable,
        .NOMEM => return error.SystemResources,
        else => |err| return unexpectedErrno(err),
    }
}

pub const SetSockOptError = error{
    /// The socket is already connected, and a specified option cannot be set while the socket is connected.
    AlreadyConnected,

    /// The option is not supported by the protocol.
    InvalidProtocolOption,

    /// The send and receive timeout values are too big to fit into the timeout fields in the socket structure.
    TimeoutTooBig,

    /// Insufficient resources are available in the system to complete the call.
    SystemResources,

    /// Setting the socket option requires more elevated permissions.
    PermissionDenied,

    OperationUnsupported,
    NetworkDown,
    FileDescriptorNotASocket,
    SocketNotBound,
    NoDevice,
} || UnexpectedError;

/// Set a socket's options.
pub fn setsockopt(fd: socket_t, level: i32, optname: u32, opt: []const u8) SetSockOptError!void {
    if (native_os == .windows) {
        @compileError("use std.Io instead");
    } else {
        switch (errno(system.setsockopt(fd, level, optname, opt.ptr, @intCast(opt.len)))) {
            .SUCCESS => {},
            .BADF => unreachable, // always a race condition
            .NOTSOCK => unreachable, // always a race condition
            .INVAL => unreachable,
            .FAULT => unreachable,
            .DOM => return error.TimeoutTooBig,
            .ISCONN => return error.AlreadyConnected,
            .NOPROTOOPT => return error.InvalidProtocolOption,
            .NOMEM => return error.SystemResources,
            .NOBUFS => return error.SystemResources,
            .PERM => return error.PermissionDenied,
            .NODEV => return error.NoDevice,
            .OPNOTSUPP => return error.OperationUnsupported,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub const MemFdCreateError = error{
    SystemFdQuotaExceeded,
    ProcessFdQuotaExceeded,
    OutOfMemory,
    /// Either the name provided exceeded `NAME_MAX`, or invalid flags were passed.
    NameTooLong,
    SystemOutdated,
} || UnexpectedError;

pub fn memfd_createZ(name: [*:0]const u8, flags: u32) MemFdCreateError!fd_t {
    switch (native_os) {
        .linux => {
            // memfd_create is available only in glibc versions starting with 2.27 and bionic versions starting with 30.
            const use_c = std.c.versionCheck(if (builtin.abi.isAndroid()) .{ .major = 30, .minor = 0, .patch = 0 } else .{ .major = 2, .minor = 27, .patch = 0 });
            const sys = if (use_c) std.c else linux;
            const rc = sys.memfd_create(name, flags);
            switch (sys.errno(rc)) {
                .SUCCESS => return @intCast(rc),
                .FAULT => unreachable, // name has invalid memory
                .INVAL => return error.NameTooLong, // or, program has a bug and flags are faulty
                .NFILE => return error.SystemFdQuotaExceeded,
                .MFILE => return error.ProcessFdQuotaExceeded,
                .NOMEM => return error.OutOfMemory,
                else => |err| return unexpectedErrno(err),
            }
        },
        .freebsd => {
            if (comptime builtin.os.version_range.semver.max.order(.{ .major = 13, .minor = 0, .patch = 0 }) == .lt)
                @compileError("memfd_create is unavailable on FreeBSD < 13.0");
            const rc = system.memfd_create(name, flags);
            switch (errno(rc)) {
                .SUCCESS => return rc,
                .BADF => unreachable, // name argument NULL
                .INVAL => unreachable, // name too long or invalid/unsupported flags.
                .MFILE => return error.ProcessFdQuotaExceeded,
                .NFILE => return error.SystemFdQuotaExceeded,
                .NOSYS => return error.SystemOutdated,
                else => |err| return unexpectedErrno(err),
            }
        },
        else => @compileError("target OS does not support memfd_create()"),
    }
}

pub fn memfd_create(name: []const u8, flags: u32) MemFdCreateError!fd_t {
    var buffer: [NAME_MAX - "memfd:".len - 1:0]u8 = undefined;
    if (name.len > buffer.len) return error.NameTooLong;
    @memcpy(buffer[0..name.len], name);
    buffer[name.len] = 0;
    return memfd_createZ(&buffer, flags);
}

pub fn getrusage(who: i32) rusage {
    var result: rusage = undefined;
    const rc = system.getrusage(who, &result);
    switch (errno(rc)) {
        .SUCCESS => return result,
        .INVAL => unreachable,
        .FAULT => unreachable,
        else => unreachable,
    }
}

pub const TIOCError = error{NotATerminal};

pub const TermiosGetError = TIOCError || UnexpectedError;

pub fn tcgetattr(handle: fd_t) TermiosGetError!termios {
    while (true) {
        var term: termios = undefined;
        switch (errno(system.tcgetattr(handle, &term))) {
            .SUCCESS => return term,
            .INTR => continue,
            .BADF => unreachable,
            .NOTTY => return error.NotATerminal,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub const TermiosSetError = TermiosGetError || error{ProcessOrphaned};

pub fn tcsetattr(handle: fd_t, optional_action: TCSA, termios_p: termios) TermiosSetError!void {
    while (true) {
        switch (errno(system.tcsetattr(handle, optional_action, &termios_p))) {
            .SUCCESS => return,
            .BADF => unreachable,
            .INTR => continue,
            .INVAL => unreachable,
            .NOTTY => return error.NotATerminal,
            .IO => return error.ProcessOrphaned,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub const TermioGetPgrpError = TIOCError || UnexpectedError;

/// Returns the process group ID for the TTY associated with the given handle.
pub fn tcgetpgrp(handle: fd_t) TermioGetPgrpError!pid_t {
    while (true) {
        var pgrp: pid_t = undefined;
        switch (errno(system.tcgetpgrp(handle, &pgrp))) {
            .SUCCESS => return pgrp,
            .BADF => unreachable,
            .INVAL => unreachable,
            .INTR => continue,
            .NOTTY => return error.NotATerminal,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub const TermioSetPgrpError = TermioGetPgrpError || error{NotAPgrpMember};

/// 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.
pub fn tcsetpgrp(handle: fd_t, pgrp: pid_t) TermioSetPgrpError!void {
    while (true) {
        switch (errno(system.tcsetpgrp(handle, &pgrp))) {
            .SUCCESS => return,
            .BADF => unreachable,
            .INVAL => unreachable,
            .INTR => continue,
            .NOTTY => return error.NotATerminal,
            .PERM => return TermioSetPgrpError.NotAPgrpMember,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub fn signalfd(fd: fd_t, mask: *const sigset_t, flags: u32) !fd_t {
    const rc = system.signalfd(fd, mask, flags);
    switch (errno(rc)) {
        .SUCCESS => return @intCast(rc),
        .BADF, .INVAL => unreachable,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOMEM => return error.SystemResources,
        .MFILE => return error.ProcessResources,
        .NODEV => return error.InodeMountFail,
        else => |err| return unexpectedErrno(err),
    }
}

pub const SyncError = std.Io.File.SyncError;

/// Write all pending file contents and metadata modifications to all filesystems.
pub fn sync() void {
    system.sync();
}

/// Write all pending file contents and metadata modifications to the filesystem which contains the specified file.
pub fn syncfs(fd: fd_t) SyncError!void {
    const rc = system.syncfs(fd);
    switch (errno(rc)) {
        .SUCCESS => return,
        .BADF, .INVAL, .ROFS => unreachable,
        .IO => return error.InputOutput,
        .NOSPC => return error.NoSpaceLeft,
        .DQUOT => return error.DiskQuota,
        else => |err| return unexpectedErrno(err),
    }
}

/// Write all pending file contents for the specified file descriptor to the underlying filesystem, but not necessarily the metadata.
pub fn fdatasync(fd: fd_t) SyncError!void {
    const rc = system.fdatasync(fd);
    switch (errno(rc)) {
        .SUCCESS => return,
        .BADF, .INVAL, .ROFS => unreachable,
        .IO => return error.InputOutput,
        .NOSPC => return error.NoSpaceLeft,
        .DQUOT => return error.DiskQuota,
        else => |err| return unexpectedErrno(err),
    }
}

pub const PrctlError = error{
    /// Can only occur with PR_SET_SECCOMP/SECCOMP_MODE_FILTER or
    /// PR_SET_MM/PR_SET_MM_EXE_FILE
    AccessDenied,
    /// Can only occur with PR_SET_MM/PR_SET_MM_EXE_FILE
    InvalidFileDescriptor,
    InvalidAddress,
    /// Can only occur with PR_SET_SPECULATION_CTRL, PR_MPX_ENABLE_MANAGEMENT,
    /// or PR_MPX_DISABLE_MANAGEMENT
    UnsupportedFeature,
    /// Can only occur with PR_SET_FP_MODE
    OperationUnsupported,
    PermissionDenied,
} || UnexpectedError;

pub fn prctl(option: PR, args: anytype) PrctlError!u31 {
    if (@typeInfo(@TypeOf(args)) != .@"struct")
        @compileError("Expected tuple or struct argument, found " ++ @typeName(@TypeOf(args)));
    if (args.len > 4)
        @compileError("prctl takes a maximum of 4 optional arguments");

    var buf: [4]usize = undefined;
    {
        comptime var i = 0;
        inline while (i < args.len) : (i += 1) buf[i] = args[i];
    }

    const rc = system.prctl(@backingInt(option), buf[0], buf[1], buf[2], buf[3]);
    switch (errno(rc)) {
        .SUCCESS => return @intCast(rc),
        .ACCES => return error.AccessDenied,
        .BADF => return error.InvalidFileDescriptor,
        .FAULT => return error.InvalidAddress,
        .INVAL => unreachable,
        .NODEV, .NXIO => return error.UnsupportedFeature,
        .OPNOTSUPP => return error.OperationUnsupported,
        .PERM, .BUSY => return error.PermissionDenied,
        .RANGE => unreachable,
        else => |err| return unexpectedErrno(err),
    }
}

pub const GetrlimitError = UnexpectedError;

pub fn getrlimit(resource: rlimit_resource) GetrlimitError!rlimit {
    const getrlimit_sym = if (lfs64_abi) system.getrlimit64 else system.getrlimit;

    var limits: rlimit = undefined;
    switch (errno(getrlimit_sym(resource, &limits))) {
        .SUCCESS => return limits,
        .FAULT => unreachable, // bogus pointer
        .INVAL => unreachable,
        else => |err| return unexpectedErrno(err),
    }
}

pub const SetrlimitError = error{ PermissionDenied, LimitTooBig } || UnexpectedError;

pub fn setrlimit(resource: rlimit_resource, limits: rlimit) SetrlimitError!void {
    const setrlimit_sym = if (lfs64_abi) system.setrlimit64 else system.setrlimit;

    switch (errno(setrlimit_sym(resource, &limits))) {
        .SUCCESS => return,
        .FAULT => unreachable, // bogus pointer
        .INVAL => return error.LimitTooBig, // this could also mean "invalid resource", but that would be unreachable
        .PERM => return error.PermissionDenied,
        else => |err| return unexpectedErrno(err),
    }
}

pub const MincoreError = error{
    /// A kernel resource was temporarily unavailable.
    SystemResources,
    /// vec points to an invalid address.
    InvalidAddress,
    /// addr is not page-aligned.
    InvalidSyscall,
    /// One of the following:
    /// * length is greater than user space TASK_SIZE - addr
    /// * addr + length contains unmapped memory
    OutOfMemory,
    /// The mincore syscall is not available on this version and configuration
    /// of this UNIX-like kernel.
    MincoreUnavailable,
} || UnexpectedError;

/// Determine whether pages are resident in memory.
pub fn mincore(ptr: [*]align(page_size_min) u8, length: usize, vec: [*]u8) MincoreError!void {
    return switch (errno(system.mincore(ptr, length, vec))) {
        .SUCCESS => {},
        .AGAIN => error.SystemResources,
        .FAULT => error.InvalidAddress,
        .INVAL => error.InvalidSyscall,
        .NOMEM => error.OutOfMemory,
        .NOSYS => error.MincoreUnavailable,
        else => |err| unexpectedErrno(err),
    };
}

pub const MadviseError = error{
    /// advice is MADV.REMOVE, but the specified address range is not a shared writable mapping.
    AccessDenied,
    /// advice is MADV.HWPOISON, but the caller does not have the CAP_SYS_ADMIN capability.
    PermissionDenied,
    /// A kernel resource was temporarily unavailable.
    SystemResources,
    /// One of the following:
    /// * addr is not page-aligned or length is negative
    /// * advice is not valid
    /// * advice is MADV.DONTNEED or MADV.REMOVE and the specified address range
    ///   includes locked, Huge TLB pages, or VM_PFNMAP pages.
    /// * advice is MADV.MERGEABLE or MADV.UNMERGEABLE, but the kernel was not
    ///   configured with CONFIG_KSM.
    /// * advice is MADV.FREE or MADV.WIPEONFORK but the specified address range
    ///   includes file, Huge TLB, MAP.SHARED, or VM_PFNMAP ranges.
    InvalidSyscall,
    /// (for MADV.WILLNEED) Paging in this area would exceed the process's
    /// maximum resident set size.
    WouldExceedMaximumResidentSetSize,
    /// One of the following:
    /// * (for MADV.WILLNEED) Not enough memory: paging in failed.
    /// * Addresses in the specified range are not currently mapped, or
    ///   are outside the address space of the process.
    OutOfMemory,
    /// The madvise syscall is not available on this version and configuration
    /// of the Linux kernel.
    MadviseUnavailable,
    /// The operating system returned an undocumented error code.
    Unexpected,
};

/// Give advice about use of memory.
/// This syscall is optional and is sometimes configured to be disabled.
pub fn madvise(ptr: [*]align(page_size_min) u8, length: usize, advice: u32) MadviseError!void {
    switch (errno(system.madvise(ptr, length, advice))) {
        .SUCCESS => return,
        .PERM => return error.PermissionDenied,
        .ACCES => return error.AccessDenied,
        .AGAIN => return error.SystemResources,
        .BADF => unreachable, // The map exists, but the area maps something that isn't a file.
        .INVAL => return error.InvalidSyscall,
        .IO => return error.WouldExceedMaximumResidentSetSize,
        .NOMEM => return error.OutOfMemory,
        .NOSYS => return error.MadviseUnavailable,
        else => |err| return unexpectedErrno(err),
    }
}

pub const PerfEventOpenError = error{
    /// Returned if the perf_event_attr size value is too small (smaller
    /// than PERF_ATTR_SIZE_VER0), too big (larger than the page  size),
    /// or  larger  than the kernel supports and the extra bytes are not
    /// zero.  When E2BIG is returned, the perf_event_attr size field is
    /// overwritten by the kernel to be the size of the structure it was
    /// expecting.
    TooBig,
    /// Returned when the requested event requires CAP_SYS_ADMIN permis‐
    /// sions  (or a more permissive perf_event paranoid setting).  Some
    /// common cases where an unprivileged process  may  encounter  this
    /// error:  attaching  to a process owned by a different user; moni‐
    /// toring all processes on a given CPU (i.e.,  specifying  the  pid
    /// argument  as  -1); and not setting exclude_kernel when the para‐
    /// noid setting requires it.
    /// Also:
    /// Returned on many (but not all) architectures when an unsupported
    /// exclude_hv,  exclude_idle,  exclude_user, or exclude_kernel set‐
    /// ting is specified.
    /// It can also happen, as with EACCES, when the requested event re‐
    /// quires   CAP_SYS_ADMIN   permissions   (or   a  more  permissive
    /// perf_event paranoid setting).  This includes  setting  a  break‐
    /// point on a kernel address, and (since Linux 3.13) setting a ker‐
    /// nel function-trace tracepoint.
    PermissionDenied,
    /// Returned if another event already has exclusive  access  to  the
    /// PMU.
    DeviceBusy,
    /// Each  opened  event uses one file descriptor.  If a large number
    /// of events are opened, the per-process limit  on  the  number  of
    /// open file descriptors will be reached, and no more events can be
    /// created.
    ProcessResources,
    EventRequiresUnsupportedCpuFeature,
    /// Returned if  you  try  to  add  more  breakpoint
    /// events than supported by the hardware.
    TooManyBreakpoints,
    /// Returned  if PERF_SAMPLE_STACK_USER is set in sample_type and it
    /// is not supported by hardware.
    SampleStackNotSupported,
    /// Returned if an event requiring a specific  hardware  feature  is
    /// requested  but  there is no hardware support.  This includes re‐
    /// questing low-skid events if not supported, branch tracing if  it
    /// is not available, sampling if no PMU interrupt is available, and
    /// branch stacks for software events.
    EventNotSupported,
    /// Returned  if  PERF_SAMPLE_CALLCHAIN  is   requested   and   sam‐
    /// ple_max_stack   is   larger   than   the  maximum  specified  in
    /// /proc/sys/kernel/perf_event_max_stack.
    SampleMaxStackOverflow,
    /// Returned if attempting to attach to a process that does not  exist.
    ProcessNotFound,
} || UnexpectedError;

pub fn perf_event_open(
    attr: *system.perf_event_attr,
    pid: pid_t,
    cpu: i32,
    group_fd: fd_t,
    flags: usize,
) PerfEventOpenError!fd_t {
    if (native_os == .linux) {
        // There is no syscall wrapper for this function exposed by libcs
        const rc = linux.perf_event_open(attr, pid, cpu, group_fd, flags);
        switch (linux.errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .@"2BIG" => return error.TooBig,
            .ACCES => return error.PermissionDenied,
            .BADF => unreachable, // group_fd file descriptor is not valid.
            .BUSY => return error.DeviceBusy,
            .FAULT => unreachable, // Segmentation fault.
            .INVAL => unreachable, // Bad attr settings.
            .INTR => unreachable, // Mixed perf and ftrace handling for a uprobe.
            .MFILE => return error.ProcessResources,
            .NODEV => return error.EventRequiresUnsupportedCpuFeature,
            .NOENT => unreachable, // Invalid type setting.
            .NOSPC => return error.TooManyBreakpoints,
            .NOSYS => return error.SampleStackNotSupported,
            .OPNOTSUPP => return error.EventNotSupported,
            .OVERFLOW => return error.SampleMaxStackOverflow,
            .PERM => return error.PermissionDenied,
            .SRCH => return error.ProcessNotFound,
            else => |err| return unexpectedErrno(err),
        }
    }
}

pub const PtraceError = error{
    DeadLock,
    DeviceBusy,
    InputOutput,
    NameTooLong,
    OperationUnsupported,
    OutOfMemory,
    ProcessNotFound,
    PermissionDenied,
} || UnexpectedError;

pub fn ptrace(request: u32, pid: pid_t, addr: usize, data: usize) PtraceError!void {
    return switch (native_os) {
        .windows,
        .wasi,
        .emscripten,
        .haiku,
        .illumos,
        .plan9,
        => @compileError("ptrace unsupported by target OS"),

        .linux => switch (errno(if (builtin.link_libc) std.c.ptrace(
            @intCast(request),
            pid,
            @ptrFromInt(addr),
            @ptrFromInt(data),
        ) else linux.ptrace(request, pid, addr, data, 0))) {
            .SUCCESS => {},
            .SRCH => error.ProcessNotFound,
            .FAULT => unreachable,
            .INVAL => unreachable,
            .IO => return error.InputOutput,
            .PERM => error.PermissionDenied,
            .BUSY => error.DeviceBusy,
            else => |err| return unexpectedErrno(err),
        },

        .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => switch (errno(std.c.ptrace(
            @fromBackingInt(@intCast(request)),
            pid,
            @ptrFromInt(addr),
            @intCast(data),
        ))) {
            .SUCCESS => {},
            .SRCH => error.ProcessNotFound,
            .INVAL => unreachable,
            .PERM => error.PermissionDenied,
            .BUSY => error.DeviceBusy,
            else => |err| return unexpectedErrno(err),
        },

        .dragonfly => switch (errno(std.c.ptrace(
            @intCast(request),
            pid,
            @ptrFromInt(addr),
            @intCast(data),
        ))) {
            .SUCCESS => {},
            .SRCH => error.ProcessNotFound,
            .INVAL => unreachable,
            .PERM => error.PermissionDenied,
            .BUSY => error.DeviceBusy,
            else => |err| return unexpectedErrno(err),
        },

        .freebsd => switch (errno(std.c.ptrace(
            @intCast(request),
            pid,
            @ptrFromInt(addr),
            @intCast(data),
        ))) {
            .SUCCESS => {},
            .SRCH => error.ProcessNotFound,
            .INVAL => unreachable,
            .PERM => error.PermissionDenied,
            .BUSY => error.DeviceBusy,
            .NOENT, .NOMEM => error.OutOfMemory,
            .NAMETOOLONG => error.NameTooLong,
            else => |err| return unexpectedErrno(err),
        },

        .netbsd => switch (errno(std.c.ptrace(
            @intCast(request),
            pid,
            @ptrFromInt(addr),
            @intCast(data),
        ))) {
            .SUCCESS => {},
            .SRCH => error.ProcessNotFound,
            .INVAL => unreachable,
            .PERM => error.PermissionDenied,
            .BUSY => error.DeviceBusy,
            .DEADLK => error.DeadLock,
            else => |err| return unexpectedErrno(err),
        },

        .openbsd => switch (errno(std.c.ptrace(
            @intCast(request),
            pid,
            @ptrFromInt(addr),
            @intCast(data),
        ))) {
            .SUCCESS => {},
            .SRCH => error.ProcessNotFound,
            .INVAL => unreachable,
            .PERM => error.PermissionDenied,
            .BUSY => error.DeviceBusy,
            .NOTSUP => error.OperationUnsupported,
            else => |err| return unexpectedErrno(err),
        },

        else => @compileError("std.posix.ptrace unimplemented for target OS"),
    };
}

pub const NameToFileHandleAtError = error{
    FileNotFound,
    NotDir,
    OperationUnsupported,
    NameTooLong,
    Unexpected,
};

pub fn name_to_handle_at(
    dirfd: fd_t,
    pathname: []const u8,
    handle: *std.os.linux.file_handle,
    mount_id: *i32,
    flags: u32,
) NameToFileHandleAtError!void {
    const pathname_c = try toPosixPath(pathname);
    return name_to_handle_atZ(dirfd, &pathname_c, handle, mount_id, flags);
}

pub fn name_to_handle_atZ(
    dirfd: fd_t,
    pathname_z: [*:0]const u8,
    handle: *std.os.linux.file_handle,
    mount_id: *i32,
    flags: u32,
) NameToFileHandleAtError!void {
    switch (errno(system.name_to_handle_at(dirfd, pathname_z, handle, mount_id, flags))) {
        .SUCCESS => {},
        .FAULT => unreachable, // pathname, mount_id, or handle outside accessible address space
        .INVAL => unreachable, // bad flags, or handle_bytes too big
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.NotDir,
        .OPNOTSUPP => return error.OperationUnsupported,
        .OVERFLOW => return error.NameTooLong,
        else => |err| return unexpectedErrno(err),
    }
}

pub const lfs64_abi = native_os == .linux and builtin.link_libc and (builtin.abi.isGnu() or builtin.abi.isAndroid());

pub const UnexpectedError = std.Io.UnexpectedError;

/// Call this when you made a syscall or something that sets errno
/// and you get an unexpected error.
pub fn unexpectedErrno(err: E) UnexpectedError {
    if (std.options.unexpected_error_tracing) {
        std.debug.print("unexpected errno: {d}\n", .{@backingInt(err)});
        std.debug.dumpCurrentStackTrace(.{});
    }
    return error.Unexpected;
}

/// Used to convert a slice to a null terminated slice on the stack.
pub fn toPosixPath(file_path: []const u8) error{NameTooLong}![PATH_MAX - 1:0]u8 {
    if (std.debug.runtime_safety) assert(mem.findScalar(u8, file_path, 0) == null);
    var path_with_null: [PATH_MAX - 1:0]u8 = undefined;
    // >= rather than > to make room for the null byte
    if (file_path.len >= PATH_MAX) return error.NameTooLong;
    @memcpy(path_with_null[0..file_path.len], file_path);
    path_with_null[file_path.len] = 0;
    return path_with_null;
}