<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/FileHandle",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSFileHandle"
  },
  "title" : "FileHandle"
}
-->

# FileHandle

An object-oriented wrapper for a file descriptor.

```
class FileHandle
```

## Overview

You use file handle objects to access data associated with files, sockets, pipes, and devices. For files, you can read, write, and seek within the file. For sockets, pipes, and devices, you can use a file handle object to monitor the device and process data asynchronously.

Most creation methods for [`FileHandle`](/documentation/Foundation/FileHandle) cause the file handle object to take ownership of the associated file descriptor. This means that the file handle object both creates the file descriptor and is responsible for closing it later, usually when the system deallocates the file handle object. If you want to use a file handle object with a file descriptor that you created, use the [`init(fileDescriptor:)`](/documentation/Foundation/FileHandle/init(fileDescriptor:)) method or use the [`init(fileDescriptor:closeOnDealloc:)`](/documentation/Foundation/FileHandle/init(fileDescriptor:closeOnDealloc:)) method and pass <doc://com.apple.documentation/documentation/Swift/false> for the `flag` parameter.

### Run Loop Considerations

When using a file handle object to communicate asynchronously with a socket, you must initiate the corresponding operations from a thread with an active run loop. Although the read, accept, and wait operations themselves are performed asynchronously on background threads, the file handle uses a run loop source to monitor the operations and notify your code appropriately. Therefore, you must call those methods from your application’s main thread or from any thread where you’ve configured a run loop and are using it to process events.

## Topics

### Creating a File Handle

[`init(fileDescriptor:)`](/documentation/Foundation/FileHandle/init(fileDescriptor:))

Creates and returns a file handle object associated with the specified file descriptor.

[`init(fileDescriptor:closeOnDealloc:)`](/documentation/Foundation/FileHandle/init(fileDescriptor:closeOnDealloc:))

Creates and returns a file handle object associated with the specified file descriptor and deallocation policy.

[`init(forReadingAtPath:)`](/documentation/Foundation/FileHandle/init(forReadingAtPath:))

Returns a file handle initialized for reading the file, device, or named socket at the specified path.

[`init(forReadingFromURL:)`](/documentation/Foundation/FileHandle/init(forReadingFromURL:))

Returns a file handle initialized for reading the file, device, or named socket at the specified URL.

[`init(forWritingAtPath:)`](/documentation/Foundation/FileHandle/init(forWritingAtPath:))

Returns a file handle initialized for writing to the file, device, or named socket at the specified path.

[`init(forWritingToURL:)`](/documentation/Foundation/FileHandle/init(forWritingToURL:))

Returns a file handle initialized for writing to the file, device, or named socket at the specified URL.

[`init(forUpdatingAtPath:)`](/documentation/Foundation/FileHandle/init(forUpdatingAtPath:))

Returns a file handle initialized for reading and writing to the file, device, or named socket at the specified path.

[`init(forUpdatingURL:)`](/documentation/Foundation/FileHandle/init(forUpdatingURL:))

Returns a file handle initialized for reading and writing to the file, device, or named socket at the specified URL.

[`init(coder:)`](/documentation/Foundation/FileHandle/init(coder:))

Returns a file handle initialized from data in an unarchiver.

### Getting a File Handle

[`standardError`](/documentation/Foundation/FileHandle/standardError)

The file handle associated with the standard error file.

[`standardInput`](/documentation/Foundation/FileHandle/standardInput)

The file handle associated with the standard input file.

[`standardOutput`](/documentation/Foundation/FileHandle/standardOutput)

The file handle associated with the standard output file.

[`nullDevice`](/documentation/Foundation/FileHandle/nullDevice)

The file handle associated with a null device.

### Getting a File Descriptor

[`fileDescriptor`](/documentation/Foundation/FileHandle/fileDescriptor)

The POSIX file descriptor associated with the receiver.

### Reading from a File Handle Asynchronously

[`bytes`](/documentation/Foundation/FileHandle/bytes)

