NIOFileHandle

public final class NIOFileHandle : FileDescriptor

A NIOFileHandle is a handle to an open file.

When creating a NIOFileHandle it takes ownership of the underlying file descriptor. When a NIOFileHandle is no longer needed you must close it or take back ownership of the file descriptor using takeDescriptorOwnership.

Note

One underlying file descriptor should usually be managed by one NIOFileHandle only.

Warning

Failing to manage the lifetime of a NIOFileHandle correctly will result in undefined behaviour.

Warning

NIOFileHandle objects are not thread-safe and are mutable. They also cannot be fully thread-safe as they refer to a global underlying file descriptor.

  • Declaration

    Swift

    public private(set) var isOpen: Bool
  • Create a NIOFileHandle taking ownership of descriptor. You must call NIOFileHandle.close or NIOFileHandle.takeDescriptorOwnership before this object can be safely released.

    Declaration

    Swift

    public init(descriptor: CInt)
  • Duplicates this NIOFileHandle. This means that a new NIOFileHandle object with a new underlying file descriptor is returned. The caller takes ownership of the returned NIOFileHandle and is responsible for closing it.

    Warning

    The returned NIOFileHandle is not fully independent, the seek pointer is shared as documented by dup(2).

    Declaration

    Swift

    public func duplicate() throws -> NIOFileHandle

    Return Value

    A new NIOFileHandle with a fresh underlying file descriptor but shared seek pointer.

  • Take the ownership of the underlying file descriptor. This is similar to close() but the underlying file descriptor remains open. The caller is responsible for closing the file descriptor by some other means.

    After calling this, the NIOFileHandle cannot be used for anything else and all the operations will throw.

    Declaration

    Swift

    public func takeDescriptorOwnership() throws -> CInt

    Return Value

    The underlying file descriptor, now owned by the caller.

  • Declaration

    Swift

    public func close() throws
  • Declaration

    Swift

    public func withUnsafeFileDescriptor<T>(_ body: (CInt) throws -> T) throws -> T
  • Mode represents file access modes.

    See more

    Declaration

    Swift

    public struct Mode : OptionSet
  • Flags allows to specify additional flags to Mode, such as permission for file creation.

    See more

    Declaration

    Swift

    public struct Flags
  • Open a new NIOFileHandle.

    Declaration

    Swift

    public convenience init(path: String, mode: Mode = .read, flags: Flags = .default) throws

    Parameters

    path

    The path of the file to open. The ownership of the file descriptor is transferred to this NIOFileHandle and so it will be closed once close is called.

    mode

    Access mode. Default mode is .read.

    flags

    Additional POSIX flags.

  • Open a new NIOFileHandle.

    Declaration

    Swift

    public convenience init(path: String) throws

    Parameters

    path

    The path of the file to open. The ownership of the file descriptor is transferred to this NIOFileHandle and so it will be closed once close is called.