NSFileHandle Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Low-Level File Management Programming Topics
Declared in
NSFileHandle.h
Related sample code

Overview

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.

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.

Tasks

Getting a File Handle

Creating a File Handle

Getting a File Descriptor

Reading from a File Handle

Writing to a File Handle

Reading and Writing Using Blocks

Communicating Asynchronously

Seeking Within a File

Operating on a File

Properties

readabilityHandler

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

@property (copy) void (^readabilityHandler)(NSFileHandle *);
Discussion

The default value of this property is nil. Assigning a valid block object to this property creates a dispatch source for reading the contents of the file or socket. Your block is submitted to the file handle’s dispatch queue when there is data to read. When reading a file, your handler block is typically executed repeatedly until the entire contents of the file have been read. When reading data from a socket, your handler block is executed whenever there is data on the socket waiting to be read.

The block you provide must accept a single parameter that is the current file handle. The return type of your block should be void.

To stop reading the file or socket, set the value of this property to nil. Doing so cancels the dispatch source and cleans up the file handle’s structures appropriately.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSFileHandle.h

writeabilityHandler

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

@property (copy) void (^writeabilityHandler)(NSFileHandle *);
Discussion

The default value of this property is nil. Assigning a valid block object to this property creates a dispatch source for writing the contents of the file or socket. Your block is submitted to the file handle’s dispatch queue when there is room available to write more data. When writing a file, your handler block is typically executed repeatedly until the entire contents of the file have been written. When writing data to a socket, your handler block is executed whenever the socket is ready to accept more data.

The block you provide must accept a single parameter that is the current file handle. The return type of your block should be void.

To stop writing data to the file or socket, set the value of this property to nil. Doing so cancels the dispatch source and cleans up the file handle’s structures appropriately.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSFileHandle.h

Class Methods

fileHandleForReadingAtPath:

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

+ (id)fileHandleForReadingAtPath:(NSString *)path
Parameters
path

The path to the file, device, or named socket to access.

Return Value

The initialized file handle object or nil if no file exists at path.

Discussion

The file pointer is set to the beginning of the file. You cannot write data to the returned file handle object. Use the readDataToEndOfFile or readDataOfLength: methods to read data from it.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

fileHandleForReadingFromURL:error:

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

+ (id)fileHandleForReadingFromURL:(NSURL *)url error:(NSError **)error
Parameters
url

The URL of the file, device, or named socket to access.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Return Value

The initialized file handle object or nil if no file exists at url.

Discussion

The file pointer is set to the beginning of the file. You cannot write data to the returned file handle object. Use the readDataToEndOfFile or readDataOfLength: methods to read data from it.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSFileHandle.h

fileHandleForUpdatingAtPath:

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

+ (id)fileHandleForUpdatingAtPath:(NSString *)path
Parameters
path

The path to the file, device, or named socket to access.

Return Value

The initialized file handle object or nil if no file exists at path.

Discussion

The file pointer is set to the beginning of the file. The returned object responds to both read... messages and writeData:.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

fileHandleForUpdatingURL:error:

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

+ (id)fileHandleForUpdatingURL:(NSURL *)url error:(NSError **)error
Parameters
url

The URL of the file, device, or named socket to access.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Return Value

The initialized file handle object or nil if no file exists at url.

Discussion

The file pointer is set to the beginning of the file. The returned object responds to both NSFileHandleread... messages and writeData:.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSFileHandle.h

fileHandleForWritingAtPath:

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

+ (id)fileHandleForWritingAtPath:(NSString *)path
Parameters
path

The path to the file, device, or named socket to access.

Return Value

The initialized file handle object or nil if no file exists at path.

Discussion

The file pointer is set to the beginning of the file. You cannot read data from the returned file handle object. Use the writeData: method to write data to the file handle.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

fileHandleForWritingToURL:error:

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

+ (id)fileHandleForWritingToURL:(NSURL *)url error:(NSError **)error
Parameters
url

The URL of the file, device, or named socket to access.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Return Value

