Class

NSFileHandle

The NSFileHandle class is an object-oriented wrapper for a file descriptor. 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.

Overview

Most creation methods for NSFileHandle 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 initWithFileDescriptor: method or use the initWithFileDescriptor:closeOnDealloc: method and pass NO 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.

Symbols

Getting a File Handle

+ fileHandleForReadingAtPath:

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

+ fileHandleForReadingFromURL:error:

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

+ fileHandleForWritingAtPath:

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

+ fileHandleForWritingToURL:error:

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

+ fileHandleForUpdatingAtPath:

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

+ fileHandleForUpdatingURL:error:

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

Creating a File Handle

- initWithFileDescriptor:

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

- initWithFileDescriptor:closeOnDealloc:

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

Getting a File Descriptor

fileDescriptor

The POSIX file descriptor associated with the receiver.

Reading from a File Handle

availableData

The data currently available in the receiver.

- readDataToEndOfFile

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

- readDataOfLength:

Synchronously reads data up to the specified number of bytes.

Writing to a File Handle

- writeData:

Synchronously writes the specified data to the receiver.

Reading and Writing Using Blocks

readabilityHandler

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

writeabilityHandler

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

Communicating Asynchronously

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

- acceptConnectionInBackgroundAndNotifyForModes:

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

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

- readInBackgroundAndNotifyForModes:

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

- readToEndOfFileInBackgroundAndNotify

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

- readToEndOfFileInBackgroundAndNotifyForModes:

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

- waitForDataInBackgroundAndNotify

Asynchronously checks to see if data is available.

- waitForDataInBackgroundAndNotifyForModes:

Asynchronously checks to see if data is available.

Seeking Within a File

offsetInFile

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

- seekToEndOfFile

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

- seekToFileOffset:

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

Operating on a File

- closeFile

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

- synchronizeFile

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

- truncateFileAtOffset:

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.

Unused Constant

Constant that is currently unused.

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.

NSFileHandleConnectionAcceptedNotification

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.

NSFileHandleDataAvailableNotification

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

NSFileHandleReadCompletionNotification

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

NSFileHandleReadToEndOfFileCompletionNotification

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.

Initializers

Relationships

Inherits From

Conforms To