# std/syncio

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

This module implements various synchronized I/O operations.

# Imports

since, formatfloat, widestrs, ansi_c, exitprocs

# Types

    File = ptr CFile

  The type representing a file handle. Source Edit

    FileHandle = int

  Windows `HANDLE` type, convertible to `winlean.Handle`. Source Edit

    FileMode = enum
      fmRead,                   ## Open the file for read access only.
                                 ## If the file does not exist, it will not
                                 ## be created.
      fmWrite,                  ## Open the file for write access only.
                                 ## If the file does not exist, it will be
                                 ## created. Existing files will be cleared!
      fmReadWrite,              ## Open the file for read and write access.
                                 ## If the file does not exist, it will be
                                 ## created. Existing files will be cleared!
      fmReadWriteExisting,      ## Open the file for read and write access.
                                 ## If the file does not exist, it will not be
                                 ## created. The existing file will not be cleared.
      fmAppend                   ## Open the file for writing only; append data
                                 ## at the end. If the file does not exist, it
                                 ## will be created.

  The file mode when opening a file. Source Edit

    FileSeekPos = enum
      fspSet,                   ## Seek to absolute value
      fspCur,                   ## Seek relative to current position
      fspEnd                     ## Seek relative to end

  Position relative to which seek should happen. Source Edit

# Vars

    stderr {.importc: "stderr", header: "<stdio.h>".}: File

  The standard error stream. Source Edit

    stdin {.importc: "stdin", header: "<stdio.h>".}: File

  The standard input stream. Source Edit

    stdout {.importc: "stdout", header: "<stdio.h>".}: File

  The standard output stream. Source Edit

