Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/std.zig

Source line 1

std.array_hash_map

alias

Source line 64

Alias of std.array_hash_map

std.array_list

alias

Source line 55

Alias of std.array_list

std.ArrayHashMapUnmanaged

alias

Source line 40

Deprecated; use array_hash_map.Custom.

Alias of std.array_hash_map.Custom

std.ArrayList

type-function

Source line 52

A contiguous, growable list of items in memory. This is a wrapper around a slice of T values.

The same allocator must be used throughout its entire lifetime. Initialize directly with empty or initCapacity, and deinitialize with deinit or toOwnedSlice.

pub fn ArrayList(comptime T: type) type

Parameters

T: type

std.ArrayListAligned

alias

Source line 58

Deprecated; use array_list.Aligned.

Alias of std.array_list.Aligned

std.ArrayListAlignedUnmanaged

alias

Source line 60

Deprecated; use array_list.Aligned.

Alias of std.array_list.Aligned

std.ArrayListUnmanaged

alias

Source line 62

Deprecated; use ArrayList.

Alias of std.ArrayList

std.ascii

alias

Source line 103

Alias of std.ascii

std.atomic

alias

Source line 65

Alias of std.atomic

std.AutoArrayHashMapUnmanaged

alias

Source line 42

Deprecated; use array_hash_map.Auto.

Alias of std.array_hash_map.Auto

std.AutoHashMap

alias

Source line 1

Alias of std.hash_map.AutoHashMap

std.AutoHashMapUnmanaged

alias

Source line 2

Alias of std.hash_map.AutoHashMapUnmanaged

std.base64

alias

Source line 66

Alias of std.base64

std.bit_set

alias

Source line 67

Alias of std.bit_set

std.BitStack

alias

Source line 3

Alias of std.BitStack

std.BufMap

alias

Source line 5

Alias of std.buf_map.BufMap

std.BufSet

alias

Source line 6

Alias of std.buf_set.BufSet

std.Build

alias

Source line 4

Alias of std.Build

std.builtin

alias

Source line 71

Deprecated; use lang.

To be removed after Zig 0.17.0.

Alias of std.lang

std.c

alias

Source line 73

Alias of std.c

std.coff

alias

Source line 74

Alias of std.coff

std.compress

alias

Source line 75

Alias of std.compress

std.crypto

alias

Source line 77

Alias of std.crypto

std.debug

alias

Source line 78

Alias of std.debug

std.Deque

alias

Source line 9

Alias of std.deque.Deque

std.DoublyLinkedList

alias

Source line 10

Alias of std.DoublyLinkedList

std.dwarf

alias

Source line 79

Alias of std.dwarf

std.DynamicBitSet

alias

Source line 13

Deprecated: use bit_set.DynamicManaged.

Alias of std.bit_set.DynamicBitSet

std.DynamicBitSetUnmanaged

alias

Source line 15

Deprecated: use bit_set.Dynamic.

Alias of std.bit_set.DynamicBitSetUnmanaged

std.DynLib

alias

Source line 11

Alias of std.dynamic_library.DynLib

std.elf

alias

Source line 80

Alias of std.elf

std.EnumArray

alias

Source line 16

Alias of std.enums.EnumArray

std.EnumMap

alias

Source line 17

Alias of std.enums.EnumMap

std.enums

alias

Source line 81

Alias of std.enums

std.EnumSet

alias

Source line 18

Alias of std.enums.EnumSet

std.fmt

alias

Source line 82

Alias of std.fmt

std.fs

alias

Source line 83

Alias of std.fs

std.hash

alias

Source line 85

Alias of std.hash

std.hash_map

alias

Source line 86

Alias of std.hash_map

std.HashMap

alias

Source line 19

Alias of std.hash_map.HashMap

std.HashMapUnmanaged

alias

Source line 20

Alias of std.hash_map.HashMapUnmanaged

std.heap

alias

Source line 87

Alias of std.heap

std.http

alias

Source line 88

Alias of std.http

std.Io

alias

Source line 21

Alias of std.Io

std.json

alias

Source line 89

Alias of std.json

std.lang

alias

Source line 72

Alias of std.lang

std.leb

alias

Source line 90

Alias of std.leb128

std.log

alias

Source line 91

Alias of std.log

std.macho

alias

Source line 92

Alias of std.macho

std.math

alias

Source line 93

Alias of std.math

std.mem

alias

Source line 94

Alias of std.mem

std.meta

alias

Source line 95

Alias of std.meta

std.MultiArrayList

alias

Source line 22

Alias of std.multi_array_list.MultiArrayList

