# 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

# Types

    File = ptr CFile

  The type representing a file handle. Source Edit

    FileHandle = cint

  type that represents an OS file handle; this is useful for low-level file access 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: [].}

  control 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() <system.html#declared,untyped>`.

  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