The initialized file handle object or nil if no file exists at url.

Discussion

The file pointer is set to the beginning of the file. The returned object responds only to writeData:.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSFileHandle.h

fileHandleWithNullDevice

Returns a file handle associated with a null device.

+ (id)fileHandleWithNullDevice
Return Value

A file handle associated with a null device.

Discussion

You can use null-device file handles as “placeholders” for standard-device file handles or in collection objects to avoid exceptions and other errors resulting from messages being sent to invalid file handles. Read messages sent to a null-device file handle return an end-of-file indicator (an empty NSData object) rather than raise an exception. Write messages are no-ops, whereas fileDescriptor returns an illegal value. Other methods are no-ops or return “sensible” values.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

fileHandleWithStandardError

Returns the file handle associated with the standard error file.

+ (id)fileHandleWithStandardError
Return Value

The shared file handle associated with the standard error file.

Discussion

Conventionally this is a terminal device to which error messages are sent. There is one standard error file handle per process; it is a shared instance.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

fileHandleWithStandardInput

Returns the file handle associated with the standard input file.

+ (id)fileHandleWithStandardInput
Return Value

The shared file handle associated with the standard input file.

Discussion

Conventionally this is a terminal device on which the user enters a stream of data. There is one standard input file handle per process; it is a shared instance.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

fileHandleWithStandardOutput

Returns the file handle associated with the standard output file.

+ (id)fileHandleWithStandardOutput
Return Value

The shared file handle associated with the standard output file.

Discussion

Conventionally this is a terminal device that receives a stream of data from a program. There is one standard output file handle per process; it is a shared instance.

When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

Instance Methods

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.

- (void)acceptConnectionInBackgroundAndNotify
Discussion

This method asynchronously creates a file handle for the other end of the socket connection and returns that object by posting a NSFileHandleConnectionAcceptedNotification notification in the current thread. The notification includes a userInfo dictionary with the created NSFileHandle object, which is accessible using the NSFileHandleNotificationFileHandleItem key.

You must call this method from a thread that has an active run loop.

Special Considerations

The receiver must be created by an initWithFileDescriptor: message that takes as an argument a stream-type socket created by the appropriate system routine, and that is being listened on. In other words, you must bind() the socket, and ensure that the socket has a connection backlog defined by listen().

The object that will write data to the returned file handle must add itself as an observer of NSFileHandleConnectionAcceptedNotification.

Note that this method does not continue to listen for connection requests after it posts NSFileHandleConnectionAcceptedNotification. If you want to keep getting notified, you need to call acceptConnectionInBackgroundAndNotify again in your observer method.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

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.

- (void)acceptConnectionInBackgroundAndNotifyForModes:(NSArray *)modes
Parameters
modes

The runloop modes in which the connection accepted notification can be posted.

Discussion

See acceptConnectionInBackgroundAndNotify for details of how this method operates. This method differs from acceptConnectionInBackgroundAndNotify in that modes specifies the run-loop mode (or modes) in which NSFileHandleConnectionAcceptedNotification can be posted.

You must call this method from a thread that has an active run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

availableData

Returns the data currently available in the receiver.

- (NSData *)availableData
Return Value

The data currently available through the receiver, up to the the maximum size that can be represented by an NSData object.

Discussion

If the receiver is a file, this method returns the data obtained by reading the file from the current file pointer to the end of the file. If the receiver is a communications channel, this method reads up to a buffer of data and returns it; if no data is available, the method blocks. Returns an empty data object if the end of file is reached. This method raises NSFileHandleOperationException if attempts to determine the file-handle type fail or if attempts to read from the file or channel fail.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSFileHandle.h

closeFile

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

- (void)closeFile
Discussion

If the file handle object owns its file descriptor, it automatically closes that descriptor when it is deallocated. If you initialized the file handle object using the initWithFileDescriptor: method, or you initialized it using the initWithFileDescriptor:closeOnDealloc: and passed NO for the flag parameter, you can use this method to close the file descriptor; otherwise, you must close the file descriptor yourself.

