Write a File
113
SWRU455A – February 2017 – Revised March 2017
Copyright © 2017, Texas Instruments Incorporated
File System
8.4.3 Create a File
The open-create or open-create-write creates a new file, and as part of the function the device allocates
the storage for the file. The size of the allocated storage is determined by the maximum size parameter.
The close function makes the opened file valid.
A file created but not closed has allocated storage (according its maximum size), but does not have a
valid copy.
Because the process of creating a file involves updating the file allocation table on the SFLASH, TI
recommends minimizing the creation of files. If it is required to update the file content, open the file for
write rather than to delete and create it.
For a secure file, the default behavior of the file creation function is to generate the file tokens (including
the master): the master token is returned as the function output, and all other tokens can be retrieved
using the sl_FsGetInfo() function. Further information regarding the file tokens can be find in
CC3120/CC3220 SimpleLink Wi-Fi Devices Built-In Security Features
).
The sl_FsOpen() function tests that the file storage can be allocated, that the file does not exist, and that
the creation flags are valid. If in error, the function returns a negative value and represents the error
number; the following is a partial list of errors that might be returned by the creation function:
•
SL_ERROR_FS_NOT_ENOUGH_STORAGE_SPACE, no available storage for the file
•
SL_ERROR_FS_FILE_ALREADY_EXISTS, file with the same name already exists
•
SL_ERROR_FS_NO_AVAILABLE_NV_INDEX, number of opened files exceeded
•
SL_ERROR_FS_FILE_INVALID_FILE_SIZE, the maximum file size is set to 0
The create file input parameters are:
•
Filename: The filename is a string of up to 180 bytes; TI recommends using short filenames (explained
in
); the file name is not case-sensitive.
•
Maximum file size
–
When creating a file, the storage for the file is allocated according the requested maximum file size.
For an existing file, the maximum file size cannot be changed; thus, when defining the maximum
size of a file, the future growth of the file should be considered.
–
Creating a file with the FAILSAFE flag creates the file with a copy, thus the allocated storage size
for the file is doubled.
–
Because the smallest erase unit of a SFLASH is 4096 bytes, the file system allocates storage size,
which is aligned to 4096 bytes.
•
File tokens: The token is the key for accessing a secure file; for a nonsecure file, it is set to zero. The
file creation function returns the file token. By default, the device generates the file master token and
returns it to the host. The default behavior of the token creation can be overridden by special creation
flags.
•
Creation flags: The creation flags are set during the file creation and cannot be changed afterward.
The following is a list of creation flags:
–
SL_FS_CREATE_FAILSAFE: A file opened with failsafe has double copies, but only one copy is
considered to be active at a time. Each time file is opened for write, the file storage is erased. If the
system is powered off while writing a file with no failsafe, the file content is lost. If the system is
powered off while writing a file with failsafe, the old content becomes the active one. Using the
FAILSAFE doubles the file allocated storage. If the bundle feature (used for OTA) is used with the
file, this flag is mandatory.
–
SL_FS_CREATE_SECURE: A file created as secure has its content encrypted on the SFLASH.
Access to the file is limited, and requires a file token. See the security application notes file for
more information about secure files.
–
SL_FS_CREATE_NOSIGNATURE: The flag is relevant only for secure files. By default, a secure
file has a signature, which authenticates the file creator. See the security application notes for more
information about how to create file signature.
–
SL_FS_CREATE_STATIC_TOKEN: Relevant only for secure files. This flag changes the default
behavior of the file tokens creation: with this flag, the file tokens are not changed each time a file is
opened for write.