The file’s contents, as an asynchronous sequence of bytes.

[`FileHandle.AsyncBytes`](/documentation/Foundation/FileHandle/AsyncBytes)

An asynchronous sequence of bytes.

### Reading from a File Handle Synchronously

[`availableData`](/documentation/Foundation/FileHandle/availableData)

The data currently available in the receiver.

[`readToEnd()`](/documentation/Foundation/FileHandle/readToEnd())

Reads the available data synchronously up to the end of file or maximum number of bytes.

[`read(upToCount:)`](/documentation/Foundation/FileHandle/read(upToCount:))

Reads data synchronously up to the specified number of bytes.

[`readDataToEndOfFileAndReturnError:`](/documentation/Foundation/NSFileHandle/readDataToEndOfFileAndReturnError:)

Reads the available data synchronously up to the end of file or maximum number of bytes.

[`readDataUpToLength:error:`](/documentation/Foundation/NSFileHandle/readDataUpToLength:error:)

Reads data synchronously up to the specified number of bytes.

### Reading Asynchronously with Notifications

[`acceptConnectionInBackgroundAndNotify()`](/documentation/Foundation/FileHandle/acceptConnectionInBackgroundAndNotify())

Accepts a socket connection (for stream-type sockets only) in the background and creates a file handle for the “near” (client) end of the communications channel.

[`acceptConnectionInBackgroundAndNotify(forModes:)`](/documentation/Foundation/FileHandle/acceptConnectionInBackgroundAndNotify(forModes:))

Accepts a socket connection (for stream-type sockets only) in the background and creates a file handle for the “near” (client) end of the communications channel.

[`readInBackgroundAndNotify()`](/documentation/Foundation/FileHandle/readInBackgroundAndNotify())

Reads from the file or communications channel in the background and posts a notification when finished.

[`readInBackgroundAndNotify(forModes:)`](/documentation/Foundation/FileHandle/readInBackgroundAndNotify(forModes:))

Reads from the file or communications channel in the background and posts a notification when finished.

[`readToEndOfFileInBackgroundAndNotify()`](/documentation/Foundation/FileHandle/readToEndOfFileInBackgroundAndNotify())

Reads to the end of file from the file or communications channel in the background and posts a notification when finished.

[`readToEndOfFileInBackgroundAndNotify(forModes:)`](/documentation/Foundation/FileHandle/readToEndOfFileInBackgroundAndNotify(forModes:))

Reads to the end of file from the file or communications channel in the background and posts a notification when finished.

[`waitForDataInBackgroundAndNotify()`](/documentation/Foundation/FileHandle/waitForDataInBackgroundAndNotify())

Asynchronously checks to see if data is available.

[`waitForDataInBackgroundAndNotify(forModes:)`](/documentation/Foundation/FileHandle/waitForDataInBackgroundAndNotify(forModes:))

Asynchronously checks to see if data is available.

### Writing to a File Handle

[`write(contentsOf:)`](/documentation/Foundation/FileHandle/write(contentsOf:))

Writes the specified data synchronously to the file handle.

[`writeData:error:`](/documentation/Foundation/NSFileHandle/writeData:error:)

Writes the specified data synchronously to the file handle.

### Seeking Within a File

[`offset()`](/documentation/Foundation/FileHandle/offset())

Gets the position of the file pointer within the file.

[`seekToEnd()`](/documentation/Foundation/FileHandle/seekToEnd())

Places the file pointer at the end of the file referenced by the file handle and returns the new file offset.

[`getOffset:error:`](/documentation/Foundation/NSFileHandle/getOffset:error:)

Get the current position of the file pointer within the file.

[`seekToEndReturningOffset:error:`](/documentation/Foundation/NSFileHandle/seekToEndReturningOffset:error:)

Places the file pointer at the end of the file referenced by the file handle and returns the new file offset.

[`seek(toOffset:)`](/documentation/Foundation/FileHandle/seek(toOffset:))

Moves the file pointer to the specified offset within the file.

### Operating on a File

