1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// 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.
public final class NIOFileHandle: FileDescriptor {
public private(set) var isOpen: Bool
private let descriptor: CInt
/// Create a `NIOFileHandle` taking ownership of `descriptor`. You must call `NIOFileHandle.close` or `NIOFileHandle.takeDescriptorOwnership` before
/// this object can be safely released.
public init(descriptor: CInt) {
self.descriptor = descriptor
self.isOpen = true
}
deinit {
assert(!self.isOpen, "leaked open NIOFileHandle(descriptor: \(self.descriptor)). Call `close()` to close or `takeDescriptorOwnership()` to take ownership and close by some other means.")
}
/// 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)`.
///
/// - returns: A new `NIOFileHandle` with a fresh underlying file descriptor but shared seek pointer.
public func duplicate() throws -> NIOFileHandle {
return try withUnsafeFileDescriptor { fd in
NIOFileHandle(descriptor: try Posix.dup(descriptor: fd))
}
}
/// 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.
///
/// - returns: The underlying file descriptor, now owned by the caller.
public func takeDescriptorOwnership() throws -> CInt {
guard self.isOpen else {
throw IOError(errnoCode: EBADF, reason: "can't close file (as it's not open anymore).")
}
self.isOpen = false
return self.descriptor
}
public func close() throws {
try withUnsafeFileDescriptor { fd in
try Posix.close(descriptor: fd)
}
self.isOpen = false
}
public func withUnsafeFileDescriptor<T>(_ body: (CInt) throws -> T) throws -> T {
guard self.isOpen else {
throw IOError(errnoCode: EBADF, reason: "file descriptor already closed!")
}
return try body(self.descriptor)
}
}
extension NIOFileHandle {
/// `Mode` represents file access modes.
public struct Mode: OptionSet {
public let rawValue: UInt8
public init(rawValue: UInt8) {
self.rawValue = rawValue
}
internal var posixFlags: CInt {
switch self {
case [.read, .write]:
return O_RDWR
case .read:
return O_RDONLY
case .write:
return O_WRONLY
default:
preconditionFailure("Unsupported mode value")
}
}
/// Opens file for reading
public static let read = Mode(rawValue: 1 << 0)
/// Opens file for writing
public static let write = Mode(rawValue: 1 << 1)
}
/// `Flags` allows to specify additional flags to `Mode`, such as permission for file creation.
public struct Flags {
internal var posixMode: mode_t
internal var posixFlags: CInt
public static let `default` = Flags(posixMode: 0, posixFlags: 0)
/// Allows file creation when opening file for writing. File owner is set to the effective user ID of the process.
///
/// - parameters:
/// - posixMode: `file mode` applied when file is created. Default permissions are: read and write for fileowner, read for owners group and others.
public static func allowFileCreation(posixMode: mode_t = S_IWUSR | S_IRUSR | S_IRGRP | S_IROTH) -> Flags {
return Flags(posixMode: posixMode, posixFlags: O_CREAT)
}
/// Allows the specification of POSIX flags (e.g. `O_TRUNC`) and mode (e.g. `S_IWUSR`)
///
/// - parameters:
/// - flags: The POSIX open flags (the second parameter for `open(2)`).
/// - mode: The POSIX mode (the third parameter for `open(2)`).
/// - returns: A `NIOFileHandle.Mode` equivalent to the given POSIX flags and mode.
public static func posix(flags: CInt, mode: mode_t) -> Flags {
return Flags(posixMode: mode, posixFlags: flags)
}
}
/// Open a new `NIOFileHandle`. This operation is blocking.
///
/// - 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.
public convenience init(path: String, mode: Mode = .read, flags: Flags = .default) throws {
let fd = try Posix.open(file: path, oFlag: mode.posixFlags | O_CLOEXEC | flags.posixFlags, mode: flags.posixMode)
self.init(descriptor: fd)
}
/// Open a new `NIOFileHandle`. This operation is blocking.
///
/// - 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.
public convenience init(path: String) throws {
// This function is here because we had a function like this in NIO 2.0, and the one above doesn't quite match. Sadly we can't
// really deprecate this either, because it'll be preferred to the one above in many cases.
try self.init(path: path, mode: .read, flags: .default)
}
}
extension NIOFileHandle: CustomStringConvertible {
public var description: String {
return "FileHandle { descriptor: \(self.descriptor) }"
}
}
|