std.options

constant

Source line 119

Compile-time known settings overridable by the root source file.

Options

std.Options

container

Source line 121

Fields

enable_segfault_handler: bool = debug.default_enable_segfault_handler
signal_stack_size: ?u64 = 1 << 18

If set, std.start and std.Thread will configure an per-thread alternative signal stack of this size. Importantly, if enable_segfault_handler is set, the segfault handler will use this alternative stack, meaning it can still print stack traces even if a segmentation fault is caused by a stack overflow.

On POSIX targets, the signal stack is configured using 'sigaltstack(2)'.

On Windows, this value is currently ignored.

log_level: log.Level = log.default_level

The current log level.

log_scope_levels: []const log.ScopeLevel = &.{}
logFn: fn (
    comptime message_level: log.Level,
    comptime scope: @EnumLiteral(),
    comptime format: []const u8,
    args: anytype,
) void = log.defaultLog
page_size_min: ?usize = null

Overrides std.heap.page_size_min.

page_size_max: ?usize = null

Overrides std.heap.page_size_max.

queryPageSize: fn () usize = heap.defaultQueryPageSize

Overrides default implementation for determining OS page size at runtime.

fmt_max_depth: usize = fmt.default_max_depth
http_disable_tls: bool = false

By default, std.http.Client will support HTTPS connections. Set this option to true to disable TLS support.

This will likely reduce the size of the binary, but it will also make it impossible to make a HTTPS connection.

http_enable_ssl_key_log_file: bool = @import("builtin").mode == .debug

This enables std.http.Client to log ssl secrets to the file specified by the SSLKEYLOGFILE env var. Creating such a log file allows other programs with access to that file to decrypt all std.http.Client traffic made by this program.

side_channels_mitigations: crypto.SideChannelsMitigations = crypto.default_side_channels_mitigations
allow_stack_tracing: bool = !@import("builtin").strip_debug_info

Whether to allow capturing and writing stack traces. This affects the following functions:

Stack traces can generally be collected and printed when debug info is stripped, but are often less useful since they usually cannot be mapped to source locations and/or have bad source locations. The stack tracing logic can also be quite large, which may be undesirable, particularly in ReleaseSmall.

If this is false, then captured stack traces will always be empty, and attempts to write stack traces will just print an error to the relevant Io.Writer and return.

networking: bool = true

Allows disabling networking in std.Io implementations.

unexpected_error_tracing: bool = @import("builtin").mode == .debug and switch (@import("builtin").zig_backend) {
    .stage2_llvm, .stage2_x86_64 => true,
    else => false,
}

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

If this happens the fix is to add the error code to the corresponding switch expression, possibly introduce a new error in the error set, and send a patch to Zig.

std.Options.cwd

constant

Source line 234

Overrides std.Io.Dir.cwd.

?fn () Io.Dir

std.Options.debug_io

constant

Source line 228

The Io instance that std.debug uses for std.debug.print, capturing stack traces, loading debug info, finding the executable's own path, and environment variables that affect terminal mode detection. The default is to use statically initialized singleton that is independent from the application's Io instance in order to make debugging more straightforward. For example, while debugging an Io implementation based on coroutines, one likely wants std.debug.print to directly write to stderr without trying to interact with the code being debugged.

Io

std.Options.debug_threaded_io

constant

Source line 214

?*Io.Threaded

std.Options.elf_debug_info_search_paths

constant

Source line 206

TODO This is a separate decl instead of a field as a workaround around compilation errors due to zig not being lazy enough.

?fn (exe_path: []const u8) switch (@import("builtin").object_format) { .elf => debug.ElfFile.DebugInfoSearchPaths, else => void, }

std.Options.FilePermissions

constant

Source line 231

Overrides std.Io.File.Permissions.

?type

std.Options.logTerminalMode

alias

Source line 202

TODO This is a separate decl instead of a field as a workaround around compilation errors due to zig not being lazy enough.

Alias of std.log.defaultTerminalMode

std.os

alias

Source line 96

Alias of std.os

std.pdb

alias

Source line 97

Alias of std.pdb

std.pie

alias

Source line 98

Alias of std.pie

std.posix

alias

Source line 99

Alias of std.posix

std.PriorityDequeue

alias

Source line 24

Alias of std.priority_dequeue.PriorityDequeue

std.PriorityQueue

alias

Source line 23

Alias of std.priority_queue.PriorityQueue

std.process

alias

Source line 100

Alias of std.process

std.Progress

alias

Source line 25

Alias of std.Progress

std.Random

alias

Source line 26

