From bf6a345baa21818010242566bef4f2c25cb72437 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Wed, 7 Aug 2013 12:20:53 -0700 Subject: [PATCH] Doc: update the documentation of QStandardPaths to be more thorough Specifically, note what paths can be empty and which ones can't (modulo system mis-configuration, like an empty $HOME var) and describe what implications there are for application-specific paths and for global (user) paths. Change-Id: If6c11aab466ba50f3a9685dce52dd51b86426f27 Reviewed-by: David Faure --- src/corelib/io/qstandardpaths.cpp | 206 ++++++++++++++++++++++++++---- 1 file changed, 182 insertions(+), 24 deletions(-) diff --git a/src/corelib/io/qstandardpaths.cpp b/src/corelib/io/qstandardpaths.cpp index 186321db6e..b32f5ac576 100644 --- a/src/corelib/io/qstandardpaths.cpp +++ b/src/corelib/io/qstandardpaths.cpp @@ -72,31 +72,189 @@ QT_BEGIN_NAMESPACE methods such as QStandardPaths::writableLocation, QStandardPaths::standardLocations, and QStandardPaths::displayName. - \value DesktopLocation Returns the user's desktop directory. - \value DocumentsLocation Returns the user's document. - \value FontsLocation Returns the user's fonts. - \value ApplicationsLocation Returns the user's applications. - \value MusicLocation Returns the user's music. - \value MoviesLocation Returns the user's movies. - \value PicturesLocation Returns the user's pictures. - \value TempLocation Returns the system's temporary directory. - \value HomeLocation Returns the user's home directory. - \value DataLocation Returns a directory location where persistent - application data can be stored. QCoreApplication::organizationName - and QCoreApplication::applicationName are appended to the directory location - returned for GenericDataLocation. - \value CacheLocation Returns a directory location where user-specific - non-essential (cached) data should be written. - \value GenericCacheLocation Returns a directory location where user-specific - non-essential (cached) data, shared across applications, should be written. - \value GenericDataLocation Returns a directory location where persistent - data shared across applications can be stored. - \value RuntimeLocation Returns a directory location where runtime communication - files should be written. For instance unix local sockets. - \value ConfigLocation Returns a directory location where user-specific - configuration files should be written. - \value DownloadLocation Returns a directory for user's downloaded files. + Some of the values in this enum represent a user configuration. Such enum + values will return the same paths in different applications, so they could + be used to share data with other applications. Other values are specific to + this application. Each enum value in the table below describes whether it's + application-specific or generic. + Application-specific directories should be assumed to be unreachable by + other applications. Therefore, files placed there might not be readable by + other applications, even if run by the same user. On the other hand, generic + directories should be assumed to be accessible by all applications run by + this user, but should still be assumed to be unreachable by applications by + other users. + + The only exception is QStandardPaths::TempLocation (which is the same as + QDir::tempPath()): the path returned may be application-specific, but files + stored there may be accessed by other applications run by the same user. + + Data interchange with other users is out of the scope of QStandardPaths. + + \value DesktopLocation Returns the user's desktop directory. This is a generic value. + On systems with no concept of a desktop, this is the same as + QStandardPaths::HomeLocation. + \value DocumentsLocation Returns the directory containing user document files. + This is a generic value. The returned path is never empty. + \value FontsLocation Returns the directory containing user's fonts. This is a generic value. + Note that installing fonts may require additional, platform-specific operations. + \value ApplicationsLocation Returns the directory containing the user applications + (either executables, application bundles, or shortcuts to them). This is a generic value. + Note that installing applications may require additional, platform-specific operations. + Files, folders or shortcuts in this directory are platform-specific. + \value MusicLocation Returns the directory containing the user's music or other audio files. + This is a generic value. If no directory specific for music files exists, a sensible + fallback for storing user documents is returned. + \value MoviesLocation Returns the directory containing the user's movies and videos. + This is a generic value. If no directory specific for movie files exists, a sensible + fallback for storing user documents is returned. + \value PicturesLocation Returns the directory containing the user's pictures or photos. + This is a generic value. If no directory specific for picture files exists, a sensible + fallback for storing user documents is returned. + \value TempLocation Returns a directory where temporary files can be stored. The returned value + might be application-specific, shared among other applications for this user, or even + system-wide. The returned path is never empty. + \value HomeLocation Returns the user's home directory (the same as QDir::homePath()). On Unix + systems, this is equal to the HOME environment variable. This value might be + generic or application-specific, but the returned path is never empty. + \value DataLocation Returns a directory location where persistent + application data can be stored. This is an application-specific directory. To obtain a + path to store data to be shared with other applications, use + QStandardPaths::GenericDataLocation. The returned path is never empty. + \value CacheLocation Returns a directory location where user-specific + non-essential (cached) data should be written. This is an application-specific directory. + The returned path is never empty. + \value GenericCacheLocation Returns a directory location where user-specific non-essential + (cached) data, shared across applications, should be written. This is a generic value. + Note that the returned path may be empty if the system has no concept of shared cache. + \value GenericDataLocation Returns a directory location where persistent + data shared across applications can be stored. This is a generic value. The returned + path is never empty. + \value RuntimeLocation Returns a directory location where runtime communication + files should be written, like Unix local sockets. This is a generic value. + The returned path may be empty on some systems. + \value ConfigLocation Returns a directory location where user-specific + configuration files should be written. This may be either a generic value + or application-specific, and the returned path is never empty. + \value DownloadLocation Returns a directory for user's downloaded files. This is a generic value. + If no directory specific for downloads exists, a sensible fallback for storing user + documents is returned. + + The following table gives examples of paths on different operating systems. + The first path is the writable path (unless noted). Other, additional + paths, if any, represent non-writable locations. + + \table + \header \li Path type \li OS X \li Windows + \row \li DesktopLocation + \li "~/Desktop" + \li "C:/Users//Desktop" + \row \li DocumentsLocation + \li "~/Documents" + \li "C:/Users//Documents" + \row \li FontsLocation + \li "/System/Library/Fonts" (not writable) + \li "C:/Windows/Fonts" (not writable) + \row \li ApplicationsLocation + \li "/Applications" (not writable) + \li "C:/Users//AppData/Roaming/Microsoft/Windows/Start Menu/Programs" + \row \li MusicLocation + \li "~/Music" + \li "C:/Users//Music" + \row \li MoviesLocation + \li "~/Movies" + \li "C:/Users//Videos" + \row \li PicturesLocation + \li "~/Pictures" + \li "C:/Users//Pictures" + \row \li TempLocation + \li randomly generated by the OS + \li "C:/Users//AppData/Local/Temp" + \row \li HomeLocation + \li "~" + \li "C:/Users/" + \row \li DataLocation + \li "~/Library/Application Support/", "/Library/Application Support/" + \li "C:/Users//AppData/Local/", "C:/ProgramData/" + \row \li CacheLocation + \li "~/Library/Caches/", "/Library/Caches/" + \li "C:/Users//AppData/Local//cache" + \row \li GenericDataLocation + \li "~/Library/Application Support", "/Library/Application Support" + \li "C:/Users//AppData/Local", "C:/ProgramData" + \row \li RuntimeLocation + \li "~/Library/Application Support" + \li "C:/Users/" + \row \li ConfigLocation + \li "~/Library/Preferences" + \li "C:/Users//AppData/Local/", "C:/ProgramData/" + \row \li DownloadLocation + \li "~/Documents" + \li "C:/Users//Documents" + \row \li GenericCacheLocation + \li "~/Library/Caches", "/Library/Caches" + \li "C:/Users//AppData/Local/cache" + \endtable + + \table + \header \li Path type \li Blackberry \li Linux (including Android) + \row \li DesktopLocation + \li "/data" + \li "~/Desktop" + \row \li DocumentsLocation + \li "/shared/documents" + \li "~/Documents" + \row \li FontsLocation + \li "/base/usr/fonts" (not writable) + \li "~/.fonts" + \row \li ApplicationsLocation + \li not supported (directory not readable) + \li "~/.local/share/applications", "/usr/local/share/applications", "/usr/share/applications" + \row \li MusicLocation + \li "/shared/music" + \li "~/Music" + \row \li MoviesLocation + \li "/shared/videos" + \li "~/Videos" + \row \li PicturesLocation + \li "/shared/photos" + \li "~/Pictures" + \row \li TempLocation + \li "/var/tmp" + \li "/tmp" + \row \li HomeLocation + \li "/data" + \li "~" + \row \li DataLocation + \li "/data" + \li "~/.local/share/", "/usr/local/share/", "/usr/share/" + \row \li CacheLocation + \li "/data/Cache" + \li "~/.cache/" + \row \li GenericDataLocation + \li "/shared/misc" + \li "~/.local/share", "/usr/local/share", "/usr/share" + \row \li RuntimeLocation + \li "/var/tmp" + \li "/run/user/" + \row \li ConfigLocation + \li "/data/Settings" + \li "~/.config", "/etc/xdg" + \row \li DownloadLocation + \li "/shared/downloads" + \li "~/Downloads" + \row \li GenericCacheLocation + \li "/data/Cache" (there is no shared cache) + \li "~/.cache" + \endtable + + In the table above, \c is usually the organization name, the + application name, or both, or a unique name generated at packaging. + Similarly, is the location where this application is installed + (often a sandbox). + + The paths above should not be relied upon, as they may change according to + OS configuration, locale, or they may change in future Qt versions. \sa writableLocation(), standardLocations(), displayName(), locate(), locateAll() */