1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

QFile::moveToTrash: add documentation about run time and fail conditions

Browse Source 
All of the implementations will attempt to perform a filesystem rename,
so the runtime is constant for a single file and possibly for a
directory full of files too.

The macOS and Windows implementations use the OS API so they run with
slightly elevated privileges. That means they don't fail under normal
conditions. The XDG implementation will fail if the file or dir being
trashed resides on a volume which doesn't have an existing trash
location for the current user and one such cannot be created either, or
if the hardlinking/renaming fails (usually with EXDEV).

Pick-to: 6.6 6.7
Change-Id: I76ffba14ece04f24b43efffd17abd67e20196f2b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
This commit is contained in:
Thiago Macieira 2024-01-19 11:32:01 -08:00
parent fcaf9a476f
commit 6d1b4d5740
2 changed files with 26 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/global/externalsites/external-resources.qdoc
View File

@ -566,3 +566,8 @@
\externalpage https://www.qt.io/product/quality-assurance/test-center
\title Test Center
*/
/*!
\externalpage https://specifications.freedesktop.org/trash-spec/trashspec-1.0.html
\title FreeDesktop.org Trash specification version 1.0
*/

21
src/corelib/io/qfile.cpp
View File

@ -459,6 +459,24 @@ QFile::remove(const QString &fileName)
and sets the fileName() to the path at which the file can be found within the trash;
otherwise returns \c false.
//! [move-to-trash-common]
The time for this function to run is independent of the size of the file
being trashed. If this function is called on a directory, it may be
proportional to the number of files being trashed.
This function uses the Windows and \macos APIs to perform the trashing on
those two operating systems. Elsewhere (Unix systems), this function
implements the \l{FreeDesktop.org Trash specification version 1.0}.
\note When using the FreeDesktop.org Trash implementation, this function
will fail if it is unable to move the files to the trash location by way of
file renames and hardlinks. This condition arises if the file being trashed
resides on a volume (mount point) on which the current user does not have
permission to create the \c{.Trash} directory, or with some unusual
filesystem types or configurations (such as sub-volumes that aren't
themselves mount points).
//! [move-to-trash-common]
\note On systems where the system API doesn't report the location of the file in the
trash, fileName() will be set to the null string once the file has been moved. On
systems that don't have a trash can, this function always returns false.
@ -496,9 +514,12 @@ QFile::moveToTrash()
and sets \a pathInTrash (if provided) to the path at which the file can be found within
the trash; otherwise returns \c false.
\include qfile.cpp move-to-trash-common
\note On systems where the system API doesn't report the path of the file in the
trash, \a pathInTrash will be set to the null string once the file has been moved.
On systems that don't have a trash can, this function always returns false.
*/
bool
QFile::moveToTrash(const QString &fileName, QString *pathInTrash)