--- title: dankogai/swift-posix framework: Swift Package Catalog role: article path: packages/dankogai/swift-posix --- # dankogai/swift-posix A thin but swifty POSIX layer. ## Exporting on demand Like Perl's `use POSIX ()` vs `use POSIX`, you choose how much lands in your namespace. `import POSIX` (above) exports nothing but the `POSIX` namespace itself. When you want the names at the top level, opt in: ```swift import POSIXGlobals // Perl-style: everything exported let cwd = try getcwd() let st = try stat("Package.swift") strftime("%Y-%m-%d", gmtime(0)) ``` or cherry-pick single symbols, `@EXPORT_OK`-style, with Swift's scoped imports: ```swift import POSIX import func POSIXGlobals.floor // just floor at the top level import struct POSIXGlobals.Errno // just Errno floor(3.7) // 3.0 ``` Both modules ship in the one `POSIX` library product, and they share the same underlying types, so the two styles mix freely. ## Requirements Swift 6.0 or later, on macOS (Darwin) or Linux (Glibc). ## Usage Add to your `Package.swift`: ```swift .package(url: "https://github.com/dankogai/swift-posix.git", from: "0.0.1") ``` and `import POSIX` (namespaced) or `import POSIXGlobals` (top-level names). The namespaced form never collides with Foundation or the C overlays, no matter what else you import. ## Design * **Same names as C** — `getcwd`, `strftime`, `mkfifo`, `SIGINT`, `O_CREAT`. If you know POSIX you already know this module. Swifty renaming is limited to types (`Stat`, `Tm`, `SigSet`, …) which C spells the same as functions. * **`String` where C has `char *`** — and `[UInt8]` where C means bytes (`read`/`write`). * **`throws Errno` where C returns -1** — `Errno` is a `RawRepresentable` error with all the `E*` constants (`Errno.ENOENT`) and a `strerror` description. Functions that cannot fail (`getpid`) don't throw. * **Swifty structs where C has structs** — `Stat`, `Tm`, `Times`, `Utsname`, `Lconv`, `Termios`, `WaitStatus`, `SigSet`, `SigAction`, `Passwd`, `Group`, and `Dir` (a `Sequence` of entry names). Macros become properties: `S_ISDIR(st_mode)` is `st.isDirectory`, `WIFEXITED(status)` is `status.exited`. * **`OptionSet`s and wrapper types where C has flag/enum constants** — `OpenFlags`, `FilePermissions`, `AccessMode`, `WaitOptions`, `Signal`, `LocaleCategory`, `Whence`, `BaudRate`, and the `Termios` flag sets, each with the original C constant names as members. * **Out-parameters become tuples** — `frexp`, `modf`, `remquo`, `strtod`, `strtol`, `pipe`, `wait`, `mkstemp`. * **Thin** — no Foundation, no dependencies; every wrapper is a few lines over libc. ## What's deliberately not implemented Perl's POSIX module leaves the C-specific functions unimplemented and croaks with advice ("C-specific: use eval {} instead"). This module keeps that interface parity: `atoi`, `malloc`, `strlen`, `printf`, `setjmp`, `qsort`, `execl`, and friends all exist but halt with `fatalError` pointing at the swifty way: ```swift strlen("hello") // Fatal error: POSIX.strlen() is C-specific and unimplemented: // use String.count or utf8.count ``` ## Documentation and examples * **Manuals** live in [docs/](docs/README.md) — one per header, with signatures and examples. * **Playground**: [macOS.playground](macOS.playground) walks the whole library interactively. Open the package directory in Xcode, build the **POSIX** scheme once (⌘B), then open the playground pages. ## Coverage | header | manual | provided | |---|---|---| | `` | [CType.md](docs/CType.md) | `isalpha` … `isxdigit`, `tolower`, `toupper` (Perl semantics: whole-string tests, C-locale/ASCII rules) | | `` | [Dirent.md](docs/Dirent.md) | `Dir` (a `Sequence`), `opendir`, `readdir`, `rewinddir`, `telldir`, `seekdir`, `closedir` | | `` | [Errno.md](docs/Errno.md) | `Errno` with `E*` constants, `strerror`, `Errno.current` | | `` | [Fcntl.md](docs/Fcntl.md) | `open`, `creat`, `fcntl` with `OpenFlags`, `FcntlCommand`, `FD_CLOEXEC` | | `` | [Math.md](docs/Math.md) | `fegetround`, `fesetround`, `FE_*` | | ``, `` | [Limits.md](docs/Limits.md) | `DBL_MAX`, `INT_MAX`, … (defined from Swift's numeric types) | | ``, `` | [PwdGrp.md](docs/PwdGrp.md) | `getpwnam`, `getpwuid`, `getgrnam`, `getgrgid` returning `Passwd`/`Group` | | `` | [Locale.md](docs/Locale.md) | `setlocale` with `LocaleCategory`, `localeconv` returning `Lconv` | | `` | [Math.md](docs/Math.md) | the full C99 repertoire, `Double` in and out; `fpclassify` returns Swift's `FloatingPointClassification` | | `` | [Signal.md](docs/Signal.md) | `Signal` constants, `kill`, `raise`, `signal`, `sigaction`, `SigSet`, `sigprocmask`, `sigpending`, `sigsuspend` | | `` | [Stdio.md](docs/Stdio.md) | `ctermid`, `cuserid`, `remove`, `rename`, `mkstemp` (stream I/O is C-specific — unimplemented) | | `` | [Stdlib.md](docs/Stdlib.md) | `exit`, `abort`, `getenv`/`setenv`/`unsetenv`, `strtod`/`strtol`/`strtoul`, `mblen`/`mbtowc`/`wctomb`/`mbstowcs`/`wcstombs` | | `` | [Stdlib.md](docs/Stdlib.md) | `strcoll`, `strxfrm` (the rest is C-specific — unimplemented) | | `` | [SysStat.md](docs/SysStat.md) | `Stat`, `stat`, `lstat`, `fstat`, `chmod`, `mkdir`, `mkfifo`, `umask`, `utime` | | `` | [Time.md](docs/Time.md) | `times` returning `Times` (with elapsed real time, like Perl's) | | `` | [SysUtsname.md](docs/SysUtsname.md) | `uname` returning `Utsname` | | `` | [SysWait.md](docs/SysWait.md) | `wait`, `waitpid`, `WaitStatus` (the `W*` macros as properties) | | `` | [Termios.md](docs/Termios.md) | `Termios` with typed flag sets and `BaudRate`, `tcgetattr`, `tcsetattr`, `tcdrain`, `tcflow`, `tcflush`, `tcsendbreak` | | `` | [Time.md](docs/Time.md) | `Tm`, `time`, `gmtime`, `localtime`, `mktime`, `strftime`, `asctime`, `ctime`, `difftime`, `clock`, `tzset`, `tzname` | | `` | [Unistd.md](docs/Unistd.md) | ids, `fork`, `pipe`, `read`, `write`, `open`/`close`/`dup`/`lseek`, `getcwd`/`chdir`, `link`/`unlink`/`rmdir`, `access`, `sysconf`/`pathconf`, `isatty`/`ttyname`, `alarm`/`pause`/`sleep`, `getgroups`, `getlogin`, `nice`, `tcgetpgrp`/`tcsetpgrp` | ## License MIT. See [LICENSE](LICENSE). ## Package Metadata Repository: dankogai/swift-posix Default branch: main README: README.md