Alias of std.Random

std.root

constant

Source line 116

std.SemanticVersion

alias

Source line 27

Alias of std.SemanticVersion

std.simd

alias

Source line 102

Alias of std.simd

std.SinglyLinkedList

alias

Source line 28

Alias of std.SinglyLinkedList

std.sort

alias

Source line 101

Alias of std.sort

std.spirv

alias

Source line 84

Alias of std.spirv

std.start

alias

Source line 114

Alias of std.start

std.static_string_map

alias

Source line 76

Alias of std.static_string_map

std.StaticBitSet

alias

Source line 30

Deprecated: use bit_set.Static.

Alias of std.bit_set.StaticBitSet

std.StaticStringMap

alias

Source line 7

Alias of std.static_string_map.StaticStringMap

std.StaticStringMapWithEql

alias

Source line 8

Alias of std.static_string_map.StaticStringMapWithEql

std.StringArrayHashMapUnmanaged

alias

Source line 44

Deprecated; use array_hash_map.String.

Alias of std.array_hash_map.String

std.StringHashMap

alias

Source line 31

Alias of std.hash_map.StringHashMap

std.StringHashMapUnmanaged

alias

Source line 32

Alias of std.hash_map.StringHashMapUnmanaged

std.tar

alias

Source line 104

Alias of std.tar

std.Target

alias

Source line 33

Alias of std.Target

std.testing

alias

Source line 105

Alias of std.testing

std.Thread

alias

Source line 34

Alias of std.Thread

std.time

alias

Source line 106

Alias of std.time

std.Treap

alias

Source line 35

Alias of std.treap.Treap

std.tz

alias

Source line 107

Alias of std.tz

std.Tz

alias

Source line 36

Alias of std.tz.Tz

std.unicode

alias

Source line 108

Alias of std.unicode

std.Uri

alias

Source line 37

Alias of std.Uri

std.valgrind

alias

Source line 109

Alias of std.valgrind

std.wasm

alias

Source line 110

Alias of std.wasm

std.zig

alias

Source line 111

Alias of std.zig

std.zip

alias

Source line 112

Alias of std.zip

std.zon

alias

Source line 113

Alias of std.zon

Source code

std/std.zig

pub const AutoHashMap = hash_map.AutoHashMap;
pub const AutoHashMapUnmanaged = hash_map.AutoHashMapUnmanaged;
pub const BitStack = @import("BitStack.zig");
pub const Build = @import("Build.zig");
pub const BufMap = @import("buf_map.zig").BufMap;
pub const BufSet = @import("buf_set.zig").BufSet;
pub const StaticStringMap = static_string_map.StaticStringMap;
pub const StaticStringMapWithEql = static_string_map.StaticStringMapWithEql;
pub const Deque = @import("deque.zig").Deque;
pub const DoublyLinkedList = @import("DoublyLinkedList.zig");
pub const DynLib = @import("dynamic_library.zig").DynLib;
/// Deprecated: use `bit_set.DynamicManaged`.
pub const DynamicBitSet = bit_set.DynamicBitSet;
/// Deprecated: use `bit_set.Dynamic`.
pub const DynamicBitSetUnmanaged = bit_set.DynamicBitSetUnmanaged;
pub const EnumArray = enums.EnumArray;
pub const EnumMap = enums.EnumMap;
pub const EnumSet = enums.EnumSet;
pub const HashMap = hash_map.HashMap;
pub const HashMapUnmanaged = hash_map.HashMapUnmanaged;
pub const Io = @import("Io.zig");
pub const MultiArrayList = @import("multi_array_list.zig").MultiArrayList;
pub const PriorityQueue = @import("priority_queue.zig").PriorityQueue;
pub const PriorityDequeue = @import("priority_dequeue.zig").PriorityDequeue;
pub const Progress = @import("Progress.zig");
pub const Random = @import("Random.zig");
pub const SemanticVersion = @import("SemanticVersion.zig");
pub const SinglyLinkedList = @import("SinglyLinkedList.zig");
/// Deprecated: use `bit_set.Static`.
pub const StaticBitSet = bit_set.StaticBitSet;
pub const StringHashMap = hash_map.StringHashMap;
pub const StringHashMapUnmanaged = hash_map.StringHashMapUnmanaged;
pub const Target = @import("Target.zig");
pub const Thread = @import("Thread.zig");
pub const Treap = @import("treap.zig").Treap;
pub const Tz = tz.Tz;
pub const Uri = @import("Uri.zig");

