Returns the names and locations of system-related folders.
# Metadata
Platforms: desktop, server, mobile OS: mac, windows, linux, ios, android, web Introduced: 1.1 Security: disk
# Syntax
the specialFolderPath of folderIdentifier
# Params
- folderIdentifier : A string naming the special folder to locate (e.g. "home") or (on Windows only) a CSIDL value.
# Examples
local tPrefsFolder put specialFolderPath("Preferences") into tPrefsFolder
set the defaultFolder to specialFolderPath("desktop")
local appSupportFolder put specialFolderPath("asup") into appSupportFolder
local tFileContents put url ("file:" \ & specialFolderPath("engine") & slash & "foo.txt" ) into tFileContents
# get file listing of files in a given folder on mouseUp local tMyImages put files(specialFolderPath("resources") & "/myimages") into tMyImages end mouseUp
# Description
Use the specialFolderPath function to place preferences in the Preferences folder, save files to the Documents folder, find out which files are installed in the System or Fonts folders, and so on.
If the folder is not found, the specialFolderPath function returns empty. If the folderIdentifier is either not supported on the current platform or doesn't exist on the current system, the result is set to "folder not found".
Some of the special folders you can specify with the specialFolderPath function need not have the standard names. (For example, the System Folder on Mac OS systems is not necessarily named "System Folder".) For this reason, the specialFolderPath function returns the full path to the folder, including the name of the folder.
**On Windows systems**, the folderIdentifier can alternatively be a Constant Special Item ID List (CSIDL) value that identifies a special folder. Note that not all CSIDL values work on all versions of Windows.
The following folderIdentifier values are supported:
* Windows folder names: * "home": The current user's profile folder * "desktop": The current user's desktop folder * "documents": The current user's "My Documents" folder * "support": The current user's application-specific data ("AppData") folder * "system": The Windows System folder * "start": The folder that contains Start Menu items * "fonts": The folder that contains fonts * "temporary": The folder where temporary files can be placed * "engine": The folder containing the LiveCode engine and the executable files copied in the standalone application * "resources": In development mode, the current stack's folder. In a standalone, the resources folder where files or folders specified in the Standalone Builder are located. Note: A valid resources path is only returned after a stack has been saved.
* Examples of common Windows CSIDL numbers: * 0x001a: Same as "support" * 0x0023: The application-specific data folder shared by all users * 0x000d: The current user's "My Music" folder * 0x000e: The current user's "My Videos" folder * 0x0027: The current user's "My Pictures" folder * 0x000a: The "Recycle Bin".
**On Mac OS systems**, the following folderIdentifier values are supported:
* "home": The current user's home folder * "desktop": The current user's desktop folder * "preferences": The current user's preferences folder * "documents": The current user's documents folder * "support": The current user's application-specific data folder * "system": The System Folder (usually `/System`) * "fonts": The folder that contains fonts * "temporary": The folder where temporary files can be placed * "engine": The folder containing the LiveCode engine and the executable files copied in the standalone application * "resources": In development mode, the current stack's folder. In a standalone application, the resources folder where files or folders specified in the Standalone Builder are located. Note: a valid resources path is only returned after a stack has been saved.
**On iOS systems**, only create files in the "documents", "cache" and "temporary" folders. Be careful not to change or add any files within the application bundle. The application bundle is digitally signed when it is built, and any changes after this point will invalidate the signature and prevent it from launching.
iOS imposes strict controls over what you can and cannot access. Each application in iOS is stored in its own "sandbox" folder (`specialFolderPath("home")`). An application is free to read and write files anywhere beneath this folder, but it is not allowed to access anything outside of the "sandbox".
> *Note:* iOS devices have case-sensitive file systems, but the iOS > simulator's file system has the same case-sensitive > as the host system (i.e. usually case-insensitive).
The following folderIdentifier values are supported:
* "home": The (unique) folder containing the application bundle and its associated data and folders * "documents": The folder in which document data should be stored (backed up by iTunes on sync) * "library": The folder in which to store data of various types (backed up by iTunes on sync). In particular, data private to the application should be stored in a folder named with the application bundle identifier inside the "library" folder * "cache": The folder where transient data that needs to be preserved between launches should be stored (*not* backed up by iTunes) * "temporary": The folder where temporary data that is *not* preserved between launches should be stored (*not* backed up by iTunes) * "engine": The folder containing the built standalone application engine (i.e. the application bundle). This is useful for constructing paths to resources that have been copied into the application bundle at build time * "resources": Same as "engine".
**On Android systems**, note that the file system is case-sensitive.
An Android application is installed on the device as a ZIP package. This means that any assets that are included are not available as separate files in the device's native file system. In order to manage this, LiveCode "virtualizes" the asset files you include, allowing read-only access with all the standard LiveCode file and folder handling commands and functions. To access the assets you have included with your application, use file names relative to `specialFolderPath("engine")`.
The following folderIdentifier values are supported:
* "documents": The folder where application-specific data can be placed (typically valuable) * "cache": The folder where transient application-specific data can be placed (typically not valuable) * "temporary": Same as "cache" * "engine": The (virtual) folder containing the application LiveCode engine and other resources that were copied into the application at build time * "resources": Same as "engine". * "external documents": The folder on the primary shared/external storage device where application-specific data can be placed * "external cache": The folder on the primary shared/external storage device where transient application-specific data can be placed * "external temporary": same as "external cache"
>*Note:* If using any external folderIdentifier values, ensure you > have the 'Write External Storage' permission checked in the > application standalone settings
**On Linux systems**, the following folderIdentifier values are supported:
* "home": The current user's home folder * "desktop": The current user's desktop folder * "temporary": The folder where temporary files can be placed * "engine": The folder containing the LiveCode engine and the executable files copied in the standalone application * "resources": In development mode, the current stack's folder. In a standalone, the resources folder where files or folders specified in the Standalone Builder are located. Note: A valid resources path is only returned after a stack has been saved.
**In Web standalones**, you can read and write files from anywhere, since the whole file system is virtual and temporary. For compatibility purposes, the following folderIdentifier values are supported:
* "home": Always `/livecode` * "fonts": The folder that contains fonts * "temporary": A folder where temporary files can be placed * "engine": The folder where the standalone initial file system is extracted * "resources": The resources folder where files or folders specified in the Standalone Builder are located.
# Tags
# See
- **property:** defaultFolder - **command:** revSetDatabaseDriverPath - **function:** files, folders, tempName, result - **glossary:** application, application bundle, case-insensitive, case-sensitive, constant, engine, folder, platform, return, special folder, standalone application