Module filesystem

SDL offers an API for examining and manipulating the system’s filesystem. This covers most things one would need to do with directories, except for actual file I/O (which is covered by CategoryIOStream and CategoryAsyncIO instead).

There are functions to answer necessary path questions:

• Where is my app’s data? SDL_GetBasePath().
• Where can I safely write files? SDL_GetPrefPath().
• Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder().
• What is this thing at this location? SDL_GetPathInfo().
• What items live in this folder? SDL_EnumerateDirectory().
• What items live in this folder by wildcard? SDL_GlobDirectory().
• What is my current working directory? SDL_GetCurrentDirectory().

SDL also offers functions to manipulate the directory tree: renaming, removing, copying files.

Structs

SDL_EnumerationResult

Possible results from an enumeration callback.

SDL_Folder

The type of the OS-provided default folder for a specific purpose.

SDL_PathInfo

Information about a path on the filesystem.

SDL_PathType

Types of filesystem entries.

Constants

SDL_ENUM_CONTINUE

Value that requests that enumeration continue.

SDL_ENUM_FAILURE

Value that requests that enumeration stop, as a failure.

SDL_ENUM_SUCCESS

Value that requests that enumeration stop, successfully.

SDL_FOLDER_COUNT

Total number of types in this enum, not a folder type by itself.

SDL_FOLDER_DESKTOP

The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons.

SDL_FOLDER_DOCUMENTS

User document files, possibly application-specific. This is a good place to save a user’s projects.

SDL_FOLDER_DOWNLOADS

Standard folder for user files downloaded from the internet.

SDL_FOLDER_HOME

The folder which contains all of the current user’s data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user’s documents.

SDL_FOLDER_MUSIC

Music files that can be played using a standard music player (mp3, ogg…).

SDL_FOLDER_PICTURES

Image files that can be displayed using a standard viewer (png, jpg…).

SDL_FOLDER_PUBLICSHARE

Files that are meant to be shared with other users on the same computer.

SDL_FOLDER_SAVEDGAMES

Save files for games.

SDL_FOLDER_SCREENSHOTS

Application screenshots.

SDL_FOLDER_TEMPLATES

Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as “New Text File.txt”. Any file in the Templates folder can be used as a starting point for a new file.

SDL_FOLDER_VIDEOS

Video files that can be played using a standard video player (mp4, webm…).

SDL_GLOB_CASEINSENSITIVE

SDL_PATHTYPE_DIRECTORY

a directory

SDL_PATHTYPE_FILE

a normal file

SDL_PATHTYPE_NONE

path does not exist

SDL_PATHTYPE_OTHER

something completely different like a device node (not a symlink, those are always followed)

Functions

SDL_CopyFile^⚠

Copy a file.

SDL_CreateDirectory^⚠

Create a directory, and any missing parent directories.

SDL_EnumerateDirectory^⚠

Enumerate a directory through a callback function.

SDL_GetBasePath^⚠

Get the directory where the application was run from.

SDL_GetCurrentDirectory^⚠

Get what the system believes is the “current working directory.”

SDL_GetPathInfo^⚠

Get information about a filesystem path.

SDL_GetPrefPath^⚠

Get the user-and-app-specific path where files can be written.

SDL_GetUserFolder^⚠

Finds the most suitable user folder for a specific purpose.

SDL_GlobDirectory^⚠

Enumerate a directory tree, filtered by pattern, and return a list.

SDL_RemovePath^⚠

Remove a file or an empty directory.

SDL_RenamePath^⚠

Rename a file or directory.

Type Aliases

SDL_EnumerateDirectoryCallback

Callback for directory enumeration.

SDL_GlobFlags

Flags for path matching.