Types
File = ref FileImpl
- An object representing a file. This is an opaque object with differing implementations depending on the target operating system. Source Edit
FileFlag = enum ffRead, ## Open file for reading. ffWrite, ## Open file for writing. ffAppend, ## When writing, append data to end-of-file. ffTruncate, ## Truncate file when opening. ffInheritable ## Allow file handle to be inherited automatically by ## child processes.
- Flags that control file behaviors. Source Edit
Procs
proc initIOError(e: var IOError; bytesTransferred: Natural; errorCode: int32; additionalInfo = "") {.inline, ...raises: [], tags: [], forbids: [].}
- Initializes an IOError object. Source Edit
proc newAsyncFile(fd: FD): AsyncFile {....raises: [], tags: [], forbids: [].}
-
Creates a new ref AsyncFile object from an opened file handle.
The ownership of the file handle will be transferred to the resulting ref AsyncFile.
Note: It is assumed that the file handle has been opened in asynchronous mode. Only use this interface if you know what you are doing.
Platform specific details
- On Windows, the file position will always start at the beginning of the file if the file is seekable.
proc newFile(fd: FD): File {....raises: [], tags: [], forbids: [].}
-
Creates a new ref File from an opened file handle.
The ownership of the file handle will be transferred to the resulting ref File.
Note: It is assumed that the file handle has been opened in synchronous mode. Only use this interface if you know what you are doing.
Source Edit proc newIOError(bytesTransferred: Natural; errorCode: int32; additionalInfo = ""): ref IOError {. ...raises: [], tags: [], forbids: [].}
- Creates a new ref IOError. Source Edit
proc read(f: AsyncFile; b: ref seq[byte]): int {....raises: [ValueError, IOError], tags: [], forbids: [].}
-
Reads up to b.len bytes from file f into b.
This is an overload of read(), please refer to its documentation for more information.
Source Edit proc read(f: AsyncFile; b: ref string): int {....raises: [ValueError, IOError], tags: [], forbids: [].}
-
Reads up to b.len bytes from file f into b.
This is an overload of read(), please refer to its documentation for more information.
Source Edit proc read(f: AsyncFile; buf: ptr UncheckedArray[byte]; bufLen: Natural): int {. ...raises: [ValueError, IOError], tags: [], forbids: [].}
-
Reads up to bufLen bytes from file f into buf.
buf might be nil only if bufLen is 0.
buf must stays alive for the duration of the read. Direct usage of this interface is discouraged due to its unsafetyness. Users are encouraged to use high-level overloads that keep buffers alive.
If the file position is at the end-of-file, no data will be read and no error will be raised.
If f is a pipe and the write end has been closed, no data will be read and no error will be raised.
This function is not thread-safe.
Returns the number of bytes read from f.
Platform specific details
On Windows, for seekable files, the file position is implemented by the library and may overflow, though it is unlikely for that to happen due to most file system having a maximum file size of 2^64.
If you have to deal with file systems where the maximum file size exceeds that of conventional file systems, it is recommended to use File with threads for asynchronous operations.
- On Windows, most disk IOs are not asynchronous, see this article from Microsoft for more details. If asynchronous disk operations are required, it is recommended to use File with threads or carefully evaluate the limitations.
- On POSIX systems, disk IOs are never asynchronous. This is an unfortunate property of the specification. It is recommended to use File with threads for those use cases. This might change in the future.
- On POSIX systems, signals will not interrupt the operation.
proc read[T: byte or char](f: File; b: var openArray[T]): int {. ...raises: [IOError].}
-
Reads up to b.len bytes from file f into b.
If the file position is at the end-of-file, no data will be read and no error will be raised.
If f is a pipe and the write end has been closed, no data will be read and no error will be raised.
Returns the number of bytes read from f.
Platform specific details
- On POSIX systems, signals will not interrupt the operation if nothing was read.
proc write(f: AsyncFile; b: ref seq[byte]): int {....raises: [ValueError, IOError], tags: [], forbids: [].}
-
Writes the contents of array b into file f.
This is an overload of write(), please refer to its documentation for more information.
Source Edit proc write(f: AsyncFile; b: ref string): int {....raises: [ValueError, IOError], tags: [], forbids: [].}
-
Writes the contents of array b into file f.
This is an overload of write(), please refer to its documentation for more information.
Source Edit proc write(f: AsyncFile; b: seq[byte]): int {....raises: [ValueError, IOError], tags: [], forbids: [].}
-
Writes the contents of array b into file f. The contents of b will be copied. Consider the ref overload to avoid copies.
This is an overload of write(), please refer to its documentation for more information.
Source Edit proc write(f: AsyncFile; b: string): int {....raises: [ValueError, IOError], tags: [], forbids: [].}
-
Writes the contents of array b into file f. The contents of b will be copied. Consider the ref overload to avoid copies.
This is an overload of write(), please refer to its documentation for more information.
Source Edit proc write(f: AsyncFile; buf: ptr UncheckedArray[byte]; bufLen: Natural): int {. ...raises: [ValueError, IOError], tags: [], forbids: [].}
-
Writes bufLen bytes from the buffer pointed to by buf to f.
buf might be nil only if bufLen is 0.
buf must stays alive for the duration of the read. Direct usage of this interface is discouraged due to its unsafetyness. Users are encouraged to use high-level overloads that keep buffers alive.
This function is not thread-safe.
Platform specific details
On Windows, for seekable files, the file position is implemented by the library and may overflow, though it is unlikely for that to happen due to most file system having a maximum file size of 2^64.
If you have to deal with file systems where the maximum file size exceeds that of conventional file systems, it is recommended to use File with threads for asynchronous operations.
- On Windows, most disk IOs are not asynchronous, see this article from Microsoft for more details. If asynchronous disk operations are required, it is recommended to use File with threads or carefully evaluate the limitations.
- On POSIX systems, disk IOs are never asynchronous. This is an unfortunate property of the specification. It is recommended to use File with threads for those use cases. This might change in the future.
- On POSIX systems, signals will not interrupt the operation.