The rules for path handling depend on the value in the
GNUSTEP_PATH_HANDLING environment
variable and, to some extent, on the platform on
which the program is running. The understood
values of GNUSTEP_PATH_HANDLING are unix and
windows. If GNUSTEP_PATH_HANDLING is any other
value (or has not been set), GNUstep interprets this as
meaning it should try to do-the-right-thing In the default mode of operation the system is
very tolerant of paths and allows you to work with both
unix and windows style paths. The consequences of this
are apparent in the path handling methods of
NSString
rather than in
NSFileManager
.
On all Unix platforms, Path components are separated
by slashes and file names may contain any character
other than slash. The file names. and..
are special cases meaning current directory and the
parent of the current directory respectively.
Multiple adjacent slash characters are
treated as a single separator.
/
An absolute path to the root directory.
/etc/motd
An absolute path to the file named motd
in the subdirectory etc of the root
directory.
..
A relative path to the parent of the current
directory.
program.m
A relative path to the file program.m in
the current directory.
Source/program.m
A relative path to the file program.m in
the subdirectory Source of the current
directory.
../GNUmakefile
A relative path to the file GNUmakefile in
the directory above the current directory.
On Microsoft Windows the native paths may be either
UNC or drive-relative, so GNUstep supports both.
Either or both slash (/) and backslash
(\) may be used as separators for path components
in either type of name. UNC paths follow the
general form //host/share/path/file, but must
at least contain the host and share parts, i.e.
//host/share is a UNC path, but //host is
not Drive-relative names consist
of an optional drive specifier (consisting of a
single letter followed by a single colon)
followed by an absolute or relative path.
In both forms, the names. and.. are refer
to the current directory and the parent directory as
in unix paths.
//host/share/file
An absolute UNC path to a file called
file in the top directory of the export
point share on host.
C:
A relative path to the current directory on drive
C.
C:program.m
A relative path to the file program.m on
drive C.
C:\program.m
An absolute path to the file program.m in
the top level directory on drive C.
/Source\program.m
A drive-relative path to program.m in the
directory Source on the current
drive.
\\name
A drive-relative path to name in the top
level directory on the current drive. The '\\'
is treated as a single backslash as this is not a
UNC name (there must be both a host and a share
part in a UNC name).
In the default mode, GNUstep handles both unix and
windows paths so it treats both slash (/) and
backslash (\) as separators and understands
the windows UNC and drive relative path roots.
However, it treats any path beginning
with a slash (/) as an absolute path
if running on a unix system.
Attempting to pass absolute paths between
applications working on different systems
is fraught with difficulty... just don't do it.
Where paths need to be passed around (eg.
in property lists or archives) you should pass
relative paths and use a standard mechanism to
construct an absolute path in the receiving
application, for instance, appending the
relative path to the home directory of a user.
Use only the slash (/) as a path separator, not
backslash (\).
Never use a backslash (\) in a file name.
Avoid colons in file names.
Use no more than three letters in a path
extension.
GNUstep handles substitution of tilde (~) as
follows: If a path is just ~ or begins
~/ then the value returned by
NSHomeDirectory()
is substituted for the tilde. If a path is of
the form ~name or begins with a string like ~name/
then name is used as the argument to
NSHomeDirectoryForUser()
and the return value from that method (if non-nil)
is used to replace the tilde.
This is a subclass of NSEnumerator which
provides a full listing of all the files beneath a
directory and its subdirectories. Instances can
be obtained through
[NSFileManager -enumeratorAtPath:]
.
This implementation is optimized and performance
should be comparable to the speed of standard Unix
tools for large directories.
The order in which directory contents are enumerated is
undefined, and in the current implementation the
natural order of the underlying filesystem is used.
Informs the receiver that any descendents of the
current directory should be skipped rather than
enumerated. Use this to avoid enumerating the
contents of directories you are not interested in.
This is the main class for platform-independent
management of the local filesystem, which allows
you to read and save files, create/list directories, and
move or delete files and directories. In addition to
simply listing directories, you may obtain an
NSDirectoryEnumerator
instance for recursive directory contents
enumeration.
Returns an array of search paths to look at for
resources. The paths are returned in
domain order: USER, LOCAL, NETWORK then
SYSTEM. The presence of a path in this list
does not mean that the path actually exists
in the filesystem. If you are wanting to locate
an existing resource, you should normally call this
method with NSAllDomainsMask, but if you wish to
find the path in which you should create a new file,
you would generally specify a particular
domain, and then create the path in the
file system if it does not already exist.
If a file (or directory etc) exists at the specified
path, and can be queried for its
attributes, this method returns a dictionary
containing the various attributes of that file.
Otherwise nil is returned. If
an error occurs, error describes
the problem. Pass NULL if you do not want
error information.
The dictionary keys for attributes are -
NSFileAppendOnly
NSNumber... boolean
NSFileCreationDate
NSDate when the file was created (if supported)
NSFileDeviceIdentifier
NSNumber (identifies the device on which the
file is stored)
NSFileExtensionHidden
NSNumber... boolean
NSFileGroupOwnerAccountName
NSString name of the file group
NSFileGroupOwnerAccountID
NSNumber ID of the file group
NSFileHFSCreatorCode
NSNumber not used
NSFileHFSTypeCode
NSNumber not used
NSFileImmutable
NSNumber... boolean
NSFileModificationDate
NSDate when the file was last modified
NSFileOwnerAccountName
NSString name of the file owner
NSFileOwnerAccountID
NSNumber ID of the file owner
NSFilePosixPermissions
NSNumber posix access permissions mask
NSFileReferenceCount
NSNumber number of links to this file
NSFileSize
NSNumber size of the file in bytes
NSFileSystemFileNumber
NSNumber the identifier for the file on the
filesystem
NSFileSystemNumber
NSNumber the filesystem on which the file is
stored
NSFileType
NSString the type of file
The
NSDictionary
class also has a set of convenience accessor
methods which enable you to get at file
attribute information more efficiently than
using the keys above to extract it. You should
generally use the accessor methods where they
are available.
Changes the current directory used for all
subsequent operations. All non-absolute
paths are interpreted relative to this directory.
The current directory is set on a per-task
basis, so the current directory for other file
manager instances will also be changed by this
method.
Change the attributes of the file at
path to those specified. Returns
YES if all requested changes were made
(or if the dictionary was nil or empty, so
no changes were requested), NO otherwise.
On failure, some of the requested changes may
have taken place.
Returns an array of path components
suitably modified for display to the end user.
This modification may render the returned strings
unusable for path manipulation, so you
should work with two arrays... one returned by this
method (for display to the user), and a parallel one
returned by
[NSString -pathComponents]
(for path manipulation).
Returns YES if the contents of the
file or directory at path1 are the same as
those at path2. If path1
and path2 are files, this is a simple
comparison. If they are directories, the
contents of the files in those subdirectories are
compared recursively. Symbolic links are
not followed. A comparison checks first file
identity, then size, then content.
Returns an array of NSStrings of the contents of
the specified directory. The listing does
not recursively list
subdirectories. The special files
'.' and '..' are not listed. Indicates an
error by returning nil (eg.
if path is not a directory or it can't be
read for some reason).
Returns an array of NSURL of the contents of the
specified directory. The listing is
shallow and does not recurse into subdirectories.
The special files '.' and '..' are excluded but it can
return hidden files. The only mask
option supported is
NSDirectoryEnumerationSkipsHiddenFiles.
The current implementation handles only files
and property keys are ignored.
Copies the item specified by the src path
to the location specified by the dst path. If
the src is a directory, it is copied
recursively with all of its contents.
Errors are returned in the error
variable. Returns YES on success,
NO otherwise.
Copies the a file or directory specified by the
src URL to the location specified by the
dst URL. If the src is a
directory, it is copied recursively with all of
its contents. Errors are returned in the
error variable. Returns YES
on success, NO otherwise.
Copies the file or directory at source to
destination, using a handler
object which may respond to
[NSObject(NSFileManagerHandler) -fileManager:willProcessPath:]
and [NSObject(NSFileManagerHandler) -fileManager:shouldProceedAfterError:]
messages. If the handler responds to the first message, it is used to inform the handler when an item is about to be copied. If the handler responds to the second message, it is used to ask the handler whether to continue with the copy after an error (when there is no handler the processing stops at the point when an error occurs). Symbolic links are copied themselved rather than causing the items they link to be copied. Will not copy to a destination which already exists.
Creates a new directory, and sets its
attributes as specified. Fails if
directories in the path are missing.
Returns YES if the directory was
actually created, NO otherwise.
Creates a new directory (and all intermediate
directories if flag is
YES). Creates only the last directory
in the path if flag is
NO. The directory is created
with the attributes specified, and any
problem is returned in error.
Returns YES if the directory is
created (or flag is YES and
the directory already exists), NO on
failure.
Creates a new directory and all intermediate
directories in the file URL if flag
is YES. Creates only the last
directory in the URL if flag is
NO. The directory is created
with the attributes specified and any
problem is returned in error.
Returns YES if the directory is
created (or flag is YES and
the directory already exists), NO on
failure.
Returns an array of the contents of the specified
directory. The listing does
not recursively list
subdirectories. The special files
'.' and '..' are not listed. Indicates an error
by returning nil (eg. if path is
not a directory or it can't be read for some reason).
Returns the name of the file or directory at
path. Converts it into a format for
display to an end user. This may render it unusable
as part of a file/path name. For instance, if a
user has elected not to see file extensions, this
method may return filenames with the extension
removed. The default operation is to return
the result of calling
[NSString -lastPathComponent]
on the path.
Returns an enumerator which can be used to return
each item with the directory at path in
turn.
The enumeration is recursive... following all nested
subdirectories.
The order in which directory contents are enumerated
is undefined, and in the current implementation the
natural order of the underlying filesystem is
used.
Returns the attributes dictionary for the file at
the specified path. If that file is a
symbolic link, the flag determines
whether the attributes returned are those of the
link or those of the destination file. If a
file (or directory etc) exists at the specified
path, and can be queried for its
attributes, this method returns a dictionary
containing the various attributes of that file.
Otherwise nil is returned. If
the flag is NO and the file is
a symbolic link, the attributes of the link itself
(rather than the file it points to) are returned.
The dictionary keys for attributes are -
NSFileAppendOnly
NSNumber... boolean
NSFileCreationDate
NSDate when the file was created (if supported)
NSFileDeviceIdentifier
NSNumber (identifies the device on which the
file is stored)
NSFileExtensionHidden
NSNumber... boolean
NSFileGroupOwnerAccountName
NSString name of the file group
NSFileGroupOwnerAccountID
NSNumber ID of the file group
NSFileHFSCreatorCode
NSNumber not used
NSFileHFSTypeCode
NSNumber not used
NSFileImmutable
NSNumber... boolean
NSFileModificationDate
NSDate when the file was last modified
NSFileOwnerAccountName
NSString name of the file owner
NSFileOwnerAccountID
NSNumber ID of the file owner
NSFilePosixPermissions
NSNumber posix access permissions mask
NSFileReferenceCount
NSNumber number of links to this file
NSFileSize
NSNumber size of the file in bytes
NSFileSystemFileNumber
NSNumber the identifier for the file on the
filesystem
NSFileSystemNumber
NSNumber the filesystem on which the file is
stored
NSFileType
NSString the type of file
The
NSDictionary
class also has a set of convenience accessor
methods which enable you to get at file
attribute information more efficiently than
using the keys above to extract it. You should
generally use the accessor methods where they
are available.
Returns YES if a file (or directory
etc) exists at the specified path.
If the isDirectory argument is not a nul
pointer, stores a flag in the location it points
to, indicating whether the file is a directory or not.
Convert from OpenStep internal string format to a
string in the local filesystem format, suitable for
passing to system functions. This
representation may vary between filesystems.
Converts the standard path
separator ('/') and path extension
('.') characters to the local representation if
necessary. On mingw32 systems, the
filesystem representation is 16-bit unicode and
is expected to be used in conjunction with the variants
of system calls which work with unicode strings.
Raises an exception if the character conversion is
not possible.
If the destination is a directory, the
source path is linked into that
directory, otherwise the
destination must not exist, but its
parent directory must exist and the
source will be linked into the parent as
the name specified by the destination.
If the source is a symbolic link, it is
copied to the destination. If
the source is a directory, it is copied to
the destination and its contents are
linked into the new directory. Otherwise, a
hard link is made from the destination to
the source.
Moves the file or directory at source to
destination, using a handler
object which should respond to
[NSObject(NSFileManagerHandler) -fileManager:willProcessPath:]
and [NSObject(NSFileManagerHandler) -fileManager:shouldProceedAfterError:]
messages. If the handler responds to the first message, it is used to inform the handler when an item is about to be moved. If the handler responds to the second message, it is used to ask the handler whether to continue with the move after an error (when there is no handler the processing stops at the point when an error occurs). Will not move to a destination which already exists.
Removes the file or directory specified by the
path to be removed. If the path
points to a directory, the directory is deleted
recursively. Returns YES
on success, otherwise NO.
Removes the file or directory specified by the
url to be removed. If the url
points to a directory, the directory is deleted
recursively. Returns YES
on success, otherwise NO.
Convert to OpenStep internal string
format from a string in the local
filesystem format, as returned by system
functions. This representation may vary
between filesystems. The GNUstep version of
this method currently does not bother to change any
path separator and extension characters to the
standard values ('/' and '.' respectively) as the
path handling methods of
NSString
should be able to handle native format strings.
On mingw32 systems, the filesystem
representation is 16-bit unicode and is
expected to have come from the variant of a
system call which works with unicode strings.
Returns an array containing the (relative) paths of
all the items in the directory at path.
The listing follows all subdirectories, so it
can produce a very large array... use with care.
When an error occurs during a copy or move
operation, the file manager will send this
message to the handler, and will use the return
value to determine whether the operation should
proceed. If the method returns YES
then the operation will proceed after the error, if
it returns NO then it will be aborted.
If the handler does not implement this method it will
be treated as if it returns NO.
The error dictionary contains the following
"Error" contains a
description of the error.
"Path" contains the path that
is being processed when an error occurred. If an
error occurs during an operation involving two
files, like copying, and it is not clear which
file triggers the error it will default to the
source file.
"FromPath" (Optional)
contains the path involved in reading.
"ToPath" (Optional) contains
the path involved in writing.
Note that the FromPath is a GNUstep
extension.
Also the FromPath and
ToPath are filled in when
appropriate. So when copying a file they
will typically both have a value and when reading
only FromPath.
The file manager sends this method to the handler
immediately before performing part of a
directory move or copy operation. This provides
the handler object with information it can use in the
event of an error, to decide whether processing
should proceed after the error.