Class

FileHandle

An object-oriented wrapper for a file descriptor.

Declaration

class FileHandle : NSObject

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 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 file handle object itself is deallocated. If you want to use a file handle object with a file descriptor that you created, use the init(fileDescriptor:) method or use the init(fileDescriptor:closeOnDealloc:) method and pass 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 have configured a run loop and are using it to process events.

For more information about configuring and using run loops, see Threading Programming Guide.

Topics

Getting a File Handle

init?(forReadingAtPath: String)

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

init(forReadingFrom: URL)

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

init?(forWritingAtPath: String)

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

init(forWritingTo: URL)

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

init?(forUpdatingAtPath: String)

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

init(forUpdating: URL)

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

class var standardError: FileHandle

Returns the file handle associated with the standard error file.

class var standardInput: FileHandle

Returns the file handle associated with the standard input file.

class var standardOutput: FileHandle

Returns the file handle associated with the standard output file.

class var nullDevice: FileHandle

Returns a file handle associated with a null device.

Creating a File Handle

init(fileDescriptor: Int32)

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

init(fileDescriptor: Int32, closeOnDealloc: Bool)

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

Getting a File Descriptor

var fileDescriptor: Int32

The POSIX file descriptor associated with the receiver.

Reading from a File Handle

var availableData: Data

The data currently available in the receiver.

func readDataToEndOfFile() -> Data

Synchronously reads the available data up to the end of file or maximum number of bytes.

func readData(ofLength: Int) -> Data

Synchronously reads data up to the specified number of bytes.

Writing to a File Handle

func write(Data)

Synchronously writes the specified data to the receiver.

Reading and Writing Using Blocks

var readabilityHandler: ((FileHandle) -> Void)?

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

var writeabilityHandler: ((FileHandle) -> Void)?

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

Communicating Asynchronously

func 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.

func acceptConnectionInBackgroundAndNotify(forModes: [RunLoop.Mode]?)

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.

func readInBackgroundAndNotify()

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

func readInBackgroundAndNotify(forModes: [RunLoop.Mode]?)

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

func readToEndOfFileInBackgroundAndNotify()

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

func readToEndOfFileInBackgroundAndNotify(forModes: [RunLoop.Mode]?)

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

func waitForDataInBackgroundAndNotify()

Asynchronously checks to see if data is available.

func waitForDataInBackgroundAndNotify(forModes: [RunLoop.Mode]?)

Asynchronously checks to see if data is available.

Seeking Within a File

var offsetInFile: UInt64

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

func seekToEndOfFile() -> UInt64

Puts the file pointer at the end of the file referenced by the receiver and returns the new file offset.

func seek(toFileOffset: UInt64)

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

Operating on a File

func closeFile()

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

func synchronizeFile()

Causes all in-memory data and attributes of the file represented by the receiver to be written to permanent storage.

func truncateFile(atOffset: UInt64)

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

Constants

Keys for Notification UserInfo Dictionary

Strings that are used as keys in a userinfo dictionary in a file handle notification.

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.

static let NSFileHandleConnectionAccepted: NSNotification.Name

This notification is posted when an NSFileHandle object establishes a socket connection between two processes, creates an NSFileHandle object for one end of the connection, and makes this object available to observers by putting it in the userInfo dictionary.

static let NSFileHandleDataAvailable: NSNotification.Name

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

class let readCompletionNotification: NSNotification.Name

This notification is posted when the file handle reads the data currently available in a file or at a communications channel.

static let NSFileHandleReadToEndOfFileCompletion: NSNotification.Name

This notification is posted when the file handle reads all data in the file or, if a communications channel, until the other process signals the end of data.