Class

NSFile​Handle

The NSFile​Handle 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 NSFile​Handle 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​With​File​Descriptor:​ method or use the init​With​File​Descriptor:​close​On​Dealloc:​ 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

+ file​Handle​For​Reading​At​Path:​​

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

+ file​Handle​For​Reading​From​URL:​​error:​​

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

+ file​Handle​For​Writing​At​Path:​​

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

+ file​Handle​For​Writing​To​URL:​​error:​​

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

+ file​Handle​For​Updating​At​Path:​​

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

+ file​Handle​For​Updating​URL:​​error:​​

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

file​Handle​With​Standard​Error

Returns the file handle associated with the standard error file.

file​Handle​With​Standard​Input

Returns the file handle associated with the standard input file.

file​Handle​With​Standard​Output

Returns the file handle associated with the standard output file.

file​Handle​With​Null​Device

Returns a file handle associated with a null device.

Creating a File Handle

- init​With​File​Descriptor:​​

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

- init​With​File​Descriptor:​​close​On​Dealloc:​​

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

Getting a File Descriptor

file​Descriptor

The POSIX file descriptor associated with the receiver.

Reading from a File Handle

available​Data

The data currently available in the receiver.

- read​Data​To​End​Of​File

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

- read​Data​Of​Length:​​

Synchronously reads data up to the specified number of bytes.

Writing to a File Handle

- write​Data:​​

Synchronously writes the specified data to the receiver.

Reading and Writing Using Blocks

readability​Handler

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

writeability​Handler

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

Communicating Asynchronously

- accept​Connection​In​Background​And​Notify

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.

- accept​Connection​In​Background​And​Notify​For​Modes:​​

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.

- read​In​Background​And​Notify

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

- read​In​Background​And​Notify​For​Modes:​​

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

- read​To​End​Of​File​In​Background​And​Notify

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

- read​To​End​Of​File​In​Background​And​Notify​For​Modes:​​

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

- wait​For​Data​In​Background​And​Notify

Asynchronously checks to see if data is available.

- wait​For​Data​In​Background​And​Notify​For​Modes:​​

Asynchronously checks to see if data is available.

Seeking Within a File

offset​In​File

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

- seek​To​End​Of​File

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

- seek​To​File​Offset:​​

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

Operating on a File

- close​File

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

- synchronize​File

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

- truncate​File​At​Offset:​​

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 User​Info 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

NSFile​Handle 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.

NSFile​Handle​Connection​Accepted​Notification

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

NSFile​Handle​Data​Available​Notification

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

NSFile​Handle​Read​Completion​Notification

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

NSFile​Handle​Read​To​End​Of​File​Completion​Notification

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.

Relationships

Inherits From