NSObject(GMUserFileSystemOperations)


Extends Class: NSObject
Declared In: GMUserFileSystem

Discussion

The core set of file system operations the delegate must implement. Unless otherwise noted, they typically should behave like the NSFileManager equivalent. However, the error codes that they return should correspond to the BSD-equivalent call and be in the NSPOSIXErrorDomain.

For a read-only filesystem, you can typically pick-and-choose which methods to implement. For example, a minimal read-only filesystem might implement:

For a writeable filesystem, the Finder can be quite picky unless the majority of these methods are implemented. However, you can safely skip hard-links, symbolic links, and extended attributes.



Methods

-contentsOfDirectoryAtPath:error:
Returns directory contents at the specified path.
-attributesOfItemAtPath:userData:error:
Returns attributes at the specified path.
-attributesOfFileSystemForPath:error:
Returns file system attributes.
-setAttributes:ofItemAtPath:userData:error:
Set attributes at the specified path.
-contentsAtPath:
Returns directory contents at the specified path.
-openFileAtPath:mode:userData:error:
Opens the file at the given path for read/write.
-releaseFileAtPath:userData:
Called when an opened file is closed.
-readFileAtPath:userData:buffer:size:offset:error:
Reads data from the open file at the specified path.
-writeFileAtPath:userData:buffer:size:offset:error:
Writes data to the open file at the specified path.
-exchangeDataOfItemAtPath:withItemAtPath:error:
Atomically exchanges data between files.
-createDirectoryAtPath:attributes:error:
Creates a directory at the specified path.
-createFileAtPath:attributes:userData:error:
Creates and opens a file at the specified path.
-moveItemAtPath:toPath:error:
Moves or renames an item.
-removeDirectoryAtPath:error:
Remove the directory at the given path.
-removeItemAtPath:error:
Removes the item at the given path.
-linkItemAtPath:toPath:error:
Creates a hard link.
-createSymbolicLinkAtPath:withDestinationPath:error:
Creates a symbolic link.
-destinationOfSymbolicLinkAtPath:error:
Reads the destination of a symbolic link.
-extendedAttributesOfItemAtPath:error:
Returns the names of the extended attributes at the specified path.
-valueOfExtendedAttribute:ofItemAtPath:position:error:
Returns the contents of the extended attribute at the specified path.
-setExtendedAttribute:ofItemAtPath:value:position:options:error:
Writes the contents of the extended attribute at the specified path.
-removeExtendedAttribute:ofItemAtPath:error:
Removes the extended attribute at the specified path.

contentsOfDirectoryAtPath:error:


Returns directory contents at the specified path.

See Also:
readdir(3)
- (NSArray *)contentsOfDirectoryAtPath:(NSString *)path 
        error:(NSError **)error;
Parameters
path
The path to a directory.
error
Should be filled with a POSIX error in case of failure.
Return Value

An array of NSString or nil on error.

Discussion

Returns an array of NSString containing the names of files and sub-directories in the specified directory.


attributesOfItemAtPath:userData:error:


Returns attributes at the specified path.

See Also:
stat(2), fstat(2)
- (NSDictionary *)attributesOfItemAtPath:(NSString *)path userData:(id)userData error:(NSError **)error; 
Parameters
path
The path to the item.
userData
The userData corresponding to this open file or nil.
error
Should be filled with a POSIX error in case of failure.
Return Value

A dictionary of attributes or nil on error.

Discussion

Returns a dictionary of attributes at the given path. It is required to return at least the NSFileType attribute. You may omit the NSFileSize attribute if contentsAtPath: is implemented, although this is less efficient. The following keys are currently supported (unknown keys are ignored):


If this is the fstat variant and userData was supplied in openFileAtPath: or createFileAtPath: then it will be passed back in this call.


attributesOfFileSystemForPath:error:


Returns file system attributes.

See Also:
statvfs(3)
- (NSDictionary *)attributesOfFileSystemForPath:(NSString *)path error:(NSError **)error; 
Parameters
path
A path on the file system (it is safe to ignore this).
error
Should be filled with a POSIX error in case of failure.
Return Value

A dictionary of attributes for the file system.

Discussion

Returns a dictionary of attributes for the file system. The following keys are currently supported (unknown keys are ignored):



setAttributes:ofItemAtPath:userData:error:


Set attributes at the specified path.

See Also:
truncate(2), chown(2), chmod(2), utimes(2), chflags(2),
fchown(2), fchmod(2), futimes(2), fchflags(2)
- (BOOL)setAttributes:(NSDictionary *)attributes ofItemAtPath:(NSString *)path userData:(id)userData error:(NSError **)error; 
Parameters
attributes
The attributes to set.
path
The path to the item.
userData
The userData corresponding to this open file or nil.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the attributes are successfully set.

