get-folder-path Function

Summary

Gets the path of a special folder.

Package

system

Signature

get-folder-path what &key create => result

Arguments

what⇩	A keyword.
create⇩	A boolean.

Values

result⇩

A directory pathname naming the path, or nil.

Description

The function get-folder-path obtains the current value for various special folders often used by applications. It is useful because these paths may differ between versions of the operating system. get-folder-path is implemented all platforms, using system APIs on Microsoft Windows, macOS, iOS and Android.

On platforms other than Windows, macOS, iOS and Android it is a dummy function, which makes a path to a directory inside the user's home directory that looks like <homedir>/get-folder-path/<symbol-name-downcased>. This allows testing code that uses get-folder-path to work in the sense that files can be written and read from these directories.

what indicates the purpose of the special folder. For instance, :common-appdata means the folder containing application data for all users.

The following values of what are recognized on Microsoft Windows, macOS and iOS:

:appdata, :documents, :my-documents and :local-appdata.

:documents is an alias for :my-documents.

The following values of what are recognized on Microsoft Windows, macOS:

:common-appdata and :common-documents.

The following values are recognized on Microsoft Windows only: :program-files, :programs and :common-programs.

The following values are recognized on macOS and iOS only:

:my-library, :my-appsupport, :my-preferences, :my-caches and :my-logs.

The following values are recognized on macOS only:

:common-library, :common-appsupport, :common-preferences, :common-caches, :common-logs, :system-library.

On macOS and iOS, :appdata is an alias for :my-appsupport, :common-appdata is an alias for :common-appsupport, and :local-appdata is an alias for :common-appsupport.

If the folder does not exist and create is true, the folder is created. If the folder does not exist and create is false, result is nil. The default value of create is false.

The following values of what are recognized on Android:

:appdata, :local-appdata
	Both of these return the same directory. It is the directory which is returned by the getFilesDir on the application context. Note that this is a private directory, not visible to other applications.
:my-documents, :documents
	On Android 4.4 and later this returns the "documents" directory in the "public external" directory (the result of calling android.os.Environment.getExternalStoragePublicDirectory with the value of android.os.Environment.DIRECTORY_DOCUMENTS). In previous versions it uses the "downloads" directory, because there does not seem to be another useful place for it. Note: This is used as the home directory on Android, that is what cl:user-homedir-pathname returns.
:alarms, :dcim, :downloads, :movies, :music, :notifications, :pictures, :podcasts, :ringtones
	Return the matching directory in the "public external" directory. This is the result of calling android.os.Environment.getExternalStoragePublicDirectory with the value of android.os.Environment.DIRECTORY_name, where name is the symbol name of what, for example android.os.Environment.DIRECTORY_RINGTONES.
:common-appdata	Returns the external storage directory of the application if it is accessible, otherwise returns nil. The external storage directory is the result of calling getExternalFilesDir on the application context with null. Note that the application will need permission to access the external storage, by having uses-permission android.permission.WRITE_EXTERNAL_STORAGE or android.permission.READ_EXTERNAL_STORAGE in the AndroidManifest.xml file.

Compatibility notes

1. In LispWorks 6.1 and earlier versions, get-folder-path is implemented only on Windows and macOS.
2. In LispWorks 5.0 and previous versions, get-folder-path returns a string.

Examples

This form constructs a pathname to a file foo.lisp in the user's documents directory:

(make-pathname 
 :name "foo" 
 :type "lisp" 
 :defaults
 (sys:get-folder-path :my-documents))

See also

get-user-profile-directory