[`close()`](/documentation/Foundation/FileHandle/close())

Disallows further access to the represented file or communications channel and signals end of file on communications channels that permit writing.

[`synchronize()`](/documentation/Foundation/FileHandle/synchronize())

Causes all in-memory data and attributes of the file represented by the file handle to write to permanent storage.

[`truncate(atOffset:)`](/documentation/Foundation/FileHandle/truncate(atOffset:))

Truncates or extends the file represented by the file handle to a specified offset within the file and puts the file pointer at that position.

### Monitoring for Readability and Writability

Set these properties if you want to use a block that reads or writes based on the file handle’s availability.

[`readabilityHandler`](/documentation/Foundation/FileHandle/readabilityHandler)

The block to use for reading the contents of the file handle asynchronously.

[`writeabilityHandler`](/documentation/Foundation/FileHandle/writeabilityHandler)

The block to use for writing the contents of the file handle asynchronously.

### Constants

[Keys for Notification UserInfo Dictionary](/documentation/Foundation/keys-for-notification-userinfo-dictionary)

Strings that the system uses as keys in a userinfo dictionary during a file handle notification.

[Exception Names](/documentation/Foundation/exception-names)

Constant that defines the name of a file operation exception.

### Notifications

`NSFileHandle` posts several notifications related to asynchronous background I/O operations. They are set to post when the run loop of the thread that started the asynchronous operation is idle.

[`NSFileHandleConnectionAccepted`](/documentation/Foundation/NSNotification/Name-swift.struct/NSFileHandleConnectionAccepted)

Posted when a file handle object establishes a socket connection between two processes, creates a file handle object for one end of the connection, and makes this object available to observers.

[`NSFileHandleDataAvailable`](/documentation/Foundation/NSNotification/Name-swift.struct/NSFileHandleDataAvailable)

Posted when the file handle determines that data is currently available for reading in a file or at a communications channel.

[`readCompletionNotification`](/documentation/Foundation/FileHandle/readCompletionNotification)

Posted when the file handle reads the data currently available in a file or at a communications channel.

[`NSFileHandleReadToEndOfFileCompletion`](/documentation/Foundation/NSNotification/Name-swift.struct/NSFileHandleReadToEndOfFileCompletion)

Posted when the file handle reads all data in the file or, in a communications channel, until the other process signals the end of data.

### Deprecated

[`readDataToEndOfFile()`](/documentation/Foundation/FileHandle/readDataToEndOfFile())

Reads the available data synchronously up to the end of file or maximum number of bytes.

[`readData(ofLength:)`](/documentation/Foundation/FileHandle/readData(ofLength:))

Reads data synchronously up to the specified number of bytes.

[`write(_:)`](/documentation/Foundation/FileHandle/write(_:))

Writes the specified data synchronously to the file handle.

[`offsetInFile`](/documentation/Foundation/FileHandle/offsetInFile)

The position of the file pointer within the file represented by the file handle.

[`seekToEndOfFile()`](/documentation/Foundation/FileHandle/seekToEndOfFile())

Places the file pointer at the end of the file referenced by the file handle and returns the new file offset.

[`seek(toFileOffset:)`](/documentation/Foundation/FileHandle/seek(toFileOffset:))

Moves the file pointer to the specified offset within the file represented by the receiver.

[`closeFile()`](/documentation/Foundation/FileHandle/closeFile())

Disallows further access to the represented file or communications channel and signals end of file on communications channels that permit writing.

[`synchronizeFile()`](/documentation/Foundation/FileHandle/synchronizeFile())

Causes all in-memory data and attributes of the file represented by the handle to write to permanent storage.

[`truncateFile(atOffset:)`](/documentation/Foundation/FileHandle/truncateFile(atOffset:))

Truncates or extends the file represented by the file handle to a specified offset within the file and puts the file pointer at that position.

[`NSFileHandleNotificationMonitorModes`](/documentation/Foundation/NSFileHandleNotificationMonitorModes)

Currently unused.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)