API Roadmap

This is meant to be a continuously-updated list of API candidates for System.

## Criteria for Inclusion

System's primary aim is to be the place developers go to access native platform interfaces, presented in as Swifty a way as feasible. This positions System as a successor to Darwin/GlibC/SwiftWin32 and a “bedrock” upon which to enable better systems-level programming in Swift.

System is not aiming to be a cross-platform abstraction layer; there will be platform differences reflected in System's API. Of course, if a concept can be expressed the same way across platforms without harm or significant compromise to the developer's native experience on that platform, that's great. But, System's API should feel natural and native for the target platform.

System aims to provide API in 3 areas:

1. As-Swifty-as-we-reasonably-can direct access to system calls and types

If a system interface exists, that’s strong justification for providing access to it in System as faithfully as we can.

2. Common types for library API at the systems level

System hosts common types for systems level programming, enabling libraries built on top of System to use the same, well-crafted types in their API.

For example, many API take locations in the file system, for which `FilePath` provides a common expression.

3. High-value utility functionality and abstractions, where appropriate

System provides common utilities that users of System would otherwise find themselves having to reinvent. These usually have some combination of being pervasive, having obvious desired behavior, and being difficult/onerous to implement correctly.

For example, ensuring that a file descriptor is closed under all (non-pathological) conditions can be complex in the presence of error-handling, so System provides `FileDescriptor.closeAfter`.

This area has a higher bar for contribution, requiring more justification and thought. What is "obvious desired behavior" and "correct" can differ amongst users of System.

## Roadmap

### Released

* [0.0.1](https://github.com/apple/swift-system/releases/tag/0.0.1)
* syscalls: `read`, `write`, `lseek`, `pread`, `pwrite`, `open`, `close`
* types: `FilePath`, `FileDescriptor`, `Errno`, `FilePermissions`
* helpers: `closeAfter`, `writeAll`
* [0.0.2](https://github.com/apple/swift-system/releases/tag/0.0.2)
* [FilePath Syntactic Operations](https://github.com/apple/swift-system/pull/14)
* decompose a path, analyze a path, components view, mutate a path, etc
* [Standard file descriptors](https://github.com/apple/swift-system/pull/21)
* static `FileDescriptor.standardInput`, `FileDescriptor.standardOutput`, `FileDescriptor.standardError`
* [dup/dup2](https://github.com/apple/swift-system/pull/28)
* `FileDescriptor.duplicate`, with optional `as` target.

### Merged

### In Progress

* [Strongly-typed process and signal wrappers](https://github.com/apple/swift-system/pull/20)
* `ProcessID`, `Signal`, `SignalSet`, `ProcessID.TaskInfo`, `ProcessID.ResourceUsageInfo`
* TODO: `posix_spawn` and `execv` functionality and interfaces
* [Initial socket support](https://github.com/apple/swift-system/pull/30)
* [Pipes](https://github.com/apple/swift-system/pull/58)

### Sketches

Sketches are merge-worthy, quick-but-complete presentations of systems interfaces. They help to surface unknown-unknowns and can be easily adapted into a proposal. They are not necessarily named or expressed in their final form.

* [`fcntl`](https://github.com/apple/swift-system/pull/44)
* [`sysconf`, `pathconf`, `fpathconf`](https://github.com/apple/swift-system/pull/33)
* [`openat`, `fsync`, `sync`](https://github.com/apple/swift-system/pull/43)

### Starter tasks

* Add support for `pipe`

### Near Term

Anything here could be added to System in the near term. Most of the functionality can be added by following existing API design patterns, though some will need new patterns.

* sleep capabilities (e.g. `usleep`)
* FilePath semantic (i.e. file-system interacting) operations
* `stat`, `chown`, directory iteration, etc.
* temporary files
* `pthread` low-level interfaces
* Further networking and sockets functionality
* `getaddrinfo`, `gethostent`, etc.
* Environment variables
* FilePath: `~` expansion, `currentWorkingDirectory`
* OSString-like abstraction
* Null-terminated bytes on Unix, wchar or bytes on Windows (pending investigation)
* I/O events
* `kqueue`/`kevent` for Darwin, `epoll` for Linux, APC (or something similar) for Windows
* exit handling
* `exit`, `atexit`, etc
* tty
* `ioctl`, etc
* Fleshing out FileDescriptor more
* `chmod`, `umask`, etc.

### Long Term (vague "blue-sky" hopes)

* moveonly `File` type
* high level `Process` type
* `io_uring` on Linux

Start with the roadmap's Starter tasks entry for adding support for pipe, then read the existing API design patterns used by System's released system calls and types. Confirm the platform interfaces and intended Swift API shape with maintainers; the work is complete when pipe support is implemented consistently with those patterns.

Written by the indexing model from the issue text.