Discussion

Sets the attributes for the item at the specified path. The following keys may be present (you must ignore unknown keys):


If this is the f-variant and userData was supplied in openFileAtPath: or createFileAtPath: then it will be passed back in this call.


contentsAtPath:


Returns directory contents at the specified path.

- (NSData *)contentsAtPath:(NSString *)path; 
Parameters
path
The path to the file.
Return Value

The contents of the file or nil if a file does not exist at path.

Discussion

Returns the full contents at the given path. Implementation of this delegate method is recommended only by very simple file systems that are not concerned with performance. If contentsAtPath is implemented then you can skip open/release/read.


openFileAtPath:mode:userData:error:


Opens the file at the given path for read/write.

See Also:
open(2)
- (BOOL)openFileAtPath:(NSString *)path mode:(int)mode userData:(id *)userData error:(NSError **)error; 
Parameters
path
The path to the file.
mode
The open mode for the file (e.g. O_RDWR, etc.)
userData
Out parameter that can be filled in with arbitrary user data. The given userData will be retained and passed back in to delegate methods that are acting on this open file.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the file was opened successfully.

Discussion

This will only be called for existing files. If the file needs to be created then createFileAtPath: will be called instead.


releaseFileAtPath:userData:


Called when an opened file is closed.

See Also:
close(2)
- (void)releaseFileAtPath:(NSString *)path userData:(id)userData; 
Parameters
path
The path to the file.
userData
The userData corresponding to this open file or nil.
Discussion

If userData was provided in the corresponding openFileAtPath: call then it will be passed in userData and released after this call completes.


readFileAtPath:userData:buffer:size:offset:error:


Reads data from the open file at the specified path.

See Also:
pread(2)
- (int)readFileAtPath:(NSString *)path userData:(id)userData buffer:(char *)buffer size:(size_t)size offset:(off_t)offset error:(NSError **)error; 
Parameters
path
The path to the file.
userData
The userData corresponding to this open file or nil.
buffer
Byte buffer to read data from the file into.
size
The size of the provided buffer.
offset
The offset in the file from which to read data.
error
Should be filled with a POSIX error in case of failure.
Return Value

The number of bytes read or -1 on error.

Discussion

Reads data from the file starting at offset into the provided buffer and returns the number of bytes read. If userData was provided in the corresponding openFileAtPath: or createFileAtPath: call then it will be passed in.


writeFileAtPath:userData:buffer:size:offset:error:


Writes data to the open file at the specified path.

See Also:
pwrite(2)
- (int)writeFileAtPath:(NSString *)path userData:(id)userData buffer:(const char *)buffer size:(size_t)size offset:(off_t)offset error:(NSError **)error; 
Parameters
path
The path to the file.
userData
The userData corresponding to this open file or nil.
buffer
Byte buffer containing the data to write to the file.
size
The size of the provided buffer.
offset
The offset in the file to write data.
error
Should be filled with a POSIX error in case of failure.
Return Value

The number of bytes written or -1 on error.

Discussion

Writes data to the file starting at offset from the provided buffer and returns the number of bytes written. If userData was provided in the corresponding openFileAtPath: or createFileAtPath: call then it will be passed in.


exchangeDataOfItemAtPath:withItemAtPath:error:


Atomically exchanges data between files.

See Also:
exchangedata(2)
- (BOOL)exchangeDataOfItemAtPath:(NSString *)path1 withItemAtPath:(NSString *)path2 error:(NSError **)error; 
Parameters
path1
The path to the file.
path2
The path to the other file.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if data was exchanged successfully.

Discussion

Called to atomically exchange file data between path1 and path2.


createDirectoryAtPath:attributes:error:


Creates a directory at the specified path.

See Also:
mkdir(2)
- (BOOL)createDirectoryAtPath:(NSString *)path attributes:(NSDictionary *)attributes error:(NSError **)error; 
Parameters
path
The directory path to create.
attributes
Set of attributes to apply to the newly created directory.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the directory was successfully created.

Discussion

The attributes may contain keys similar to setAttributes:.


createFileAtPath:attributes:userData:error:


Creates and opens a file at the specified path.

See Also:
creat(2)
- (BOOL)createFileAtPath:(NSString *)path attributes:(NSDictionary *)attributes userData:(id *)userData error:(NSError **)error; 
Parameters
path
The path of the file to create.
attributes
Set of attributes to apply to the newly created file.
userData
Out parameter that can be filled in with arbitrary user data. The given userData will be retained and passed back in to delegate methods that are acting on this open file.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the directory was successfully created.

