An abstract handle to an input or output data resource,
such as a file or a socket.
You are responsible for managing the lifetime and validity
of `FileDescriptor` values,
in the same way as you manage a raw C file handle.
func closeAfter<R>(_ body: () throws -> R) throws -> R
Runs a closure and then closes the file descriptor, even if an error occurs.
- Parameter body: The closure to run.
If the closure throws an error,
this method closes the file descriptor before it rethrows that error.
- Returns: The value returned by the closure.
If `body` throws an error
or an error occurs while closing the file descriptor,
this method rethrows that error.
get · iOS 14.0+
standardError
TypeScript
get standardError(): FileDescriptor
Swift declaration
static var standardError: FileDescriptor { get }
The standard error file descriptor, with a numeric value of 2.
get · iOS 14.0+
standardInput
TypeScript
get standardInput(): FileDescriptor
Swift declaration
static var standardInput: FileDescriptor { get }
The standard input file descriptor, with a numeric value of 0.
get · iOS 14.0+
standardOutput
TypeScript
get standardOutput(): FileDescriptor
Swift declaration
static var standardOutput: FileDescriptor { get }
The standard output file descriptor, with a numeric value of 1.
Opens or creates a file for reading or writing.
- Parameters:
- path: The location of the file to open.
- mode: The read and write access to use.
- options: The behavior for opening the file.
- permissions: The file permissions to use for created files.
- retryOnInterrupt: Whether to retry the open operation
if it throws ``Errno/interrupted``.
The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: A file descriptor for the open file
The corresponding C function is `open`.
Opens or creates a file for reading or writing.
- Parameters:
- path: The location of the file to open.
- mode: The read and write access to use.
- options: The behavior for opening the file.
- permissions: The file permissions to use for created files.
- retryOnInterrupt: Whether to retry the open operation
if it throws ``Errno/interrupted``.
The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: A file descriptor for the open file
The corresponding C function is `open`.
Creates a unidirectional data channel, which can be used for interprocess communication.
- Parameters:
- options: The behavior for creating the pipe.
- Returns: The pair of file descriptors.
The corresponding C function is `pipe2`.
Creates a unidirectional data channel, which can be used for interprocess communication.
- Returns: The pair of file descriptors.
The corresponding C function is `pipe`.
method · iOS 14.0+
read
TypeScript
readFromAbsoluteOffsetIntoRetryOnInterrupt($self: FileDescriptor, offset: number, buffer: ArrayBuffer, retryOnInterrupt?: boolean): number
Swift declaration
func read(fromAbsoluteOffset offset: Int64, into buffer: UnsafeMutableRawBufferPointer, retryOnInterrupt: Bool = true) throws -> Int
Reads bytes at the specified offset into a buffer.
- Parameters:
- offset: The file offset where reading begins.
- buffer: The region of memory to read into.
- retryOnInterrupt: Whether to retry the read operation
if it throws ``Errno/interrupted``.
The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: The number of bytes that were read.
The <doc://com.apple.documentation/documentation/swift/unsafemutablerawbufferpointer/count-95usp> property of `buffer`
determines the maximum number of bytes that are read into that buffer.
Unlike <doc:FileDescriptor/read(into:retryOnInterrupt:)>,
this method leaves the file's existing offset unchanged.
The corresponding C function is `pread`.
method · iOS 14.0+
read
TypeScript
readIntoRetryOnInterrupt($self: FileDescriptor, buffer: ArrayBuffer, retryOnInterrupt?: boolean): number
Reads bytes at the current file offset into a buffer.
- Parameters:
- buffer: The region of memory to read into.
- retryOnInterrupt: Whether to retry the read operation
if it throws ``Errno/interrupted``.
The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: The number of bytes that were read.
The <doc://com.apple.documentation/documentation/swift/unsafemutablerawbufferpointer/count-95usp> property of `buffer`
determines the maximum number of bytes that are read into that buffer.
After reading,
this method increments the file's offset by the number of bytes read.
To change the file's offset,
call the ``seek(offset:from:)`` method.
The corresponding C function is `read`.
method · iOS 14.0+
seek
TypeScript
seek($self: FileDescriptor, offset: number, whence: FileDescriptor_SeekOrigin): number
Swift declaration
@discardableResult func seek(offset: Int64, from whence: FileDescriptor.SeekOrigin) throws -> Int64
Repositions the offset for the given file descriptor.
- Parameters:
- offset: The new offset for the file descriptor.
- whence: The origin of the new offset.
- Returns: The file's offset location,
in bytes from the beginning of the file.
The corresponding C function is `lseek`.
method · iOS 27.0+
stat
TypeScript
stat($self: FileDescriptor, retryOnInterrupt?: boolean): Stat
Swift declaration
func stat(retryOnInterrupt: Bool = true) throws(Errno) -> Stat
Creates a `Stat` struct for the file referenced by this `FileDescriptor`.
The corresponding C function is `fstat()`.
method · iOS 14.0+
close
TypeScript
close($self: FileDescriptor): void
Swift declaration
func close() throws
Deletes a file descriptor.
Deletes the file descriptor from the per-process object reference table.
If this is the last reference to the underlying object,
the object will be deactivated.
The corresponding C function is `close`.
method · iOS 14.0+
write
TypeScript
writeToAbsoluteOffsetRetryOnInterrupt($self: FileDescriptor, offset: number, buffer: ArrayBuffer, retryOnInterrupt?: boolean): number
Writes the contents of a buffer at the specified offset.
- Parameters:
- offset: The file offset where writing begins.
- buffer: The region of memory that contains the data being written.
- retryOnInterrupt: Whether to retry the write operation
if it throws ``Errno/interrupted``.
The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: The number of bytes that were written.
Unlike ``write(_:retryOnInterrupt:)``,
this method leaves the file's existing offset unchanged.
The corresponding C function is `pwrite`.
method · iOS 14.0+
write
TypeScript
writeRetryOnInterrupt($self: FileDescriptor, buffer: ArrayBuffer, retryOnInterrupt?: boolean): number
Writes the contents of a buffer at the current file offset.
- Parameters:
- buffer: The region of memory that contains the data being written.
- retryOnInterrupt: Whether to retry the write operation
if it throws ``Errno/interrupted``.
The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: The number of bytes that were written.
After writing,
this method increments the file's offset by the number of bytes written.
To change the file's offset,
call the ``seek(offset:from:)`` method.
The corresponding C function is `write`.
Truncates or extends the file referenced by this file descriptor.
- Parameters:
- newSize: The length in bytes to resize the file to.
- retryOnInterrupt: Whether to retry the write operation
if it throws ``Errno/interrupted``. The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
The file referenced by this file descriptor will by truncated (or extended) to `newSize`.
If the current size of the file exceeds `newSize`, any extra data is discarded. If the current
size of the file is smaller than `newSize`, the file is extended and filled with zeros to the
provided size.
This function requires that the file has been opened for writing.
- Note: This function does not modify the current offset for any open file descriptors
associated with the file.
The corresponding C function is `ftruncate`.
init · iOS 14.0+
init
TypeScript
init(rawValue: number): FileDescriptor
Swift declaration
init(rawValue: CInt)
Creates a strongly-typed file handle from a raw C file handle.
get · iOS 14.0+
rawValue
TypeScript
getRawValue($self: FileDescriptor): number
Swift declaration
let rawValue: CInt
The raw C file handle.
method · iOS 14.0+
writeAll
TypeScript
writeAllToAbsoluteOffset($self: FileDescriptor, offset: number, sequence: Array<number>): number
Swift declaration
@discardableResult func writeAll<S>(toAbsoluteOffset offset: Int64, _ sequence: S) throws -> Int where S : Sequence, S.Element == UInt8
Writes a sequence of bytes to the given offset.
- Parameters:
- offset: The file offset where writing begins.
- sequence: The bytes to write.
- Returns: The number of bytes written, equal to the number of elements in `sequence`.
This method either writes the entire contents of `sequence`,
or throws an error if only part of the content was written.
Unlike ``writeAll(_:)``,
this method preserves the file descriptor's existing offset.
If `sequence` doesn't implement
the <doc://com.apple.documentation/documentation/swift/sequence/3128824-withcontiguousstorageifavailable> method,
temporary space will be allocated as needed.
method · iOS 14.0+
writeAll
TypeScript
writeAll($self: FileDescriptor, sequence: Array<number>): number
Swift declaration
@discardableResult func writeAll<S>(_ sequence: S) throws -> Int where S : Sequence, S.Element == UInt8
Writes a sequence of bytes to the current offset
and then updates the offset.
- Parameter sequence: The bytes to write.
- Returns: The number of bytes written, equal to the number of elements in `sequence`.
This method either writes the entire contents of `sequence`,
or throws an error if only part of the content was written.
Writes to the position associated with this file descriptor, and
increments that position by the number of bytes written.
See also ``seek(offset:from:)``.
If `sequence` doesn't implement
the <doc://com.apple.documentation/documentation/swift/sequence/3128824-withcontiguousstorageifavailable> method,
temporary space will be allocated as needed.
Duplicates this file descriptor and returns the newly created copy.
- Parameters:
- `target`: The desired target file descriptor, or `nil`, in which case
the copy is assigned to the file descriptor with the lowest raw value
that is not currently in use by the process.
- retryOnInterrupt: Whether to retry the duplicate operation
if it throws ``Errno/interrupted``. The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: The new file descriptor.
If the `target` descriptor is already in use, then it is first
deallocated as if a close(2) call had been done first.
File descriptors are merely references to some underlying system resource.
The system does not distinguish between the original and the new file
descriptor in any way. For example, read, write and seek operations on
one of them also affect the logical file position in the other, and
append mode, non-blocking I/O and asynchronous I/O options are shared
between the references. If a separate pointer into the file is desired,
a different object reference to the file must be obtained by issuing an
additional call to `open`.
However, each file descriptor maintains its own close-on-exec flag.
The corresponding C functions are `dup` and `dup2`.
Duplicates this file descriptor and returns the newly created copy.
- Parameters:
- `target`: The desired target file descriptor.
- `options`: The behavior for creating the target file descriptor.
- retryOnInterrupt: Whether to retry the duplicate operation
if it throws ``Errno/interrupted``. The default is `true`.
Pass `false` to try only once and throw an error upon interruption.
- Returns: The new file descriptor.
If the `target` descriptor is already in use, then it is first
deallocated as if a close(2) call had been done first.
File descriptors are merely references to some underlying system resource.
The system does not distinguish between the original and the new file
descriptor in any way. For example, read, write and seek operations on
one of them also affect the logical file position in the other, and
append mode, non-blocking I/O and asynchronous I/O options are shared
between the references. If a separate pointer into the file is desired,
a different object reference to the file must be obtained by issuing an
additional call to `open`.
However, each file descriptor maintains its own close-on-exec flag.
The corresponding C function is `dup3`.
