Name
CreateFile -- create a new file (V11.0)
Synopsis
f$ = CreateFile(path$, file$[, table])
Library
dos

Function
This function creates the file specified by file$ in the path specified by path$. This is basically the same as calling OpenFile() with #MODE_WRITE on the file and closing it so you'll essentially get an empty file. The difference is that CreateFile() doesn't accept a single path argument containing both the path and the file specification but two individual arguments specifying the directory where to create the file and the name of the file to be created. It also returns the path to the file just created. All this makes CreateFile() suitable for use with Android's Storage Access Framework (SAF) and with MediaStore on Android which both work a little differently than traditional path specifications. See Working with Android URIs for details.

Note that in contrast to OpenFile(), CreateFile() will fail if the file already exists, except on Android when using the SAF or MediaStore URIs. In that case CreateFile() will never fail if the file already exists. Instead, a counter like (1), (2)... will be appended to the filename. To find out the real filename of the file just created use GetFileAttributes() and the Name table tag.

Note that CreateFile() is very important on Android when using SAF or MediaStore URIs because with those URIs files have to be created first before you can write to them, e.g. when saving a brush to a file using SAF or MediaStore you can't just go ahead and call SaveBrush() but you first have to create the file using CreateFile() and then you can call SaveBrush() on the newly created file. See Working with Android URIs for details.

Just like FullPath(), CreateFile() also supports the following special constants on Android if you need to compose a MediaStore URI:

#MEDIA_DOWNLOADS
The collection of downloaded files in the MediaStore.

#MEDIA_IMAGES
The collection of images in the MediaStore.

#MEDIA_VIDEOS
The collection of videos in the MediaStore.

#MEDIA_MUSIC
The collection of audio files in the MediaStore.

When passing one of these special constants, file$ may contain a single subdirectory which is separated from the actual file using a single slash, e.g. "subdir/file", to refer to a file in a MediaStore subdirectory. Keep in mind, though, that only one nesting level is allowed so there must not be more than one subdirectory in file$. See Working with Android URIs for details.

CreateFile() also accepts an optional table argument which can be used to pass additional parameters. The following table elements are currently recognized:

Adapter:
This tag allows you to specify one or more file adapters that should be asked to create the specified file. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to the adapter set using SetDefaultAdapter(). See Loaders and adapters for details.

UserTags:
This tag can be used to specify additional data that should be passed to file adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details.

MIMEType:
The desired MIME type for the file. This is currently only handled on Android.

Inputs
path$
path for the new file
file$
filename for the new file
table
optional: table containing further parameters
Results
f$
path to the newly created file
Show TOC