Discussion

This should create and open the file at the same time. The attributes may contain keys similar to setAttributes:.


moveItemAtPath:toPath:error:


Moves or renames an item.

See Also:
rename(2)
- (BOOL)moveItemAtPath:(NSString *)source toPath:(NSString *)destination error:(NSError **)error; 
Parameters
source
The source file or directory.
destination
The destination file or directory.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the move was successful.

Discussion

Move, also known as rename, is one of the more difficult file system methods to implement properly. Care should be taken to handle all error conditions and return proper POSIX error codes.


removeDirectoryAtPath:error:


Remove the directory at the given path.

See Also:
rmdir(2)
- (BOOL)removeDirectoryAtPath:(NSString *)path error:(NSError **)error; 
Parameters
path
The directory to remove.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the directory was successfully removed.

Discussion

Unlike NSFileManager, this should not recursively remove subdirectories. If this method is not implemented, then removeItemAtPath will be called even for directories.


removeItemAtPath:error:


Removes the item at the given path.

See Also:
unlink(2), rmdir(2)
- (BOOL)removeItemAtPath:(NSString *)path error:(NSError **)error; 
Parameters
path
The path to the item to remove.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the item was successfully removed.

Discussion

This should not recursively remove subdirectories. If removeDirectoryAtPath is implemented, then that will be called instead of this selector if the item is a directory.


linkItemAtPath:toPath:error:


Creates a hard link.

See Also:
link(2)
- (BOOL)linkItemAtPath:(NSString *)path toPath:(NSString *)otherPath error:(NSError **)error; 
Parameters
path
The path for the created hard link.
otherPath
The path that is the target of the created hard link.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the hard link was successfully created.


createSymbolicLinkAtPath:withDestinationPath:error:


Creates a symbolic link.

See Also:
symlink(2)
- (BOOL)createSymbolicLinkAtPath:(NSString *)path withDestinationPath:(NSString *)otherPath error:(NSError **)error; 
Parameters
path
The path for the created symbolic link.
otherPath
The path that is the target of the symbolic link.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the symbolic link was successfully created.


destinationOfSymbolicLinkAtPath:error:


Reads the destination of a symbolic link.

See Also:
readlink(2)
- (NSString *)destinationOfSymbolicLinkAtPath:(NSString *)path error:(NSError **)error; 
Parameters
path
The path to the specified symlink.
error
Should be filled with a POSIX error in case of failure.
Return Value

The destination path of the symbolic link or nil on error.


extendedAttributesOfItemAtPath:error:


Returns the names of the extended attributes at the specified path.

See Also:
listxattr(2)
- (NSArray *)extendedAttributesOfItemAtPath:path error:(NSError **)error; 
Parameters
path
The path to the specified file.
error
Should be filled with a POSIX error in case of failure.
Return Value

An NSArray of extended attribute names or nil on error.

Discussion

If there are no extended attributes at this path, then return an empty array. Return nil only on error.


valueOfExtendedAttribute:ofItemAtPath:position:error:


Returns the contents of the extended attribute at the specified path.

See Also:
getxattr(2)
- (NSData *)valueOfExtendedAttribute:(NSString *)name ofItemAtPath:(NSString *)path position:(off_t)position error:(NSError **)error; 
Parameters
name
The name of the extended attribute.
path
The path to the specified file.
position
The offset within the attribute to read from.
error
Should be filled with a POSIX error in case of failure.
Return Value

The data corresponding to the attribute or nil on error.


setExtendedAttribute:ofItemAtPath:value:position:options:error:


Writes the contents of the extended attribute at the specified path.

See Also:
setxattr(2)
- (BOOL)setExtendedAttribute:(NSString *)name ofItemAtPath:(NSString *)path value:(NSData *)value position:(off_t)position options:(int)options error:(NSError **)error; 
Parameters
name
The name of the extended attribute.
path
The path to the specified file.
value
The data to write.
position
The offset within the attribute to write to
options
Options (see setxattr man page).
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the attribute was successfully written.


removeExtendedAttribute:ofItemAtPath:error:


Removes the extended attribute at the specified path.

See Also:
removexattr(2)
- (BOOL)removeExtendedAttribute:(NSString *)name ofItemAtPath:(NSString *)path error:(NSError **)error; 
Parameters
name
The name of the extended attribute.
path
The path to the specified file.
error
Should be filled with a POSIX error in case of failure.
Return Value

YES if the attribute was successfully removed.

Last Updated: Monday, November 17, 2008