tur/io

(defopaque DirListing :ptr<void>)

(defopaque FileStream :ptr<void>)

(file-stream-open [path :cstr mode :cstr] :FileStream)

open a file as a non-linear FileStream handle.

(let [s (file-stream-open "/etc/hostname" "rb")] (file-size s))

Since: I/O sweep

(file-stream-ok? [f :FileStream] :bool)

return true if the FileStream wraps a real FILE*.

(file-stream-ok? (file-stream-open "/etc/hostname" "rb"))  ; => true

Since: I/O sweep

(file-stream-close [f :FileStream] :int)

close a FileStream and release the underlying FILE*.

(file-stream-close s)  ; => 0

Since: I/O sweep

(file-size [f :FileStream] :int)

return the byte size of an already-open FileStream.

(file-size my-stream)  ; => 1024

(Real-FileSystem :FileSystem)

(Real-FileSystem-free [fs :FileSystem] :void)

release a FileSystem capability created by Real-FileSystem.

Since: Phase 16

(list-dir [path :cstr] :DirListing)

list all non-hidden entries in a directory.

(let [entries (list-dir "/tmp")] ...)

Since: Phase 16

(free-dir-listing [entries :DirListing] :void)

free a directory listing returned by list-dir.

Since: Phase 16

(defopaque FileHandle :ptr<void> :linear)

a linear (exactly-once) handle over a stdio FILE*.

:linear (CK_LINEAR) means every bound FileHandle must be explicitly consumed by file-close; the compiler emits TUR-E0100 if a linear value is silently dropped. The read/write/seek operations take it ^borrow.

stdlib-os-surface-plan P1: a FileHandle only ever exists for a file that opened -- file-open answers (Result FileHandle IoError) -- so there is no NULL handle to test for. (It was a one-field struct around the FILE*; an opaque says the same thing and rides a Result payload as one word.)

Since: LT4

(file-open [path :cstr mode :cstr])

open a file and return a move-only FileHandle.

(match (file-open "/etc/hostname" "rb")
  (Ok fh) (file-close fh)
  (Err e) (Err e))

Since: LT4

(file-read [^borrow fh :FileHandle buf :ptr<void> len :int])

read up to len bytes from fh into buf.

(file-read fh buf 1024)  ; => (Ok 512)

Since: LT4

(file-close [fh :FileHandle])

close a FileHandle and release the underlying FILE*.

(file-close fh)  ; => (Ok nil)

Since: LT4

(file-sync [^borrow fh :FileHandle])

flush a FileHandle all the way to the storage device.

Pushes the stdio buffer to the OS (fflush), then asks the OS to write its cached pages to disk (fsync; _commit on Windows), so the data survives a crash or power loss once this returns Ok. file-close alone does only the first half.

(file-sync fh)  ; => (Ok nil)

Since: stdlib-os-surface P3

(defdata SeekFrom :copy (SeekStart) (SeekCurrent) (SeekEnd))

the origin a file-seek offset is measured from.

SeekStart is the beginning of the file (SEEK_SET), SeekCurrent the current position (SEEK_CUR), SeekEnd the end of the file (SEEK_END). A tagged union rather than an int whence, so a caller cannot pass a stray integer.

Since: stdlib-os-surface P0

(seek-from->whence [w :SeekFrom] :int)

the C whence constant for a SeekFrom.

(file-write [^borrow fh :FileHandle buf :ptr<void> len :int])

write len bytes from buf to fh.

(file-write fh buf 13)  ; => (Ok 13)

Since: stdlib-os-surface P0

(file-write-str [^borrow fh :FileHandle s :cstr])

write a NUL-terminated string to fh (no newline added).

(file-write-str fh "hello\n")  ; => (Ok 6)

Since: stdlib-os-surface P0

(file-seek-raw [^borrow fh :FileHandle offset :int whence :int])

fseek(3) with a C whence constant (internal).

(file-seek [^borrow fh :FileHandle offset :int whence :SeekFrom])

move fh's position to offset, measured from whence.

(file-seek fh 0 (SeekEnd))  ; => (Ok file-size)

Since: stdlib-os-surface P0

(file-tell [^borrow fh :FileHandle])

the current byte position of fh.

(file-tell fh)  ; => (Ok 0)

Since: stdlib-os-surface P0

(io/read-line)

read one line from stdin.

The trailing newline (and a CR before it) is stripped. The last line of input counts even without a trailing newline. Uses getline(3) on POSIX and an fgets loop on Windows, which has no getline.

(match (io/read-line)
  (Some s) (println s)
  (None)   (println "<eof>"))

Since: stdlib-os-surface P0

(io/read-stdin)

read all of stdin into one string.

Reads until end of input, so it works on a pipe or a terminal as well as a redirected file.

(match (io/read-stdin) (Some s) (println s) (None) (println "read failed"))

Since: stdlib-os-surface P0

(file-read-line-raw [^borrow fh :FileHandle])

one line, EOF as an errno-0 error (internal).

(file-read-line [^borrow fh :FileHandle])

read the next line from fh.

The bounded-memory way through a large file: one line per call, with the newline (and a CR before it) stripped. The last line counts without a trailing newline. Shares its reader with io/read-line.

(match (file-read-line fh)
  (Ok o)  (match o (Some s) (println s) (None) (println "<eof>"))
  (Err e) (println (io-error/message e)))

Since: stdlib-os-surface P2