Rename SDL_GetPath to SDL_GetUserFolder

The documentation has been edited accordingly, and certain parts have been clarified.

include/SDL3/SDL_filesystem.h

@@ -159,11 +159,11 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
  * | SAVEDGAMES  | Vista+  |           |      |            |       |            |
  * | SCREENSHOTS | Vista+  |           |      |            |       |            |
  * | TEMPLATES   | X       | X         |      | X          |       |            |
- * | VIDEOS      | X       | X         |      | X          |       |            |
+ * | VIDEOS      | X       | X*        |      | X          |       |            |
  *
- * Note that on macOS/iOS, the Videos folder is called "Movies".
+ * * Note that on macOS/iOS, the Videos folder is called "Movies".
  *
- * \sa SDL_GetPath
+ * \sa SDL_GetUserFolder
  */
 typedef enum
 {
@@ -206,13 +206,18 @@ typedef enum
 } SDL_Folder;
 
 /**
- * Finds the most suitable OS-provided folder for @p folder, and returns its
+ * Finds the most suitable user folder for @p purpose, and returns its
  * path in OS-specific notation.
  *
  * Many OSes provide certain standard folders for certain purposes, such as
  * storing pictures, music or videos for a certain user. This function gives
  * the path for many of those special locations.
  *
+ * This function is specifically for _user_ folders, which are meant for the
+ * user to access and manage. For application-specific folders, meant to hold
+ * data for the application to manage, see SDL_GetBasePath() and
+ * SDL_GetPrefPath().
+ *
  * Note that the function is expensive, and should be called once at the
  * beginning of the execution and kept for as long as needed.
  *
@@ -229,7 +234,7 @@ typedef enum
  *
  * \sa SDL_Folder
  */
-extern DECLSPEC char *SDLCALL SDL_GetPath(SDL_Folder folder);
+extern DECLSPEC char *SDLCALL SDL_GetUserFolder(SDL_Folder folder);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

src/dynapi/SDL_dynapi.sym

@@ -280,7 +280,7 @@ SDL3_0.0.0 {
     SDL_GetNumTouchFingers;
     SDL_GetNumVideoDrivers;
     SDL_GetOriginalMemoryFunctions;
-    SDL_GetPath;
+    SDL_GetUserFolder;
     SDL_GetPerformanceCounter;
     SDL_GetPerformanceFrequency;
     SDL_GetPixelFormatEnumForMasks;

src/dynapi/SDL_dynapi_overrides.h

@@ -304,7 +304,7 @@
 #define SDL_GetNumTouchFingers SDL_GetNumTouchFingers_REAL
 #define SDL_GetNumVideoDrivers SDL_GetNumVideoDrivers_REAL
 #define SDL_GetOriginalMemoryFunctions SDL_GetOriginalMemoryFunctions_REAL
-#define SDL_GetPath SDL_GetPath_REAL
+#define SDL_GetUserFolder SDL_GetUserFolder_REAL
 #define SDL_GetPerformanceCounter SDL_GetPerformanceCounter_REAL
 #define SDL_GetPerformanceFrequency SDL_GetPerformanceFrequency_REAL
 #define SDL_GetPixelFormatEnumForMasks SDL_GetPixelFormatEnumForMasks_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -379,7 +379,7 @@ SDL_DYNAPI_PROC(int,SDL_GetNumTouchDevices,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetNumTouchFingers,(SDL_TouchID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetNumVideoDrivers,(void),(),return)
 SDL_DYNAPI_PROC(void,SDL_GetOriginalMemoryFunctions,(SDL_malloc_func *a, SDL_calloc_func *b, SDL_realloc_func *c, SDL_free_func *d),(a,b,c,d),)
-SDL_DYNAPI_PROC(char*,SDL_GetPath,(SDL_Folder a),(a),return)
+SDL_DYNAPI_PROC(char*,SDL_GetUserFolder,(SDL_Folder a),(a),return)
 SDL_DYNAPI_PROC(Uint64,SDL_GetPerformanceCounter,(void),(),return)
 SDL_DYNAPI_PROC(Uint64,SDL_GetPerformanceFrequency,(void),(),return)
 SDL_DYNAPI_PROC(Uint32,SDL_GetPixelFormatEnumForMasks,(int a, Uint32 b, Uint32 c, Uint32 d, Uint32 e),(a,b,c,d,e),return)

src/filesystem/android/SDL_sysfilesystem.c

@@ -50,7 +50,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return NULL;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     /* TODO: see https://developer.android.com/reference/android/os/Environment#lfields
        and https://stackoverflow.com/questions/39332085/get-path-to-pictures-directory */

src/filesystem/cocoa/SDL_sysfilesystem.m

@@ -130,7 +130,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     }
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     @autoreleasepool {
 #if TARGET_OS_TV

src/filesystem/dummy/SDL_sysfilesystem.c

@@ -37,7 +37,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return NULL;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/emscripten/SDL_sysfilesystem.c

@@ -83,7 +83,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     const char *home = NULL;
     char *retval;

src/filesystem/haiku/SDL_sysfilesystem.cc

@@ -97,7 +97,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     const char *home = NULL;
     char *retval;

src/filesystem/n3ds/SDL_sysfilesystem.c

@@ -60,7 +60,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/ps2/SDL_sysfilesystem.c

@@ -103,7 +103,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/psp/SDL_sysfilesystem.c

@@ -70,7 +70,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/riscos/SDL_sysfilesystem.c

@@ -200,7 +200,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/unix/SDL_sysfilesystem.c

@@ -517,7 +517,7 @@ static char *xdg_user_dir_lookup (const char *type)
     return NULL;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     const char *param = NULL;
     char *retval;

src/filesystem/vita/SDL_sysfilesystem.c

@@ -84,7 +84,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/windows/SDL_sysfilesystem.c

@@ -177,7 +177,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return retval;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     typedef HRESULT (WINAPI *pfnSHGetKnownFolderPath)(REFGUID /* REFKNOWNFOLDERID */, DWORD, HANDLE, PWSTR*);
     HMODULE lib = LoadLibrary(L"Shell32.dll");
@@ -346,7 +346,7 @@ char *SDL_GetPrefPath(const char *org, const char *app)
     return NULL;
 }
 
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;

src/filesystem/winrt/SDL_sysfilesystem.cpp

@@ -233,7 +233,7 @@ SDL_GetPrefPath(const char *org, const char *app)
 }
 
 /* TODO */
-char *SDL_GetPath(SDL_Folder folder)
+char *SDL_GetUserFolder(SDL_Folder folder)
 {
     SDL_Unsupported();
     return NULL;