# Procs

    proc close(f: File) {....tags: [], gcsafe, sideEffect, ...raises: [], forbids: [].}

  Closes the file. Source Edit

    proc endOfFile(f: File): bool {....tags: [], gcsafe, raises: [], forbids: [].}

  Returns true if `f` is at the end. Source Edit

    proc flushFile(f: File) {....tags: [WriteIOEffect], raises: [], forbids: [].}

  Flushes `f`'s buffer. Source Edit

    proc getFileHandle(f: File): FileHandle {....raises: [], tags: [], forbids: [].}

  Returns the file handle of the file `f`. This is only useful for platform specific programming. Note that on Windows this doesn't return the Windows-specific handle, but the C library's notion of a handle, whatever that means. Use `getOsFileHandle` instead. Source Edit

    proc getFilePos(f: File): int64 {....gcsafe, raises: [IOError], tags: [],
                                      forbids: [].}

  Retrieves the current position of the file pointer that is used to read from the file `f`. The file's first byte has the index zero. Source Edit

    proc getFileSize(f: File): int64 {....tags: [ReadIOEffect], gcsafe,
                                       raises: [IOError], forbids: [].}

  Retrieves the file size (in bytes) of `f`. Source Edit

    proc getOsFileHandle(f: File): FileHandle {....raises: [], tags: [], forbids: [].}

  Returns the OS file handle of the file `f`. This is only useful for platform specific programming. Source Edit

    proc open(f: var File; filehandle: FileHandle; mode: FileMode = fmRead): bool {.
        ...tags: [], raises: [], gcsafe, forbids: [].}

  Creates a `File` from a `filehandle` with given `mode`.

  Default mode is readonly. Returns true if the file could be opened.

  The passed file handle will no longer be inheritable.

  Source Edit

    proc open(f: var File; filename: string; mode: FileMode = fmRead;
              bufSize: int = -1): bool {....tags: [], raises: [], gcsafe, forbids: [].}

  Opens a file named `filename` with given `mode`.

  Default mode is readonly. Returns true if the file could be opened. This throws no exception if the file could not be opened.

  The file handle associated with the resulting `File` is not inheritable.

  Source Edit

    proc open(filename: string; mode: FileMode = fmRead; bufSize: int = -1): File {.
        ...raises: [IOError], tags: [], forbids: [].}

  Opens a file named `filename` with given `mode`.

  Default mode is readonly. Raises an `IOError` if the file could not be opened.

  The file handle associated with the resulting `File` is not inheritable.

  Source Edit

    proc readAll(file: File): string {....tags: [ReadIOEffect], gcsafe,
                                       raises: [IOError], forbids: [].}

  Reads all data from the stream `file`.

  Raises an IO exception in case of an error. It is an error if the current file position is not at the beginning of the file.

  Source Edit

    proc readBuffer(f: File; buffer: pointer; len: Natural): int {.
        ...tags: [ReadIOEffect], gcsafe, raises: [IOError], forbids: [].}

  Reads `len` bytes into the buffer pointed to by `buffer`. Returns the actual number of bytes that have been read which may be less than `len` (if not as many bytes are remaining), but not greater. Source Edit

    proc readBytes(f: File; a: var openArray[int8 | uint8]; start, len: Natural): int {.
        ...tags: [ReadIOEffect], gcsafe.}

  Reads `len` bytes into the buffer `a` starting at `a[start]`. Returns the actual number of bytes that have been read which may be less than `len` (if not as many bytes are remaining), but not greater. Source Edit

    proc readChar(f: File): char {....tags: [ReadIOEffect],
                                   raises: [IOError, EOFError], forbids: [].}

  Reads a single character from the stream `f`. Should not be used in performance sensitive code. Source Edit

    proc readChars(f: File; a: var openArray[char]): int {....tags: [ReadIOEffect],
        gcsafe, raises: [IOError], forbids: [].}

  Reads up to `a.len` bytes into the buffer `a`. Returns the actual number of bytes that have been read which may be less than `a.len` (if not as many bytes are remaining), but not greater. Source Edit

    proc readChars(f: File; a: var openArray[char]; start, len: Natural): int {.
        ...tags: [ReadIOEffect], gcsafe, deprecated: "use other `readChars` overload, possibly via: readChars(toOpenArray(buf, start, len-1))",
        raises: [IOError], forbids: [].}

  Deprecated: use other `readChars` overload, possibly via: readChars(toOpenArray(buf, start, len-1))
  Reads `len` bytes into the buffer `a` starting at `a[start]`. Returns the actual number of bytes that have been read which may be less than `len` (if not as many bytes are remaining), but not greater. Source Edit

    proc readFile(filename: string): string {....tags: [ReadIOEffect], gcsafe,
        raises: [IOError], forbids: [].}

  Opens a file named `filename` for reading, calls readAll and closes the file afterwards. Returns the string. Raises an IO exception in case of an error. If you need to call this inside a compile time macro you can use staticRead. Source Edit

    proc readLine(f: File): string {....tags: [ReadIOEffect], gcsafe,
                                     raises: [IOError, EOFError], forbids: [].}

  Reads a line of text from the file `f`. May throw an IO exception. A line of text may be delimited by `LF` or `CRLF`. The newline character(s) are not part of the returned string. Source Edit

    proc readLine(f: File; line: var string): bool {....tags: [ReadIOEffect], gcsafe,
        raises: [IOError], forbids: [].}

  Reads a line of text from the file `f` into `line`. May throw an IO exception. A line of text may be delimited by `LF` or `CRLF`. The newline character(s) are not part of the returned string. Returns `false` if the end of the file has been reached, `true` otherwise. If `false` is returned `line` contains no new data. Source Edit

    proc readLines(filename: string; n: Natural): seq[string] {.
        ...raises: [IOError, EOFError], tags: [ReadIOEffect], forbids: [].}

  Reads `n` lines from the file named `filename`. Raises an IO exception in case of an error. Raises EOF if file does not contain at least `n` lines. Available at compile time. A line of text may be delimited by `LF` or `CRLF`. The newline character(s) are not part of the returned strings. Source Edit

    proc reopen(f: File; filename: string; mode: FileMode = fmRead): bool {.
        ...tags: [], gcsafe, raises: [], forbids: [].}

  Reopens the file `f` with given `filename` and `mode`. This is often used to redirect the `stdin`, `stdout` or `stderr` file variables.

  Default mode is readonly. Returns true if the file could be reopened.

  The file handle associated with `f` won't be inheritable.

  Source Edit

    proc setFilePos(f: File; pos: int64; relativeTo: FileSeekPos = fspSet) {....gcsafe,
        sideEffect, ...raises: [IOError], tags: [], forbids: [].}

  Sets the position of the file pointer that is used for read/write operations. The file's first byte has the index zero. Source Edit

    proc setInheritable(f: FileHandle; inheritable: bool): bool {....raises: [],
        tags: [], forbids: [].}

  Controls whether a file handle can be inherited by child processes. Returns `true` on success. This requires the OS file handle, which can be retrieved via getOsFileHandle.

  This procedure is not guaranteed to be available for all platforms. Test for availability with declared().

  Source Edit

    proc setStdIoUnbuffered() {....tags: [], gcsafe, raises: [], forbids: [].}

  Configures `stdin`, `stdout` and `stderr` to be unbuffered. Source Edit

    proc write(f: File; a: varargs[string, `$`]) {....tags: [WriteIOEffect], gcsafe,
        raises: [IOError], forbids: [].}

  Source Edit

    proc write(f: File; b: bool) {....tags: [WriteIOEffect], gcsafe, raises: [IOError],
                                   forbids: [].}

  Source Edit

    proc write(f: File; c: char) {....tags: [WriteIOEffect], gcsafe, raises: [],
                                   forbids: [].}

  Source Edit

    proc write(f: File; c: cstring) {....tags: [WriteIOEffect], gcsafe,
                                      raises: [IOError], forbids: [].}

  Writes a value to the file `f`. May throw an IO exception. Source Edit

    proc write(f: File; i: BiggestInt) {....tags: [WriteIOEffect], gcsafe,
                                         raises: [IOError], forbids: [].}

  Source Edit

    proc write(f: File; i: int) {....tags: [WriteIOEffect], gcsafe, raises: [IOError],
                                  forbids: [].}

  Source Edit

    proc write(f: File; r: BiggestFloat) {....tags: [WriteIOEffect], gcsafe,
                                           raises: [IOError], forbids: [].}

  Source Edit

    proc write(f: File; r: float32) {....tags: [WriteIOEffect], gcsafe,
                                      raises: [IOError], forbids: [].}

  Source Edit

    proc write(f: File; s: string) {....tags: [WriteIOEffect], gcsafe,
                                     raises: [IOError], forbids: [].}

  Source Edit

    proc writeBuffer(f: File; buffer: pointer; len: Natural): int {.
        ...tags: [WriteIOEffect], gcsafe, raises: [IOError], forbids: [].}

  Writes the bytes of buffer pointed to by the parameter `buffer` to the file `f`. Returns the number of actual written bytes, which may be less than `len` in case of an error. Source Edit

    proc writeBytes(f: File; a: openArray[int8 | uint8]; start, len: Natural): int {.
        ...tags: [WriteIOEffect], gcsafe.}

  Writes the bytes of `a[start..start+len-1]` to the file `f`. Returns the number of actual written bytes, which may be less than `len` in case of an error. Source Edit

    proc writeChars(f: File; a: openArray[char]; start, len: Natural): int {.
        ...tags: [WriteIOEffect], gcsafe, raises: [IOError], forbids: [].}

  Writes the bytes of `a[start..start+len-1]` to the file `f`. Returns the number of actual written bytes, which may be less than `len` in case of an error. Source Edit

    proc writeFile(filename, content: string) {....tags: [WriteIOEffect], gcsafe,
        raises: [IOError], forbids: [].}

  Opens a file named `filename` for writing. Then writes the `content` completely to the file and closes the file afterwards. Raises an IO exception in case of an error. Source Edit

    proc writeFile(filename: string; content: openArray[byte]) {....raises: [IOError],
        tags: [WriteIOEffect], forbids: [].}

  Opens a file named `filename` for writing. Then writes the `content` completely to the file and closes the file afterwards. Raises an IO exception in case of an error. Source Edit

    proc writeLine[Ty](f: File; x: varargs[Ty, `$`]) {.inline,
        ...tags: [WriteIOEffect], gcsafe.}

  Writes the values `x` to `f` and then writes "\n". May throw an IO exception. Source Edit

