|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryFilesystem
|
|
|
24 *
|
|
|
25 * SDL offers an API for examining and manipulating the system's filesystem.
|
|
|
26 * This covers most things one would need to do with directories, except for
|
|
|
27 * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream)
|
|
|
28 * and [CategoryAsyncIO](CategoryAsyncIO) instead).
|
|
|
29 *
|
|
|
30 * There are functions to answer necessary path questions:
|
|
|
31 *
|
|
|
32 * - Where is my app's data? SDL_GetBasePath().
|
|
|
33 * - Where can I safely write files? SDL_GetPrefPath().
|
|
|
34 * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder().
|
|
|
35 * - What is this thing at this location? SDL_GetPathInfo().
|
|
|
36 * - What items live in this folder? SDL_EnumerateDirectory().
|
|
|
37 * - What items live in this folder by wildcard? SDL_GlobDirectory().
|
|
|
38 * - What is my current working directory? SDL_GetCurrentDirectory().
|
|
|
39 *
|
|
|
40 * SDL also offers functions to manipulate the directory tree: renaming,
|
|
|
41 * removing, copying files.
|
|
|
42 */
|
|
|
43
|
|
|
44 #ifndef SDL_filesystem_h_
|
|
|
45 #define SDL_filesystem_h_
|
|
|
46
|
|
|
47 #include <SDL3/SDL_stdinc.h>
|
|
|
48 #include <SDL3/SDL_error.h>
|
|
|
49
|
|
|
50 #include <SDL3/SDL_begin_code.h>
|
|
|
51
|
|
|
52 /* Set up for C function definitions, even when using C++ */
|
|
|
53 #ifdef __cplusplus
|
|
|
54 extern "C" {
|
|
|
55 #endif
|
|
|
56
|
|
|
57 /**
|
|
|
58 * Get the directory where the application was run from.
|
|
|
59 *
|
|
|
60 * SDL caches the result of this call internally, but the first call to this
|
|
|
61 * function is not necessarily fast, so plan accordingly.
|
|
|
62 *
|
|
|
63 * **macOS and iOS Specific Functionality**: If the application is in a ".app"
|
|
|
64 * bundle, this function returns the Resource directory (e.g.
|
|
|
65 * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding
|
|
|
66 * a property to the Info.plist file. Adding a string key with the name
|
|
|
67 * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the
|
|
|
68 * behaviour.
|
|
|
69 *
|
|
|
70 * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
|
|
|
71 * application in /Applications/SDLApp/MyApp.app):
|
|
|
72 *
|
|
|
73 * - `resource`: bundle resource directory (the default). For example:
|
|
|
74 * `/Applications/SDLApp/MyApp.app/Contents/Resources`
|
|
|
75 * - `bundle`: the Bundle directory. For example:
|
|
|
76 * `/Applications/SDLApp/MyApp.app/`
|
|
|
77 * - `parent`: the containing directory of the bundle. For example:
|
|
|
78 * `/Applications/SDLApp/`
|
|
|
79 *
|
|
|
80 * **Android Specific Functionality**: This function returns "./", which
|
|
|
81 * allows filesystem operations to use internal storage and the asset system.
|
|
|
82 *
|
|
|
83 * **Nintendo 3DS Specific Functionality**: This function returns "romfs"
|
|
|
84 * directory of the application as it is uncommon to store resources outside
|
|
|
85 * the executable. As such it is not a writable directory.
|
|
|
86 *
|
|
|
87 * The returned path is guaranteed to end with a path separator ('\\' on
|
|
|
88 * Windows, '/' on most other platforms).
|
|
|
89 *
|
|
|
90 * \returns an absolute path in UTF-8 encoding to the application data
|
|
|
91 * directory. NULL will be returned on error or when the platform
|
|
|
92 * doesn't implement this functionality, call SDL_GetError() for more
|
|
|
93 * information.
|
|
|
94 *
|
|
|
95 * \threadsafety It is safe to call this function from any thread.
|
|
|
96 *
|
|
|
97 * \since This function is available since SDL 3.2.0.
|
|
|
98 *
|
|
|
99 * \sa SDL_GetPrefPath
|
|
|
100 */
|
|
|
101 extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void);
|
|
|
102
|
|
|
103 /**
|
|
|
104 * Get the user-and-app-specific path where files can be written.
|
|
|
105 *
|
|
|
106 * Get the "pref dir". This is meant to be where users can write personal
|
|
|
107 * files (preferences and save games, etc) that are specific to your
|
|
|
108 * application. This directory is unique per user, per application.
|
|
|
109 *
|
|
|
110 * This function will decide the appropriate location in the native
|
|
|
111 * filesystem, create the directory if necessary, and return a string of the
|
|
|
112 * absolute path to the directory in UTF-8 encoding.
|
|
|
113 *
|
|
|
114 * On Windows, the string might look like:
|
|
|
115 *
|
|
|
116 * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
|
|
|
117 *
|
|
|
118 * On Linux, the string might look like:
|
|
|
119 *
|
|
|
120 * `/home/bob/.local/share/My Program Name/`
|
|
|
121 *
|
|
|
122 * On macOS, the string might look like:
|
|
|
123 *
|
|
|
124 * `/Users/bob/Library/Application Support/My Program Name/`
|
|
|
125 *
|
|
|
126 * You should assume the path returned by this function is the only safe place
|
|
|
127 * to write files (and that SDL_GetBasePath(), while it might be writable, or
|
|
|
128 * even the parent of the returned path, isn't where you should be writing
|
|
|
129 * things).
|
|
|
130 *
|
|
|
131 * Both the org and app strings may become part of a directory name, so please
|
|
|
132 * follow these rules:
|
|
|
133 *
|
|
|
134 * - Try to use the same org string (_including case-sensitivity_) for all
|
|
|
135 * your applications that use this function.
|
|
|
136 * - Always use a unique app string for each one, and make sure it never
|
|
|
137 * changes for an app once you've decided on it.
|
|
|
138 * - Unicode characters are legal, as long as they are UTF-8 encoded, but...
|
|
|
139 * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
|
|
|
140 * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
|
|
|
141 *
|
|
|
142 * Due to historical mistakes, `org` is allowed to be NULL or "". In such
|
|
|
143 * cases, SDL will omit the org subdirectory, including on platforms where it
|
|
|
144 * shouldn't, and including on platforms where this would make your app fail
|
|
|
145 * certification for an app store. New apps should definitely specify a real
|
|
|
146 * string for `org`.
|
|
|
147 *
|
|
|
148 * The returned path is guaranteed to end with a path separator ('\\' on
|
|
|
149 * Windows, '/' on most other platforms).
|
|
|
150 *
|
|
|
151 * \param org the name of your organization.
|
|
|
152 * \param app the name of your application.
|
|
|
153 * \returns a UTF-8 string of the user directory in platform-dependent
|
|
|
154 * notation. NULL if there's a problem (creating directory failed,
|
|
|
155 * etc.). This should be freed with SDL_free() when it is no longer
|
|
|
156 * needed.
|
|
|
157 *
|
|
|
158 * \threadsafety It is safe to call this function from any thread.
|
|
|
159 *
|
|
|
160 * \since This function is available since SDL 3.2.0.
|
|
|
161 *
|
|
|
162 * \sa SDL_GetBasePath
|
|
|
163 */
|
|
|
164 extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char *app);
|
|
|
165
|
|
|
166 /**
|
|
|
167 * The type of the OS-provided default folder for a specific purpose.
|
|
|
168 *
|
|
|
169 * Note that the Trash folder isn't included here, because trashing files
|
|
|
170 * usually involves extra OS-specific functionality to remember the file's
|
|
|
171 * original location.
|
|
|
172 *
|
|
|
173 * The folders supported per platform are:
|
|
|
174 *
|
|
|
175 * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten |
|
|
|
176 * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- |
|
|
|
177 * | HOME | X | X | | X | X | X |
|
|
|
178 * | DESKTOP | X | X | | X | X | |
|
|
|
179 * | DOCUMENTS | X | X | | X | | |
|
|
|
180 * | DOWNLOADS | Vista+ | X | | X | | |
|
|
|
181 * | MUSIC | X | X | | X | | |
|
|
|
182 * | PICTURES | X | X | | X | | |
|
|
|
183 * | PUBLICSHARE | | X | | X | | |
|
|
|
184 * | SAVEDGAMES | Vista+ | | | | | |
|
|
|
185 * | SCREENSHOTS | Vista+ | | | | | |
|
|
|
186 * | TEMPLATES | X | X | | X | | |
|
|
|
187 * | VIDEOS | X | X* | | X | | |
|
|
|
188 *
|
|
|
189 * Note that on macOS/iOS, the Videos folder is called "Movies".
|
|
|
190 *
|
|
|
191 * \since This enum is available since SDL 3.2.0.
|
|
|
192 *
|
|
|
193 * \sa SDL_GetUserFolder
|
|
|
194 */
|
|
|
195 typedef enum SDL_Folder
|
|
|
196 {
|
|
|
197 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. */
|
|
|
198 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. */
|
|
|
199 SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */
|
|
|
200 SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */
|
|
|
201 SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */
|
|
|
202 SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */
|
|
|
203 SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */
|
|
|
204 SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */
|
|
|
205 SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */
|
|
|
206 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. */
|
|
|
207 SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */
|
|
|
208 SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */
|
|
|
209 } SDL_Folder;
|
|
|
210
|
|
|
211 /**
|
|
|
212 * Finds the most suitable user folder for a specific purpose.
|
|
|
213 *
|
|
|
214 * Many OSes provide certain standard folders for certain purposes, such as
|
|
|
215 * storing pictures, music or videos for a certain user. This function gives
|
|
|
216 * the path for many of those special locations.
|
|
|
217 *
|
|
|
218 * This function is specifically for _user_ folders, which are meant for the
|
|
|
219 * user to access and manage. For application-specific folders, meant to hold
|
|
|
220 * data for the application to manage, see SDL_GetBasePath() and
|
|
|
221 * SDL_GetPrefPath().
|
|
|
222 *
|
|
|
223 * The returned path is guaranteed to end with a path separator ('\\' on
|
|
|
224 * Windows, '/' on most other platforms).
|
|
|
225 *
|
|
|
226 * If NULL is returned, the error may be obtained with SDL_GetError().
|
|
|
227 *
|
|
|
228 * \param folder the type of folder to find.
|
|
|
229 * \returns either a null-terminated C string containing the full path to the
|
|
|
230 * folder, or NULL if an error happened.
|
|
|
231 *
|
|
|
232 * \threadsafety It is safe to call this function from any thread.
|
|
|
233 *
|
|
|
234 * \since This function is available since SDL 3.2.0.
|
|
|
235 */
|
|
|
236 extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder);
|
|
|
237
|
|
|
238
|
|
|
239 /* Abstract filesystem interface */
|
|
|
240
|
|
|
241 /**
|
|
|
242 * Types of filesystem entries.
|
|
|
243 *
|
|
|
244 * Note that there may be other sorts of items on a filesystem: devices,
|
|
|
245 * symlinks, named pipes, etc. They are currently reported as
|
|
|
246 * SDL_PATHTYPE_OTHER.
|
|
|
247 *
|
|
|
248 * \since This enum is available since SDL 3.2.0.
|
|
|
249 *
|
|
|
250 * \sa SDL_PathInfo
|
|
|
251 */
|
|
|
252 typedef enum SDL_PathType
|
|
|
253 {
|
|
|
254 SDL_PATHTYPE_NONE, /**< path does not exist */
|
|
|
255 SDL_PATHTYPE_FILE, /**< a normal file */
|
|
|
256 SDL_PATHTYPE_DIRECTORY, /**< a directory */
|
|
|
257 SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */
|
|
|
258 } SDL_PathType;
|
|
|
259
|
|
|
260 /**
|
|
|
261 * Information about a path on the filesystem.
|
|
|
262 *
|
|
|
263 * \since This datatype is available since SDL 3.2.0.
|
|
|
264 *
|
|
|
265 * \sa SDL_GetPathInfo
|
|
|
266 * \sa SDL_GetStoragePathInfo
|
|
|
267 */
|
|
|
268 typedef struct SDL_PathInfo
|
|
|
269 {
|
|
|
270 SDL_PathType type; /**< the path type */
|
|
|
271 Uint64 size; /**< the file size in bytes */
|
|
|
272 SDL_Time create_time; /**< the time when the path was created */
|
|
|
273 SDL_Time modify_time; /**< the last time the path was modified */
|
|
|
274 SDL_Time access_time; /**< the last time the path was read */
|
|
|
275 } SDL_PathInfo;
|
|
|
276
|
|
|
277 /**
|
|
|
278 * Flags for path matching.
|
|
|
279 *
|
|
|
280 * \since This datatype is available since SDL 3.2.0.
|
|
|
281 *
|
|
|
282 * \sa SDL_GlobDirectory
|
|
|
283 * \sa SDL_GlobStorageDirectory
|
|
|
284 */
|
|
|
285 typedef Uint32 SDL_GlobFlags;
|
|
|
286
|
|
|
287 #define SDL_GLOB_CASEINSENSITIVE (1u << 0)
|
|
|
288
|
|
|
289 /**
|
|
|
290 * Create a directory, and any missing parent directories.
|
|
|
291 *
|
|
|
292 * This reports success if `path` already exists as a directory.
|
|
|
293 *
|
|
|
294 * If parent directories are missing, it will also create them. Note that if
|
|
|
295 * this fails, it will not remove any parent directories it already made.
|
|
|
296 *
|
|
|
297 * \param path the path of the directory to create.
|
|
|
298 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
299 * information.
|
|
|
300 *
|
|
|
301 * \threadsafety It is safe to call this function from any thread.
|
|
|
302 *
|
|
|
303 * \since This function is available since SDL 3.2.0.
|
|
|
304 */
|
|
|
305 extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path);
|
|
|
306
|
|
|
307 /**
|
|
|
308 * Possible results from an enumeration callback.
|
|
|
309 *
|
|
|
310 * \since This enum is available since SDL 3.2.0.
|
|
|
311 *
|
|
|
312 * \sa SDL_EnumerateDirectoryCallback
|
|
|
313 */
|
|
|
314 typedef enum SDL_EnumerationResult
|
|
|
315 {
|
|
|
316 SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */
|
|
|
317 SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */
|
|
|
318 SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */
|
|
|
319 } SDL_EnumerationResult;
|
|
|
320
|
|
|
321 /**
|
|
|
322 * Callback for directory enumeration.
|
|
|
323 *
|
|
|
324 * Enumeration of directory entries will continue until either all entries
|
|
|
325 * have been provided to the callback, or the callback has requested a stop
|
|
|
326 * through its return value.
|
|
|
327 *
|
|
|
328 * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the
|
|
|
329 * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will
|
|
|
330 * terminate the enumeration early, and dictate the return value of the
|
|
|
331 * enumeration function itself.
|
|
|
332 *
|
|
|
333 * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/'
|
|
|
334 * on most other platforms).
|
|
|
335 *
|
|
|
336 * \param userdata an app-controlled pointer that is passed to the callback.
|
|
|
337 * \param dirname the directory that is being enumerated.
|
|
|
338 * \param fname the next entry in the enumeration.
|
|
|
339 * \returns how the enumeration should proceed.
|
|
|
340 *
|
|
|
341 * \since This datatype is available since SDL 3.2.0.
|
|
|
342 *
|
|
|
343 * \sa SDL_EnumerateDirectory
|
|
|
344 */
|
|
|
345 typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname);
|
|
|
346
|
|
|
347 /**
|
|
|
348 * Enumerate a directory through a callback function.
|
|
|
349 *
|
|
|
350 * This function provides every directory entry through an app-provided
|
|
|
351 * callback, called once for each directory entry, until all results have been
|
|
|
352 * provided or the callback returns either SDL_ENUM_SUCCESS or
|
|
|
353 * SDL_ENUM_FAILURE.
|
|
|
354 *
|
|
|
355 * This will return false if there was a system problem in general, or if a
|
|
|
356 * callback returns SDL_ENUM_FAILURE. A successful return means a callback
|
|
|
357 * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries
|
|
|
358 * were enumerated.
|
|
|
359 *
|
|
|
360 * \param path the path of the directory to enumerate.
|
|
|
361 * \param callback a function that is called for each entry in the directory.
|
|
|
362 * \param userdata a pointer that is passed to `callback`.
|
|
|
363 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
364 * information.
|
|
|
365 *
|
|
|
366 * \threadsafety It is safe to call this function from any thread.
|
|
|
367 *
|
|
|
368 * \since This function is available since SDL 3.2.0.
|
|
|
369 */
|
|
|
370 extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata);
|
|
|
371
|
|
|
372 /**
|
|
|
373 * Remove a file or an empty directory.
|
|
|
374 *
|
|
|
375 * Directories that are not empty will fail; this function will not recursely
|
|
|
376 * delete directory trees.
|
|
|
377 *
|
|
|
378 * \param path the path to remove from the filesystem.
|
|
|
379 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
380 * information.
|
|
|
381 *
|
|
|
382 * \threadsafety It is safe to call this function from any thread.
|
|
|
383 *
|
|
|
384 * \since This function is available since SDL 3.2.0.
|
|
|
385 */
|
|
|
386 extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path);
|
|
|
387
|
|
|
388 /**
|
|
|
389 * Rename a file or directory.
|
|
|
390 *
|
|
|
391 * If the file at `newpath` already exists, it will be replaced.
|
|
|
392 *
|
|
|
393 * Note that this will not copy files across filesystems/drives/volumes, as
|
|
|
394 * that is a much more complicated (and possibly time-consuming) operation.
|
|
|
395 *
|
|
|
396 * Which is to say, if this function fails, SDL_CopyFile() to a temporary file
|
|
|
397 * in the same directory as `newpath`, then SDL_RenamePath() from the
|
|
|
398 * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work
|
|
|
399 * for files. Renaming a non-empty directory across filesystems is
|
|
|
400 * dramatically more complex, however.
|
|
|
401 *
|
|
|
402 * \param oldpath the old path.
|
|
|
403 * \param newpath the new path.
|
|
|
404 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
405 * information.
|
|
|
406 *
|
|
|
407 * \threadsafety It is safe to call this function from any thread.
|
|
|
408 *
|
|
|
409 * \since This function is available since SDL 3.2.0.
|
|
|
410 */
|
|
|
411 extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath);
|
|
|
412
|
|
|
413 /**
|
|
|
414 * Copy a file.
|
|
|
415 *
|
|
|
416 * If the file at `newpath` already exists, it will be overwritten with the
|
|
|
417 * contents of the file at `oldpath`.
|
|
|
418 *
|
|
|
419 * This function will block until the copy is complete, which might be a
|
|
|
420 * significant time for large files on slow disks. On some platforms, the copy
|
|
|
421 * can be handed off to the OS itself, but on others SDL might just open both
|
|
|
422 * paths, and read from one and write to the other.
|
|
|
423 *
|
|
|
424 * Note that this is not an atomic operation! If something tries to read from
|
|
|
425 * `newpath` while the copy is in progress, it will see an incomplete copy of
|
|
|
426 * the data, and if the calling thread terminates (or the power goes out)
|
|
|
427 * during the copy, `newpath`'s previous contents will be gone, replaced with
|
|
|
428 * an incomplete copy of the data. To avoid this risk, it is recommended that
|
|
|
429 * the app copy to a temporary file in the same directory as `newpath`, and if
|
|
|
430 * the copy is successful, use SDL_RenamePath() to replace `newpath` with the
|
|
|
431 * temporary file. This will ensure that reads of `newpath` will either see a
|
|
|
432 * complete copy of the data, or it will see the pre-copy state of `newpath`.
|
|
|
433 *
|
|
|
434 * This function attempts to synchronize the newly-copied data to disk before
|
|
|
435 * returning, if the platform allows it, so that the renaming trick will not
|
|
|
436 * have a problem in a system crash or power failure, where the file could be
|
|
|
437 * renamed but the contents never made it from the system file cache to the
|
|
|
438 * physical disk.
|
|
|
439 *
|
|
|
440 * If the copy fails for any reason, the state of `newpath` is undefined. It
|
|
|
441 * might be half a copy, it might be the untouched data of what was already
|
|
|
442 * there, or it might be a zero-byte file, etc.
|
|
|
443 *
|
|
|
444 * \param oldpath the old path.
|
|
|
445 * \param newpath the new path.
|
|
|
446 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
447 * information.
|
|
|
448 *
|
|
|
449 * \threadsafety It is safe to call this function from any thread, but this
|
|
|
450 * operation is not atomic, so the app might need to protect
|
|
|
451 * access to specific paths from other threads if appropriate.
|
|
|
452 *
|
|
|
453 * \since This function is available since SDL 3.2.0.
|
|
|
454 */
|
|
|
455 extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath);
|
|
|
456
|
|
|
457 /**
|
|
|
458 * Get information about a filesystem path.
|
|
|
459 *
|
|
|
460 * \param path the path to query.
|
|
|
461 * \param info a pointer filled in with information about the path, or NULL to
|
|
|
462 * check for the existence of a file.
|
|
|
463 * \returns true on success or false if the file doesn't exist, or another
|
|
|
464 * failure; call SDL_GetError() for more information.
|
|
|
465 *
|
|
|
466 * \threadsafety It is safe to call this function from any thread.
|
|
|
467 *
|
|
|
468 * \since This function is available since SDL 3.2.0.
|
|
|
469 */
|
|
|
470 extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info);
|
|
|
471
|
|
|
472 /**
|
|
|
473 * Enumerate a directory tree, filtered by pattern, and return a list.
|
|
|
474 *
|
|
|
475 * Files are filtered out if they don't match the string in `pattern`, which
|
|
|
476 * may contain wildcard characters `*` (match everything) and `?` (match one
|
|
|
477 * character). If pattern is NULL, no filtering is done and all results are
|
|
|
478 * returned. Subdirectories are permitted, and are specified with a path
|
|
|
479 * separator of `/`. Wildcard characters `*` and `?` never match a path
|
|
|
480 * separator.
|
|
|
481 *
|
|
|
482 * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching
|
|
|
483 * case-insensitive.
|
|
|
484 *
|
|
|
485 * The returned array is always NULL-terminated, for your iterating
|
|
|
486 * convenience, but if `count` is non-NULL, on return it will contain the
|
|
|
487 * number of items in the array, not counting the NULL terminator.
|
|
|
488 *
|
|
|
489 * \param path the path of the directory to enumerate.
|
|
|
490 * \param pattern the pattern that files in the directory must match. Can be
|
|
|
491 * NULL.
|
|
|
492 * \param flags `SDL_GLOB_*` bitflags that affect this search.
|
|
|
493 * \param count on return, will be set to the number of items in the returned
|
|
|
494 * array. Can be NULL.
|
|
|
495 * \returns an array of strings on success or NULL on failure; call
|
|
|
496 * SDL_GetError() for more information. This is a single allocation
|
|
|
497 * that should be freed with SDL_free() when it is no longer needed.
|
|
|
498 *
|
|
|
499 * \threadsafety It is safe to call this function from any thread.
|
|
|
500 *
|
|
|
501 * \since This function is available since SDL 3.2.0.
|
|
|
502 */
|
|
|
503 extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
|
|
|
504
|
|
|
505 /**
|
|
|
506 * Get what the system believes is the "current working directory."
|
|
|
507 *
|
|
|
508 * For systems without a concept of a current working directory, this will
|
|
|
509 * still attempt to provide something reasonable.
|
|
|
510 *
|
|
|
511 * SDL does not provide a means to _change_ the current working directory; for
|
|
|
512 * platforms without this concept, this would cause surprises with file access
|
|
|
513 * outside of SDL.
|
|
|
514 *
|
|
|
515 * The returned path is guaranteed to end with a path separator ('\\' on
|
|
|
516 * Windows, '/' on most other platforms).
|
|
|
517 *
|
|
|
518 * \returns a UTF-8 string of the current working directory in
|
|
|
519 * platform-dependent notation. NULL if there's a problem. This
|
|
|
520 * should be freed with SDL_free() when it is no longer needed.
|
|
|
521 *
|
|
|
522 * \threadsafety It is safe to call this function from any thread.
|
|
|
523 *
|
|
|
524 * \since This function is available since SDL 3.2.0.
|
|
|
525 */
|
|
|
526 extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void);
|
|
|
527
|
|
|
528 /* Ends C function definitions when using C++ */
|
|
|
529 #ifdef __cplusplus
|
|
|
530 }
|
|
|
531 #endif
|
|
|
532 #include <SDL3/SDL_close_code.h>
|
|
|
533
|
|
|
534 #endif /* SDL_filesystem_h_ */
|