/// Deprecated; use `array_hash_map.Custom`.
pub const ArrayHashMapUnmanaged = array_hash_map.Custom;
/// Deprecated; use `array_hash_map.Auto`.
pub const AutoArrayHashMapUnmanaged = array_hash_map.Auto;
/// Deprecated; use `array_hash_map.String`.
pub const StringArrayHashMapUnmanaged = array_hash_map.String;

/// A contiguous, growable list of items in memory. This is a wrapper around a
/// slice of `T` values.
///
/// The same allocator must be used throughout its entire lifetime. Initialize
/// directly with `empty` or `initCapacity`, and deinitialize with `deinit` or
/// `toOwnedSlice`.
pub fn ArrayList(comptime T: type) type {
    return array_list.Aligned(T, null);
}
pub const array_list = @import("array_list.zig");

/// Deprecated; use `array_list.Aligned`.
pub const ArrayListAligned = array_list.Aligned;
/// Deprecated; use `array_list.Aligned`.
pub const ArrayListAlignedUnmanaged = array_list.Aligned;
/// Deprecated; use `ArrayList`.
pub const ArrayListUnmanaged = ArrayList;

pub const array_hash_map = @import("array_hash_map.zig");
pub const atomic = @import("atomic.zig");
pub const base64 = @import("base64.zig");
pub const bit_set = @import("bit_set.zig");
/// Deprecated; use `lang`.
///
/// To be removed after Zig 0.17.0.
pub const builtin = lang;
pub const lang = @import("lang.zig");
pub const c = @import("c.zig");
pub const coff = @import("coff.zig");
pub const compress = @import("compress.zig");
pub const static_string_map = @import("static_string_map.zig");
pub const crypto = @import("crypto.zig");
pub const debug = @import("debug.zig");
pub const dwarf = @import("dwarf.zig");
pub const elf = @import("elf.zig");
pub const enums = @import("enums.zig");
pub const fmt = @import("fmt.zig");
pub const fs = @import("fs.zig");
pub const spirv = @import("spirv.zig");
pub const hash = @import("hash.zig");
pub const hash_map = @import("hash_map.zig");
pub const heap = @import("heap.zig");
pub const http = @import("http.zig");
pub const json = @import("json.zig");
pub const leb = @import("leb128.zig");
pub const log = @import("log.zig");
pub const macho = @import("macho.zig");
pub const math = @import("math.zig");
pub const mem = @import("mem.zig");
pub const meta = @import("meta.zig");
pub const os = @import("os.zig");
pub const pdb = @import("pdb.zig");
pub const pie = @import("pie.zig");
pub const posix = @import("posix.zig");
pub const process = @import("process.zig");
pub const sort = @import("sort.zig");
pub const simd = @import("simd.zig");
pub const ascii = @import("ascii.zig");
pub const tar = @import("tar.zig");
pub const testing = @import("testing.zig");
pub const time = @import("time.zig");
pub const tz = @import("tz.zig");
pub const unicode = @import("unicode.zig");
pub const valgrind = @import("valgrind.zig");
pub const wasm = @import("wasm.zig");
pub const zig = @import("zig.zig");
pub const zip = @import("zip.zig");
pub const zon = @import("zon.zig");
pub const start = @import("start.zig");

const root = @import("root");

/// Compile-time known settings overridable by the root source file.
pub const options: Options = if (@hasDecl(root, "std_options")) root.std_options else .{};

