// Name: filename.h
// Purpose: interface of wxFileName
// Author: wxWidgets team
-// RCS-ID: $Id$
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
wxPATH_RMDIR_RECURSIVE = 2
};
+/**
+ Flags for wxFileName::Exists().
+
+ @since 2.9.5
+ */
+enum
+{
+ wxFILE_EXISTS_REGULAR = 0x0001, //!< Check for existence of a regular file
+ wxFILE_EXISTS_DIR = 0x0002, //!< Check for existence of a directory
+ /**
+ Check for existence of a symlink.
+
+ Notice that this flag also sets ::wxFILE_EXISTS_NO_FOLLOW, otherwise it
+ would never be satisfied as wxFileName::Exists() would be checking for
+ the existence of the symlink target and not the symlink itself.
+ */
+ wxFILE_EXISTS_SYMLINK = 0x1004,
+ wxFILE_EXISTS_DEVICE = 0x0008, //!< Check for existence of a device
+ wxFILE_EXISTS_FIFO = 0x0016, //!< Check for existence of a FIFO
+ wxFILE_EXISTS_SOCKET = 0x0032, //!< Check for existence of a socket
+ wxFILE_EXISTS_NO_FOLLOW = 0x1000 //!< Don't dereference a contained symbolic link
+ wxFILE_EXISTS_ANY = 0x1FFF, //!< Check for existence of anything
+};
+
/**
The return value of wxFileName::GetSize() in case of error.
*/
wxPathFormat format = wxPATH_NATIVE);
/**
- Appends a directory component to the path. This component should contain a
- single directory name level, i.e. not contain any path or volume separators nor
- should it be empty, otherwise the function does nothing (and generates an
- assert failure in debug build).
+ Appends a directory component to the path.
+
+ This component should contain a single directory name level, i.e. not
+ contain any path or volume separators nor should it be empty, otherwise
+ the function does nothing and returns false (and generates an assert
+ failure in debug build).
+
+ Notice that the return value is only available in wxWidgets 2.9.5 or
+ later.
*/
- void AppendDir(const wxString& dir);
+ bool AppendDir(const wxString& dir);
/**
Creates the file name from another filename object.
wxPathFormat format = wxPATH_NATIVE);
/**
+ Turns off symlink dereferencing.
+
+ By default, all operations in this class work on the target of a
+ symbolic link (symlink) if the path of the file is actually a symlink.
+ Using this method allows to turn off this "symlink following" behaviour
+ and apply the operations to this path itself, even if it is a symlink.
+
+ The following methods are currently affected by this option:
+ - GetTimes() (but not SetTimes() as there is no portable way to
+ change the time of symlink itself).
+ - Existence checks: FileExists(), DirExists() and Exists() (notice
+ that static versions of these methods always follow symlinks).
+ - IsSameAs().
+
+ @see ShouldFollowLink()
+
+ @since 2.9.5
+ */
+ void DontFollowLink();
+
+ /**
Calls the static overload of this function with the full path of this
object.
- @since 2.9.4
+ @since 2.9.4 (@a flags is new since 2.9.5)
*/
- bool Exists() const;
+ bool Exists(int flags = wxFILE_EXISTS_ANY) const;
/**
Returns @true if either a file or a directory or something else with
this name exists in the file system.
+ Don't dereference @a path if it is a symbolic link and @a flags
+ argument contains ::wxFILE_EXISTS_NO_FOLLOW.
+
This method is equivalent to @code FileExists() || DirExists() @endcode
- under most systems but under Unix it also returns true if the file
+ under Windows, but under Unix it also returns true if the file
identifies a special file system object such as a device, a socket or a
FIFO.
+ Alternatively you may check for the existence of a file system entry of
+ a specific type by passing the appropriate @a flags (this parameter is
+ new since wxWidgets 2.9.5). E.g. to test for a symbolic link existence
+ you could use ::wxFILE_EXISTS_SYMLINK.
+
@since 2.9.4
@see FileExists(), DirExists()
*/
- static bool Exists(const wxString& path);
+ static bool Exists(const wxString& path, int flags = wxFILE_EXISTS_ANY);
/**
Returns @true if the file with this name exists.
bool HasVolume() const;
/**
- Inserts a directory component before the zero-based position in the directory
- list. Please see AppendDir() for important notes.
+ Inserts a directory component before the zero-based position in the
+ directory list.
+
+ As with AppendDir(), @a dir must be a single directory name and the
+ function returns @false and does nothing else if it isn't.
+
+ Notice that the return value is only available in wxWidgets 2.9.5 or
+ later.
*/
- void InsertDir(size_t before, const wxString& dir);
+ bool InsertDir(size_t before, const wxString& dir);
/**
Returns @true if this filename is absolute.
*/
void SetPath(const wxString& path, wxPathFormat format = wxPATH_NATIVE);
+ /**
+ Sets permissions for this file or directory.
+
+ @param permissions
+ The new permissions: this should be a combination of
+ ::wxPosixPermissions enum elements.
+
+ @since 3.0
+
+ @note If this is a symbolic link and it should not be followed
+ this call will fail.
+
+ @return @true on success, @false if an error occurred (for example,
+ the file doesn't exist).
+ */
+ bool SetPermissions(int permissions)
+
/**
Sets the file creation and last access/modification times (any of the pointers
may be @NULL).
+
+ Notice that the file creation time can't be changed under Unix, so @a
+ dtCreate is ignored there (but @true is still returned). Under Windows
+ all three times can be set.
*/
bool SetTimes(const wxDateTime* dtAccess,
const wxDateTime* dtMod,
*/
void SetVolume(const wxString& volume);
+ /**
+ Return whether some operations will follow symlink.
+
+ By default, file operations "follow symlink", i.e. operate on its
+ target and not on the symlink itself. See DontFollowLink() for more
+ information.
+
+ @since 2.9.5
+ */
+ bool ShouldFollowLink() const;
+
//@{
/**
This function splits a full file name into components: the volume (with the
projects / wxWidgets.git / blobdiff