Settings, User Data and Files

Applications access three kinds of information from the user’s account: settings, user data and files. These hold three different kinds of information.

Settings

Settings hold information about the way the user has configured an application, such as the font size, window size or theme. This information is typically about the application itself or metadata that describes data produced by the application.

GNOME applications access their settings using the GSettings class. This stores data in a suitable directory in the user’s home directory. Applications distributed as flatpaks require permissions to be granted in order to access the user’s settings. See the Application Permissions guide for details.

User Data

Some applications prefer to store data that the user has created or imported in a special data directory set aside for the application.

Simple data can be accessed using keyfiles that record pieces of information as key-value pairs. Access to a suitable data directory is obtained using the GLib.get_user_data_dir() function. The GKeyFile class is used to read and write keyfiles stored in a subdirectory of the data directory.

More complex and larger data is also included in the user data directories by applications where it does not necessarily make sense for the user to decide where their data should be stored. These applications function like appliances, hiding the details of data storage, or using different ways to refer to user data than applications using the traditional Open, Load and Save actions.

Applications distributed as flatpaks do not need to request permissions in order to access user data stored in a data directory that has been set aside for that purpose.

Files

Traditional applications can load and save files from arbitrary directories as long as the user has permission to access them. For types of files that can be opened by many different applications, such as music and video files, it is common to find that directories have been set aside for these files in the user’s home directory. The XDG Base Directory Specification describes how these directories are organized.

Some applications rely on finding data files in these standard locations, though they may also allow the user to select files from elsewhere, like traditional applications. These obtain the directory to access via the GLib.get_user_special_dir function, passing one of the Glib.UserDirectory values given in the table below.

Directory Contents
DIRECTORY_DOCUMENTS Documents, such as text or word processing files
DIRECTORY_DOWNLOAD Files downloaded by applications
DIRECTORY_MUSIC Music files
DIRECTORY_PICTURES Pictures and photographs
DIRECTORY_VIDEOS Movies and videos

The photographs and videos taken by the camera are stored in the directories represented by DIRECTORY_PICTURES and DIRECTORY_VIDEOS respectively.

A more complete list of directories that can be accessed is provided in the XDG Base Directory Specification document.

An application distributed as a flatpak needs to declare permissions in the finish-args entry of its manifest to be able to access these directories. The following table shows which permission corresponds to each directory, as described by the table above.

Directory Flatpak Permission
DIRECTORY_DOCUMENTS --xdg-documents
DIRECTORY_DOWNLOAD --xdg-download
DIRECTORY_MUSIC --xdg-music
DIRECTORY_PICTURES --xdg-pictures
DIRECTORY_VIDEOS --xdg-videos

See the Application Permissions for a more complete description of permissions, and consult the Sandbox Permissions section of the Flatpak documentation for a more extensive list of permissions.