# io

Dark Mode

- Manual
- Standard library
- Index

Search:
Group by:

This is a part of `system.nim`, you should not manually import it.

# Types

    File = ptr CFile

  The type representing a file handle. Source Edit

    FileMode = enum
      fmRead,                   ## Open the file for read access only.
      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.

  The file mode when opening a file. Source Edit

    FileHandle = cint

  type that represents an OS file handle; this is useful for low-level file access Source Edit

# Vars

    stdin: File

  The standard input stream. Source Edit

    stdout: File

  The standard output stream. Source Edit

    stderr: File

  The standard error stream. Source Edit

# Procs

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

  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, locks: 0.}

  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 readChars(f: File; a: var openArray[char]; start, len: Natural): int {...}{.
        tags: [ReadIOEffect], gcsafe, locks: 0, raises: [IOError].}

  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.

  Warning: The buffer `a` must be pre-allocated. This can be done using, for example, `newString`.

  Source Edit

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

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

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

  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, locks: 0.}

  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, locks: 0, raises: [IOError].}

  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 write(f: File; s: string) {...}{.tags: [WriteIOEffect], gcsafe, locks: 0,
                                     raises: [IOError].}

  Source Edit

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

  Closes the file. Source Edit

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

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

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

  Flushes `f`'s buffer. Source Edit

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

  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 getOsFileHandle(f: File): FileHandle {...}{.raises: [], tags: [].}

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

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

  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 readLine(f: File): TaintedString {...}{.tags: [ReadIOEffect], gcsafe, locks: 0,
                                            raises: [IOError, EOFError].}

  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 write(f: File; i: int) {...}{.tags: [WriteIOEffect], gcsafe, locks: 0,
                                  raises: [IOError].}

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

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

    proc readAll(file: File): TaintedString {...}{.tags: [ReadIOEffect], gcsafe,
        locks: 0, raises: [IOError].}

  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 writeLine[Ty](f: File; x: varargs[Ty, `$`]) {...}{.inline,
        tags: [WriteIOEffect], gcsafe, locks: 0.}

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

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

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

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

  Source Edit

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

  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 iff the file could be reopened.

  Source Edit

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

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

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

  Source Edit

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

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

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

  Source Edit

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

  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 getFilePos(f: File): int64 {...}{.gcsafe, locks: 0, raises: [IOError], tags: [].}

  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, locks: 0,
                                       raises: [IOError].}

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

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

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

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

  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 writeFile(filename, content: string) {...}{.tags: [WriteIOEffect], gcsafe,
        locks: 0, raises: [IOError].}

  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].}

  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 readLines(filename: string; n: Natural): seq[TaintedString] {...}{.
        raises: [IOError, EOFError], tags: [ReadIOEffect].}

  read `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

# Iterators

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

  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:

      import strutils

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

  Source Edit

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

  Iterate 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

# Templates

    template stdmsg(): File

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

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

  Deprecated: use readLines with two arguments
  Source Edit