After calling this method, you may still use the file handle object but must not attempt to read or write data or use the object to operate on the file descriptor. Attempts to read or write a closed file descriptor raise an exception.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSFileHandle.h

fileDescriptor

Returns the file descriptor associated with the receiver.

- (int)fileDescriptor
Return Value

The POSIX file descriptor associated with the receiver.

Discussion

You can use this method to retrieve the file descriptor while it is open. If the file handle object owns the file descriptor, you must not close it yourself. However, you can use the closeFile method to close the file descriptor programmatically. If you do call the closeFile method, subsequent calls to this method raise an exception.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

initWithFileDescriptor:

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

- (id)initWithFileDescriptor:(int)fileDescriptor
Parameters
fileDescriptor

The POSIX file descriptor with which to initialize the file handle. This descriptor represents an open file or socket that you created previously. For example, when creating a file handle for a socket, you would pass the value returned by the socket function.

Return Value

A file handle initialized with fileDescriptor.

Discussion

The file descriptor you pass in to this method is not owned by the file handle object. Therefore, you are responsible for closing the file descriptor at some point after disposing of the file handle object.

You can create a file handle for a socket by using the result of a socket call as fileDescriptor.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

initWithFileDescriptor:closeOnDealloc:

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

- (id)initWithFileDescriptor:(int)fileDescriptor closeOnDealloc:(BOOL)flag
Parameters
fileDescriptor

The POSIX file descriptor with which to initialize the file handle.

flag

YES if the returned file handle object should take ownership of the file descriptor and close it for you or NO if you want to maintain ownership of the file descriptor.

Return Value

An initialized file handle object.

Special Considerations

If flag is NO, the file descriptor you pass in to this method is not owned by the file handle object. In such a case, you are responsible for closing the file descriptor at some point after disposing of the file handle object. If you want the file handle object to close the descriptor for you automatically, pass YES for the flag parameter.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

offsetInFile

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

- (unsigned long long)offsetInFile
Return Value

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

Special Considerations

Raises an exception if the message is sent to a file handle representing a pipe or socket or if the file descriptor is closed.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

readDataOfLength:

Synchronously reads data up to the specified number of bytes.

- (NSData *)readDataOfLength:(NSUInteger)length
Parameters
length

The number of bytes to read from the receiver.

Return Value

The data available through the receiver up to a maximum of length bytes, or the maximum size that can be represented by an NSData object, whichever is the smaller.

Discussion

If the receiver is a file, this method returns the data obtained by reading length bytes starting at the current file pointer. If length bytes are not available, this method returns the data from the current file pointer to the end of the file. If the receiver is a communications channel, the method reads up to length bytes from the channel. Returns an empty NSData object if the file is positioned at the end of the file or if an end-of-file indicator is returned on a communications channel. This method raises NSFileHandleOperationException if attempts to determine the file-handle type fail or if attempts to read from the file or channel fail.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

readDataToEndOfFile

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

- (NSData *)readDataToEndOfFile
Return Value

The data available through the receiver up to maximum size that can be represented by an NSData object or, if a communications channel, until an end-of-file indicator is returned.

Discussion

This method invokes readDataOfLength: as part of its implementation.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSFileHandle.h

readInBackgroundAndNotify

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

- (void)readInBackgroundAndNotify
Discussion

This method performs an asynchronous availableData operation on a file or communications channel and posts an NSFileHandleReadCompletionNotification notification on the current thread when that operation is complete. You must call this method from a thread that has an active run loop.

The length of the data is limited to the buffer size of the underlying operating system. The notification includes a userInfo dictionary that contains the data read; access this object using the NSFileHandleNotificationDataItem key.

Any object interested in receiving this data asynchronously must add itself as an observer of NSFileHandleReadCompletionNotification. In communication via stream-type sockets, the receiver is often the object returned in the userInfo dictionary of NSFileHandleConnectionAcceptedNotification.

