Chapter 3: I/O with utility
Introduces cat as a simple, useful program and argues that dependable everyday software is a worthwhile use for Zig.
After this chapter you will be able to
- Value of simple software. Explain why a small program such as cat is worth building and why the author presents Zig as a good fit for it.
- Standard library role and flexibility. Explain what Zig’s standard library is used for and why its use is optional.
- Startup init argument variants. Explain that start.zig calls main and checks whether it accepts an optional init parameter. Distinguish the information supplied by std.process.Init.Minimal from the additional resources supplied by std.process.Init.
- Stack and heap memory. Explain why unknown-size data may need heap memory and how an allocator manages its lifetime.
- Explicit allocator control. Explain how Zig makes allocation choices explicit compared with the runtime-managed allocation described for C and most languages.
- Io as system abstraction. Explain why std.Io covers more than input and output: it provides access to common operating-system capabilities through an abstraction that helps programs work across platforms.
- Cat program output behavior. Describe how the cat program uses command-line filenames to produce output.
- File and directory handles. Explain what std.Io.File and std.Io.Dir are used for, what a handle represents, and why a Dir is used to open a relative path.
- Current directory file reading. Describe how the example obtains the current working directory and reads a file’s contents, including why readFileAlloc needs an allocator.
- Error sets and widening. Explain that Zig errors are values drawn from error sets, and describe when an error from a narrower set can be used as part of a wider set.
- Error union return values. Describe what an error union can contain and how its type is written in a function return type.
- Handling error union branches. Trace how an if/else expression captures an error union's payload or error, and explain why catch is used for a common handling pattern.
- Explicit error propagation with try. Explain what Zig's try does to an error union and who remains responsible for an error it propagates.
- Writers and their implementations. Explain that a std.Io.Writer can write to different destinations because it is a generic interface backed by an implementation, much like an allocator.
- For loop item captures. Describe what Zig for loops can iterate over and how a capture names each item.
- Multiple iterable captures. Explain how a for loop iterates over multiple arrays or slices together and why this is preferable to manually indexing them with a range.
- Loop expression results. Explain how a for loop used as an expression gets its result from break or else.
- Command-line file selection. Explain how the cat program obtains file names from command-line arguments and why it skips the first argument.
- Condition-controlled Collatz loop. Explain that a while loop repeats until its condition is false, and describe how the Collatz example uses repetition to count the steps from a starting number to one.
- Visibility of cat program errors. Explain how Zig’s type-checked error sets and error-as-value semantics help reveal possible failures in the cat program.
- Explicit failure points and contracts. Explain how to find potential failures in the cat program and what an error set means for a function’s caller.
- Context dependent error responses. Distinguish when propagating an error, informing the user, or logging and continuing makes sense, using the cat program’s failures as examples.
- Allocator cleanup strategies. Distinguish an arena allocator’s end-of-lifetime cleanup from a general purpose allocator’s requirement to free each allocation, and explain why the latter suits this cat program.
- Deferred cleanup on scope exit. Explain how defer prevents the file-content allocation from being missed when writing to stdout fails.
- Code improvement tradeoffs. Explain why the best version of a program need not be optimal or infallible, and describe the costs and circumstances to weigh before improving it.
- Essential file copy steps. Describe the minimal file-copy sequence in operating-system terms: open each file for reading, read and write its data to stdout until none remains, then close it.
- Failures during file copying. Distinguish the section’s responses to a failed open, a failed read or write, and a failed attempt to print an error message.
- Unnecessary whole-file allocation. Explain why the existing use of readFileAlloc does extra work for this program and what removing that allocation would avoid.
- Readers and streaming. Explain that std.Io.Reader is a generic interface for sources of bytes and that, once a reader and writer are set up, one function can transfer bytes between them until none remain.
- Configurable cat buffer size. Explain why Bill and Buff want different buffer sizes and how the section proposes accommodating both: a build-script argument that configures buffer size during compilation.
- Build script purpose. Explain why a project may use a build script instead of relying on `zig run`: it supplies configuration to automate compilation, from one executable to related libraries and executables.
- Build steps and graph. Describe how a basic build script defines modules and their compilation through build steps, and how dependent steps form a build graph.
- Executable build graph. Explain how the build script defines an executable build step and makes it run with zig build.
- Configurable cat buffering. Describe how build flags make buffer-size options available to cat and how the program behaves with buffering enabled versus disabled.
- Compile-time buffer sizes. Explain why a configured buffer size can appear in an array type definition in this program.
- Useful software beyond elegant code. Explain why making code precise or beautiful is not enough to make it useful, and why real users and changing requirements demand flexibility and persistence.
What it builds on
- Slicing and dicing (chapter 2) · the earlier introduction to slices
- Arrays (chapter 2) · the earlier introduction to arrays
Section by section
Introduction
Introduces cat as a simple, useful program and argues that dependable everyday software is a worthwhile use for Zig.
- Value of simple software: Explain why a small program such as cat is worth building and why the author presents Zig as a good fit for it.
Why it matters: It explains why the chapter spends time on an apparently elementary utility. - Purpose of cat: Describe what cat is commonly used to do.
Why it matters: It identifies the concrete utility the chapter uses as its example.
Key terms: cat, performance, reliability, concatenating files, console
3.1 Standard Zig
This section introduces the role and optionality of Zig’s standard library and shows where to find its documentation.
- Standard library role and flexibility: Explain what Zig’s standard library is used for and why its use is optional.
Why it matters: This helps you understand when std is useful without mistaking it for a mandatory part of every Zig program. - Zig documentation access: Describe where to find Zig’s standard-library and language documentation and how to open the standard-library documentation locally.
Why it matters: Documentation gives you a reference beyond what this book can cover, including when connectivity is unreliable.
Key terms: standard library, std, standard library documentation, language documentation, zig std
3.1.1 First and Foremost
Explains how Zig startup code supplies an optional init argument to main and what its two supported types contain.
- Startup init argument variants: Explain that start.zig calls main and checks whether it accepts an optional init parameter. Distinguish the information supplied by std.process.Init.Minimal from the additional resources supplied by std.process.Init.
Why it matters: This identifies where main gets process information and the resources introduced in the following sections.
Key terms: start.zig, init, std.process.Init.Minimal, std.process.Init, std.Io
3.1.2 Allocating with Allocators
This section explains why Zig uses explicit allocators, how allocated memory is managed, and what several common allocators offer.
- Stack and heap memory: Explain why unknown-size data may need heap memory and how an allocator manages its lifetime.
Why it matters: This distinction helps you choose memory for data that may not fit safely on the stack. - Explicit allocator control: Explain how Zig makes allocation choices explicit compared with the runtime-managed allocation described for C and most languages.
Why it matters: Explicit allocation choices let you control how your code manages memory. - Safe and arena allocators: Distinguish SafeAllocator from ArenaAllocator by their main memory-management benefits.
Why it matters: These options support different needs: detecting missing frees or managing groups of allocations together. - Buffer and C allocators: Describe what FixedBufferAllocator and c_allocator wrap and when each is useful.
Why it matters: These allocators let you work with a supplied buffer or cooperate with C's allocator.
Key terms: stack memory, heap memory, allocator, system call, free, allocator paradigm, memory management, language runtime, SafeAllocator, ArenaAllocator
3.1.3 Not just I/O
This section explains why Zig’s std.Io groups several system capabilities together, distinguishes async from concurrency, and identifies the Io instance the book will usually use.
- Io as system abstraction: Explain why std.Io covers more than input and output: it provides access to common operating-system capabilities through an abstraction that helps programs work across platforms.
Why it matters: This explains why apparently unrelated facilities appear under std.Io. - Asynchrony versus concurrency: Distinguish asynchronous code from concurrent code, and describe why the section associates Io with Zig’s emphasis on asynchrony.
Why it matters: Keeping the two ideas separate avoids assuming that async code always runs operations at the same time. - Io implementations and default instance: Describe the section’s practical guidance on Io implementations and which instance the book generally uses.
Why it matters: It identifies the usual Io instance in the book’s examples without implying it is the only option.
Key terms: std.Io, Io instance, file system, networking, randomness, time, asynchronous, async, concurrent, runtime
3.2 Meow, says cat
The section defines the cat program’s basic behavior and introduces an iterative approach to implementing it.
- Cat program output behavior: Describe how the cat program uses command-line filenames to produce output.
Why it matters: This behavior is the baseline for judging whether the implementation works.
Key terms: cat, command line arguments, stdout
3.2.1 Adopting our first cat
The section introduces reading a file for a cat program using Zig’s file and directory handles and an allocator.
- File and directory handles: Explain what std.Io.File and std.Io.Dir are used for, what a handle represents, and why a Dir is used to open a relative path.
Why it matters: This explains why the first cat program works through a directory even when it wants to read a file. - Current directory file reading: Describe how the example obtains the current working directory and reads a file’s contents, including why readFileAlloc needs an allocator.
Why it matters: These are the pieces the example uses to read a file from the current working directory.
Key terms: std.Io.File, std.Io.Dir, handle, relative paths, std.Io.Dir.cwd, readFileAlloc, init.arena.allocator(), current working directory
3.2.2 Errors, catch and try
This section explains how Zig represents errors with error sets and error unions, then how callers handle or propagate those errors explicitly.
- Error sets and widening: Explain that Zig errors are values drawn from error sets, and describe when an error from a narrower set can be used as part of a wider set.
Why it matters: Error sets make the ways a function can fail explicit. - Error union return values: Describe what an error union can contain and how its type is written in a function return type.
Why it matters: A caller must account for both possible outcomes of a function returning an error union. - Handling error union branches: Trace how an if/else expression captures an error union's payload or error, and explain why catch is used for a common handling pattern.
Why it matters: These forms let a caller deal with failure while still using a successful result. - Explicit error propagation with try: Explain what Zig's try does to an error union and who remains responsible for an error it propagates.
Why it matters: Recognizing try shows where a function can pass failure to its caller.
Key terms: error sets, anyerror, coerce, error union, !, payload, if/else, capture groups, catch, try
3.2.3 The interface pattern
This section explains how Zig writers serve as interfaces to different output implementations and why that interface machinery is explicit.
- Writers and their implementations: Explain that a std.Io.Writer can write to different destinations because it is a generic interface backed by an implementation, much like an allocator.
Why it matters: This explains how code can work with a writer without being tied to one output destination. - Opaque pointers in generic code: Describe what anyopaque indicates about a pointer in generic code and what must happen before the referenced data can be used.
Why it matters: It clarifies one piece of the interface boilerplate without requiring the details of how to perform a cast. - Explicit interface boilerplate: Explain why Zig's interface boilerplate can look more involved than generic features in other languages.
Why it matters: It gives context for why a simple-looking generic capability may require visible boilerplate in Zig.
Key terms: std.Io.Writer, generic interfaces, underlying implementation, allocators, anyopaque, cast, interface boilerplate, object oriented features
3.3 Giving our cat more toys
This section introduces the cat prototype’s missing features and previews loops as a prerequisite for handling multiple files.
3.3.1 For loops
This section shows how Zig for loops iterate over arrays, slices, ranges, and multiple inputs, and how they can produce values or skip iterations.
- For loop item captures: Describe what Zig for loops can iterate over and how a capture names each item.
Why it matters: Item captures are the starting point for reading the loop examples in this section. - Multiple iterable captures: Explain how a for loop iterates over multiple arrays or slices together and why this is preferable to manually indexing them with a range.
Why it matters: Capturing paired items directly makes loops over related data easier to read and safer than manually indexing both. - Range based index capture: Describe how a range can accompany other loop inputs to capture the current index.
Why it matters: A range lets the same loop use both the data and its position. - Loop expression results: Explain how a for loop used as an expression gets its result from break or else.
Why it matters: The break-or-else result makes a search loop usable directly as a value. - Early iteration skipping: Distinguish continue from leaving a loop early, using the produce example.
Why it matters: Continue lets a loop omit unwanted items without stopping the whole traversal.
Key terms: for loops, indexable types, capture group, multiple iterables, captures, produce, counts, range, index, usize
3.3.2 Cat but it can concatenate
This subsection extends the cat program to concatenate files named on the command line and shows how to pass those names through zig run.
- Command-line file selection: Explain how the cat program obtains file names from command-line arguments and why it skips the first argument.
Why it matters: This is how the program selects multiple input files without treating its own name as one. - Arguments passed through zig run: Describe where arguments intended for the cat program go when launching it with zig run.
Why it matters: The two dashes distinguish arguments for the running program from the zig run invocation.
Key terms: std.process.Init, command line arguments, for loop, executable, zig run, two dashes
3.3.3 While loops
Introduces Zig while loops through a Collatz example and notes their built-in support for an end-of-iteration operation.
- Condition-controlled Collatz loop: Explain that a while loop repeats until its condition is false, and describe how the Collatz example uses repetition to count the steps from a starting number to one.
Why it matters: This example shows when a condition-controlled loop is useful. - End-of-iteration operation: State that Zig while loops have built-in syntax for an operation that runs at the end of every iteration.
Why it matters: It points out a convenience Zig provides for repeated loop bookkeeping.
Key terms: while, Collatz sequence, iterations, while loops, end of every iteration, built-in syntax
3.4 Questioning our cat
Introduces how Zig’s error features can help make the cat program more reliable by revealing possible failures and where they can occur.
- Visibility of cat program errors: Explain how Zig’s type-checked error sets and error-as-value semantics help reveal possible failures in the cat program.
Why it matters: Seeing both what can fail and where it can fail gives you a starting point for making the cat program more reliable.
Key terms: type-checked error sets, error-as-value semantics, syntax markers
3.4.1 All of the cat errors
Revisits the cat program to identify possible failures and decide which errors deserve user-facing handling rather than propagation.
- Explicit failure points and contracts: Explain how to find potential failures in the cat program and what an error set means for a function’s caller.
Why it matters: This gives you a practical way to audit code for failures before deciding how to respond. - Context dependent error responses: Distinguish when propagating an error, informing the user, or logging and continuing makes sense, using the cat program’s failures as examples.
Why it matters: Not every failure calls for the same response, even within a small program. - Whole file allocation costs: Explain the memory-related failure and cost of using readFileAlloc with the process’s arena in this cat program.
Why it matters: A convenient minimal implementation can still impose a significant memory limit and cost.
Key terms: try, return, error sets, main, stdout, CLI arguments, readFileAlloc, arena allocator, out of memory
3.4.2 Defer to better resource management
This section shows how to free each file’s contents reliably in the cat program by using a general purpose allocator and defer.
- Allocator cleanup strategies: Distinguish an arena allocator’s end-of-lifetime cleanup from a general purpose allocator’s requirement to free each allocation, and explain why the latter suits this cat program.
Why it matters: The choice of allocator determines when the program can release memory used for file contents. - Deferred cleanup on scope exit: Explain how defer prevents the file-content allocation from being missed when writing to stdout fails.
Why it matters: Deferred cleanup protects manually managed resources even when an operation fails early. - Error-only deferred cleanup: Distinguish errdefer from defer by stating when its cleanup runs.
Why it matters: The distinction lets the reader recognize cleanup intended specifically for an error return.
Key terms: arena allocator, general purpose allocator, gpa, free, defer, scope, try, errdefer
3.4.3 Improvement can be a waste of time
The section explains how to judge whether improving a program is worth the human effort, using the cat program to distinguish a practical need from a learning exercise.
- Code improvement tradeoffs: Explain why the best version of a program need not be optimal or infallible, and describe the costs and circumstances to weigh before improving it.
Why it matters: It helps you spend effort where an improvement will make a meaningful difference. - Computer focused improvement starting point: Describe the shift in thinking the author recommends after building a proof of concept.
Why it matters: It gives you a starting question for improving working code without assuming every possible improvement is worthwhile. - Cat as deliberate reinvention: Explain why the author continues improving cat despite its limited practical need.
Why it matters: It separates the reason for this exercise from the standard you would apply to a real project's needs.
Key terms: performance, reliability, human tradeoffs, maintenance, operating cost, reinventing wheels, proof of concept, minimal working program, cat, nuclear grade
3.4.4 Making the wheel nuclear grade
This section reduces a cat-like program to its essential file operations and error choices, then identifies an unnecessary whole-file allocation.
- Essential file copy steps: Describe the minimal file-copy sequence in operating-system terms: open each file for reading, read and write its data to stdout until none remains, then close it.
Why it matters: This sequence gives you a way to spot work the file-copy program does not need. - Failures during file copying: Distinguish the section’s responses to a failed open, a failed read or write, and a failed attempt to print an error message.
Why it matters: Different failures call for different responses depending on whether copying can reliably continue. - Unnecessary whole-file allocation: Explain why the existing use of readFileAlloc does extra work for this program and what removing that allocation would avoid.
Why it matters: It shows how reducing unnecessary work can also remove a possible failure.
Key terms: operating system, stdout, stderr, readFileAlloc, buffer, out of memory
3.4.5 Writer, meet reader
The section introduces std.Io.Reader and shows how pairing a reader with a writer lets the cat program stream file data.
- Readers and streaming: Explain that std.Io.Reader is a generic interface for sources of bytes and that, once a reader and writer are set up, one function can transfer bytes between them until none remain.
Why it matters: This explains how the cat program can copy data without manually handling each chunk of bytes. - Nonzero process exit: State that std.process.exit exits to the shell with a supplied code, allowing the program to exit with a non-zero code.
Why it matters: It gives the cat program a way to report failure through its exit code.
Key terms: std.Io.Reader, writer, streaming, std.process.exit, non-zero code
3.5 Buffering and building with Buff and Bill
Introduces conflicting buffer-size needs for the cat program and proposes compile-time configuration through a build script.
- Configurable cat buffer size: Explain why Bill and Buff want different buffer sizes and how the section proposes accommodating both: a build-script argument that configures buffer size during compilation.
Why it matters: Different users can request a cat program suited to their needs without requiring one fixed buffer size.
Key terms: comptime configuration, build script, buffer size
3.5.1 Why do we need build scripting?
Explains why a Zig project may move from `zig run` to a build script and introduces build steps and build graphs.
- Build script purpose: Explain why a project may use a build script instead of relying on `zig run`: it supplies configuration to automate compilation, from one executable to related libraries and executables.
Why it matters: It clarifies what a build script adds beyond the commands used for quick experiments. - Build steps and graph: Describe how a basic build script defines modules and their compilation through build steps, and how dependent steps form a build graph.
Why it matters: These terms give you a way to describe how a build script organizes compilation. - Programmable build flexibility: Explain why Zig build scripts can support modularizing and packaging code: they are Zig programs with access to code for shaping the build system.
Why it matters: It explains why a build script can adapt to more than a single compilation command.
Key terms: zig run, build script, compilation tasks, Zig modules, build steps, build graph, build scripts, Zig programs, modularize, package
3.5.2 Our build script
This section sets up a Zig build script for the cat program and explains how its executable is built, configured, and located.
- Zig project file layout: Describe where the cat program and its build script go in a conventional Zig project.
Why it matters: The file layout lets Zig find the build script and keeps the program’s entry point in its conventional location. - Executable build graph: Explain how the build script defines an executable build step and makes it run with zig build.
Why it matters: Connecting the executable to the install step is what makes the ordinary build command compile it. - Target and optimize options: Distinguish what target and optimize mode options control, including the mode used when none is specified.
Why it matters: These options let a build suit its destination and purpose instead of relying on the default Debug build. - Build output locations: Describe what appears after building the cat program and where to find its executable.
Why it matters: It tells you where to run the compiled program and which directory is merely the compiler’s cache.
Key terms: src, main.zig, build.zig, build function, std.Build, build graph, createModule, addExecutable, install step, target
3.5.3 To buffer, or not to buffer
This section uses build options and comptime values to produce cat programs with different buffering behavior, while introducing Zig optionals.
- Optional values and null: Explain how Zig represents a value that may be absent, and why an optional can be more appropriate than an error when a value is simply not found in a slice.
Why it matters: Optionals let code express an expected missing value without treating it as an error. - Optional value handling: Distinguish the three optional-handling forms described here: if capture, .?, and orelse.
Why it matters: These forms differ in whether they account for a missing value or assert that one is present. - Configurable cat buffering: Describe how build flags make buffer-size options available to cat and how the program behaves with buffering enabled versus disabled.
Why it matters: One cat program can be built with different buffer settings and corresponding I/O behavior. - Compile-time buffer sizes: Explain why a configured buffer size can appear in an array type definition in this program.
Why it matters: It explains why changing a build option can change the buffer array’s size without a runtime-sized array type.
Key terms: optionals, ?T, null, if, capture group, .?, orelse, zig build, options, readByte
3.5.4 Say goodbye to our cats
The section contrasts the satisfaction of making elegant code with the harder work of making software useful to real users.
- Useful software beyond elegant code: Explain why making code precise or beautiful is not enough to make it useful, and why real users and changing requirements demand flexibility and persistence.
Why it matters: It keeps the satisfaction of polishing code from overshadowing whether the software works for its users.
Key terms: useful software, real users, ever-changing requirements
3.6 Summary
Where this is used later
- Core logic (chapter 4) · Prior use of Zig errors and error unions.
- Check it (chapter 4) · The interface pattern used by allocators, writers, and readers.
- The HTTP cherry on top (chapter 4) · The earlier introduction to defer
- Talk to me (chapter 4) · Prior use of readers and writers.
- Maximizing modularity (chapter 6) · Earlier use of a Zig build script.
- Building with new blocks (chapter 6) · The build script provides the basis for configuring project builds.
- A minimally messy build process (chapter 7) · The earlier introduction to a Zig build script.
- Thinking in comptime (chapter 4) · provides an example of a value being available for use in a type at comptime
Concepts explained in this chapter
- error setAn error set is the statically specified set of error values that a function may produce.
- memory allocatorAn allocator is an abstraction that obtains and releases memory on behalf of program code.
- readFileAllocreadFileAlloc is a std.fs.Dir function that reads a file's contents into dynamically allocated memory.
- build scriptA build script is a program or declarative specification that defines how source code and dependencies are configured and compiled.
- comptimeComptime is Zig's compile-time execution feature that allows code to be evaluated during compilation.
- error handlingError handling is the representation and handling of failures that can occur during program execution.
- tryIn Zig, try is an error-propagation operator that returns an error from the enclosing function when its error-union operand contains an error.
- catchIn Zig, catch is an error-handling expression that evaluates an error-union operand and executes a fallback expression when the operand contains an error.
- command-line argumentA command line argument is a value supplied to a program when it is invoked from a command-line interface.
- Zig build systemThe Zig build system is the build tool integrated with Zig for compiling Zig, C, and C++ projects and controlling build configuration.
- error unionAn error union is a Zig type whose values contain either an error or a payload value of an inner type.
- build stageA build step is a unit of a build process that produces an output from source code or a preceding build step.
- deferIn Zig, defer schedules an expression or block to execute when the enclosing scope exits.
- std.Iostd.Io is Zig's standard-library interface for portable input/output operations, including buffered and concurrent I/O.
- bufferA buffer is a temporary memory area that holds data before it is processed or transferred.
- interfaceAn interface is an abstraction that exposes defined operations or services while hiding underlying implementation details.
- std.Io.Writerstd.Io.Writer is a Zig standard-library interface for writing data to output destinations.
- standard libraryA standard library is the collection of general-purpose modules and APIs distributed as part of a programming language implementation.
- ArenaArena allocation obtains storage from an arena and typically releases the storage collectively rather than freeing individual allocations.
- error codeAn error code is a value returned or stored to indicate that an operation failed and often identify the failure kind.
- heapHeap memory is dynamically managed storage requested during program execution for data whose size or lifetime is not fixed by a function call.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