# Iterators

    iterator lines(f: File): string {....tags: [ReadIOEffect], raises: [IOError],
                                      forbids: [].}

  Iterates over any line in the file `f`.

  The trailing newline character(s) are removed from the iterated lines.

  Example:

      proc countZeros(filename: File): tuple[lines, zeros: int] =
        for line in filename.lines:
          for letter in line:
            if letter == '0':
              result.zeros += 1
          result.lines += 1

  Source Edit

    iterator lines(filename: string): string {....tags: [ReadIOEffect],
        raises: [IOError, IOError], forbids: [].}

  Iterates over any line in the file named `filename`.

  If the file does not exist `IOError` is raised. The trailing newline character(s) are removed from the iterated lines. Example:

  Example:

      import std/strutils

      proc transformLetters(filename: string) =
        var buffer = ""
        for line in filename.lines:
          buffer.add(line.replace("a", "0") & '\n')
        writeFile(filename, buffer)

  Source Edit

# Templates

    template `&=`(f: File; x: typed)

  An alias for `write`. Source Edit

    template readLines(filename: string): seq[string] {.
        ...deprecated: "use readLines with two arguments".}

  Deprecated: use readLines with two arguments
  Source Edit

    template stdmsg(): File

  Template which expands to either stdout or stderr depending on `useStdoutAsStdmsg` compile-time switch. Source Edit