Note that this method does not cause a continuous stream of notifications to be sent. If you wish to keep getting notified, you’ll also need to call readInBackgroundAndNotify in your observer method.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

readInBackgroundAndNotifyForModes:

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

- (void)readInBackgroundAndNotifyForModes:(NSArray *)modes
Parameters
modes

The runloop modes in which the read completion notification can be posted.

Discussion

See readInBackgroundAndNotify for details of how this method operates. This method differs from readInBackgroundAndNotify in that modes specifies the run-loop mode (or modes) in which NSFileHandleReadCompletionNotification can be posted.

You must call this method from a thread that has an active run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

readToEndOfFileInBackgroundAndNotify

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

- (void)readToEndOfFileInBackgroundAndNotify
Discussion

This method performs an asynchronous readToEndOfFile operation on a file or communications channel and posts an NSFileHandleReadToEndOfFileCompletionNotification. You must call this method from a thread that has an active run loop.

The notification includes a userInfo dictionary that contains the data read; access this object using the NSFileHandleNotificationDataItem key.

Any object interested in receiving this data asynchronously must add itself as an observer of NSFileHandleReadToEndOfFileCompletionNotification. In communication via stream-type sockets, the receiver is often the object returned in the userInfo dictionary of NSFileHandleConnectionAcceptedNotification.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

readToEndOfFileInBackgroundAndNotifyForModes:

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

- (void)readToEndOfFileInBackgroundAndNotifyForModes:(NSArray *)modes
Parameters
modes

The runloop modes in which the read completion notification can be posted.

Discussion

See readToEndOfFileInBackgroundAndNotify for details of this method's operation. The method differs from readToEndOfFileInBackgroundAndNotify in that modes specifies the run-loop mode (or modes) in which NSFileHandleReadToEndOfFileCompletionNotification can be posted.

You must call this method from a thread that has an active run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

seekToEndOfFile

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

- (unsigned long long)seekToEndOfFile
Return Value

The file offset with the file pointer at the end of the file. This is therefore equal to the size of the file.

Special Considerations

Raises an exception if the message is sent to an NSFileHandle object representing a pipe or socket or if the file descriptor is closed.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

seekToFileOffset:

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

- (void)seekToFileOffset:(unsigned long long)offset
Parameters
offset

The offset to seek to.

Special Considerations

Raises an exception if the message is sent to an NSFileHandle object representing a pipe or socket, if the file descriptor is closed, or if any other error occurs in seeking.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

synchronizeFile

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

- (void)synchronizeFile
Discussion

This method should be invoked by programs that require the file to always be in a known state. An invocation of this method does not return until memory is flushed.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

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.

- (void)truncateFileAtOffset:(unsigned long long)offset
Parameters
offset

The offset within the file that will mark the new end of the file.

Discussion

If the file is extended (if offset is beyond the current end of file), the added characters are null bytes.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

waitForDataInBackgroundAndNotify

Asynchronously checks to see if data is available.

- (void)waitForDataInBackgroundAndNotify
Discussion

When the data becomes available, this method posts a NSFileHandleDataAvailableNotification notification on the current thread.

You must call this method from a thread that has an active run loop.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSFileHandle.h

waitForDataInBackgroundAndNotifyForModes:

Asynchronously checks to see if data is available.

- (void)waitForDataInBackgroundAndNotifyForModes:(NSArray *)modes
Parameters
modes

The runloop modes in which the data available notification can be posted.

Discussion

When the data becomes available, this method posts a NSFileHandleDataAvailableNotification notification on the current thread. This method differs from waitForDataInBackgroundAndNotify in that modes specifies the run-loop mode (or modes) in which NSFileHandleDataAvailableNotification can be posted.

You must call this method from a thread that has an active run loop.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSFileHandle.h

writeData:

Synchronously writes the specified data to the receiver.

- (void)writeData:(NSData *)data
Parameters
data

The data to be written.

Discussion