pub const Options = struct {
    enable_segfault_handler: bool = debug.default_enable_segfault_handler,

    /// If set, `std.start` and `std.Thread` will configure an per-thread alternative signal stack
    /// of this size. Importantly, if `enable_segfault_handler` is set, the segfault handler will
    /// use this alternative stack, meaning it can still print stack traces even if a segmentation
    /// fault is caused by a stack overflow.
    ///
    /// On POSIX targets, the signal stack is configured using 'sigaltstack(2)'.
    ///
    /// On Windows, this value is currently ignored.
    signal_stack_size: ?u64 = 1 << 18, // 1<<17 observed to be sufficient for stack tracing with self-hosted x86_64 backend

    /// The current log level.
    log_level: log.Level = log.default_level,

    log_scope_levels: []const log.ScopeLevel = &.{},

    logFn: fn (
        comptime message_level: log.Level,
        comptime scope: @EnumLiteral(),
        comptime format: []const u8,
        args: anytype,
    ) void = log.defaultLog,

    /// Overrides `std.heap.page_size_min`.
    page_size_min: ?usize = null,
    /// Overrides `std.heap.page_size_max`.
    page_size_max: ?usize = null,
    /// Overrides default implementation for determining OS page size at runtime.
    queryPageSize: fn () usize = heap.defaultQueryPageSize,

    fmt_max_depth: usize = fmt.default_max_depth,

    /// By default, std.http.Client will support HTTPS connections.  Set this option to `true` to
    /// disable TLS support.
    ///
    /// This will likely reduce the size of the binary, but it will also make it impossible to
    /// make a HTTPS connection.
    http_disable_tls: bool = false,

    /// This enables `std.http.Client` to log ssl secrets to the file specified by the SSLKEYLOGFILE
    /// env var.  Creating such a log file allows other programs with access to that file to decrypt
    /// all `std.http.Client` traffic made by this program.
    http_enable_ssl_key_log_file: bool = @import("builtin").mode == .debug,

    side_channels_mitigations: crypto.SideChannelsMitigations = crypto.default_side_channels_mitigations,

    /// Whether to allow capturing and writing stack traces. This affects the following functions:
    /// * `debug.captureCurrentStackTrace`
    /// * `debug.writeCurrentStackTrace`
    /// * `debug.dumpCurrentStackTrace`
    /// * `debug.writeStackTrace`
    /// * `debug.dumpStackTrace`
    /// * `debug.writeErrorReturnTrace`
    /// * `debug.dumpErrorReturnTrace`
    ///
    /// Stack traces can generally be collected and printed when debug info is stripped, but are
    /// often less useful since they usually cannot be mapped to source locations and/or have bad
    /// source locations. The stack tracing logic can also be quite large, which may be undesirable,
    /// particularly in ReleaseSmall.
    ///
    /// If this is `false`, then captured stack traces will always be empty, and attempts to write
    /// stack traces will just print an error to the relevant `Io.Writer` and return.
    allow_stack_tracing: bool = !@import("builtin").strip_debug_info,

    /// Allows disabling networking in std.Io implementations.
    networking: bool = true,

    /// Whether or not `error.Unexpected` will print its value and a stack trace.
    ///
    /// If this happens the fix is to add the error code to the corresponding
    /// switch expression, possibly introduce a new error in the error set, and
    /// send a patch to Zig.
    unexpected_error_tracing: bool = @import("builtin").mode == .debug and switch (@import("builtin").zig_backend) {
        .stage2_llvm, .stage2_x86_64 => true,
        else => false,
    },

    /// TODO This is a separate decl instead of a field as a workaround around
    /// compilation errors due to zig not being lazy enough.
    pub const logTerminalMode: fn () Io.Terminal.Mode = log.defaultTerminalMode;

    /// TODO This is a separate decl instead of a field as a workaround around
    /// compilation errors due to zig not being lazy enough.
    pub const elf_debug_info_search_paths: ?fn (exe_path: []const u8) switch (@import("builtin").object_format) {
        .elf => debug.ElfFile.DebugInfoSearchPaths,
        else => void,
    } = if (@hasDecl(root, "std_options_elf_debug_info_search_paths"))
        root.std_options_elf_debug_info_search_paths
    else
        null;

    pub const debug_threaded_io: ?*Io.Threaded = if (@hasDecl(root, "std_options_debug_threaded_io"))
        root.std_options_debug_threaded_io
    else
        Io.Threaded.global_single_threaded;

    /// The `Io` instance that `std.debug` uses for `std.debug.print`,
    /// capturing stack traces, loading debug info, finding the executable's
    /// own path, and environment variables that affect terminal mode
    /// detection. The default is to use statically initialized singleton that
    /// is independent from the application's `Io` instance in order to make
    /// debugging more straightforward. For example, while debugging an `Io`
    /// implementation based on coroutines, one likely wants `std.debug.print`
    /// to directly write to stderr without trying to interact with the code
    /// being debugged.
    pub const debug_io: Io = if (@hasDecl(root, "std_options_debug_io")) root.std_options_debug_io else debug_threaded_io.?.io();

    /// Overrides `std.Io.File.Permissions`.
    pub const FilePermissions: ?type = if (@hasDecl(root, "std_options_FilePermissions")) root.std_options_FilePermissions else null;

    /// Overrides `std.Io.Dir.cwd`.
    pub const cwd: ?fn () Io.Dir = if (@hasDecl(root, "std_options_cwd")) root.std_options_cwd else null;
};

// This forces the start.zig file to be imported, and the comptime logic inside that
// file decides whether to export any appropriate start symbols, and call main.
comptime {
    _ = start;
}

test {
    testing.refAllDecls(@This());
}

comptime {
    debug.assert(@import("std") == @This()); // std lib tests require --zig-lib-dir
}