If the receiver is a file, writing takes place at the file pointer’s current position. After it writes the data, the method advances the file pointer by the number of bytes written. This method raises an exception if the file descriptor is closed or is not valid, if the receiver represents an unconnected pipe or socket endpoint, if no free space is left on the file system, or if any other writing error occurs.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSFileHandle.h

Constants

Keys for Notification UserInfo Dictionary

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

NSString * const NSFileHandleNotificationFileHandleItem;
NSString * const NSFileHandleNotificationDataItem;
Constants
NSFileHandleNotificationFileHandleItem

A key in the userinfo dictionary in a NSFileHandleConnectionAcceptedNotification notification.

The corresponding value is the NSFileHandle object representing the “near” end of a socket connection.

Available in iOS 2.0 and later.

Declared in NSFileHandle.h.

NSFileHandleNotificationDataItem

A key in the userinfo dictionary in a NSFileHandleReadCompletionNotification and NSFileHandleReadToEndOfFileCompletionNotification.

The corresponding value is an NSData object containing the available data read from a socket connection.

Available in iOS 2.0 and later.

Declared in NSFileHandle.h.

Declared In
NSFileHandle.h

Exception Names

Constant that defines the name of a file operation exception.

extern NSString *NSFileHandleOperationException;
Constants
NSFileHandleOperationException

Raised by NSFileHandle if attempts to determine file-handle type fail or if attempts to read from a file or channel fail.

Available in iOS 2.0 and later.

Declared in NSFileHandle.h.

Declared In
NSFileHandle.h

Unused Constant

Constant that is currently unused.

NSString * const NSFileHandleNotificationMonitorModes;
Constants
NSFileHandleNotificationMonitorModes

Currently unused.

Available in iOS 2.0 and later.

Deprecated in iOS 5.0.

Declared in NSFileHandle.h.

Declared In
NSFileHandle.h

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. To cause the posting of this notification, you must send either acceptConnectionInBackgroundAndNotify or acceptConnectionInBackgroundAndNotifyForModes: to an NSFileHandle object representing a server stream-type socket.

The notification object is the NSFileHandle object that sent the notification. The userInfo dictionary contains the following information:

Key

Value

NSFileHandleNotificationFileHandleItem

The NSFileHandle object representing the “near” end of a socket connection

@"NSFileHandleError"

An NSNumber object containing an integer representing the UNIX-type error which occurred

Availability
Declared In
NSFileHandle.h

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. The observers can then issue the appropriate messages to begin reading the data. To cause the posting of this notification, you must send either waitForDataInBackgroundAndNotify or waitForDataInBackgroundAndNotifyForModes: to an appropriate NSFileHandle object.

The notification object is the NSFileHandle object that sent the notification. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSFileHandle.h

NSFileHandleReadCompletionNotification

This notification is posted when the file handle reads the data currently available in a file or at a communications channel. It makes the data available to observers by putting it in the userInfo dictionary. To cause the posting of this notification, you must send either readInBackgroundAndNotify or readInBackgroundAndNotifyForModes: to an appropriate NSFileHandle object.

The notification object is the NSFileHandle object that sent the notification. The userInfo dictionary contains the following information:

Key

Value

NSFileHandleNotificationDataItem

An NSData object containing the available data read from a socket connection

@"NSFileHandleError"

An NSNumber object containing an integer representing the UNIX-type error which occurred

Availability
Declared In
NSFileHandle.h

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. It makes the data available to observers by putting it in the userInfo dictionary. To cause the posting of this notification, you must send either readToEndOfFileInBackgroundAndNotify or readToEndOfFileInBackgroundAndNotifyForModes: to an appropriate NSFileHandle object.

The notification object is the NSFileHandle object that sent the notification. The userInfo dictionary contains the following information:

Key

Value

NSFileHandleNotificationDataItem

An NSData object containing the available data read from a socket connection

@"NSFileHandleError"

An NSNumber object containing an integer representing the UNIX-type error which occurred

Availability
Declared In
NSFileHandle.h