File System

This contains all file system related functionality. More...

Modules

Types
File types.
 
Macros
File specific macros.
 

Functions

zos_result_t zn_file_list (zos_file_t **file_linked_list, zos_file_memory_t memory, uint32_t offset, uint32_t limit)
 List files in file system. More...
 
zos_result_t zn_file_list_with_parameters (zos_file_t **file_linked_list, const zos_file_parameters_t *search_parameters)
 List files in file system with parameters. More...
 
zos_result_t zn_file_list_with_callback (zos_file_t **file_linked_list, zos_file_memory_t memory, zos_file_list_callback_t callback, void *user)
 List files in file system with callback. More...
 
zos_result_t zn_file_create (const zos_file_t *file_info, uint32_t *handle)
 Create file on file system. More...
 
zos_result_t zn_file_open (const char *filename, uint32_t *handle_ptr)
 Open file stream for reading. More...
 
zos_result_t zn_file_open_with_decryption (const char *filename, uint32_t *handle_ptr)
 Open user entrypted file for reading. More...
 
zos_result_t zn_file_stat (const char *filename, zos_file_t *file_info)
 Get information about file. More...
 
zos_result_t zn_file_delete (const char *filename)
 Delete file from file system. More...
 
zos_result_t zn_file_write (uint32_t handle, const void *data, uint32_t size)
 Write file data. More...
 
zos_result_t zn_file_read (uint32_t handle, void *data, uint32_t max_size, uint32_t *bytes_read)
 Read file data. More...
 
zos_result_t zn_file_close (uint32_t handle)
 Close file stream. More...
 
zos_result_t zn_file_poll (uint32_t handle, uint32_t *bytes_available)
 Poll file opened for reading to see if there's more data to be read. More...
 
zos_result_t zn_file_destroy_list (zos_file_t *zn_file_list)
 Destroy list of files returned by zn_file_list(), or zn_file_list_with_callback() More...
 
const char * zn_file_get_version_str (char *buffer, uint32_t version, zos_bool_t verbose)
 Convert file version from integer to string representation. More...
 
zos_result_t zn_file_get_version_int (uint32_t *version_ptr, char *buffer)
 Convert file version from string to integer representation. More...
 
zos_result_t zn_file_get_descriptor (uint32_t handle, zos_file_descriptor_t *fd_buffer)
 Return a file descriptor about a file currently opened for reading or writing. More...
 
zos_result_t zn_file_system_get_stats (zos_file_memory_t memory, zos_file_system_stats_t *stats)
 Return statics about the file system. More...
 
zos_result_t zn_log_file_open (const zos_file_t *file_info, uint32_t *handle, zos_bool_t must_exist)
 Create/open a log file. More...
 
zos_result_t zn_log_file_open_with_decryption (const zos_file_t *file_info, uint32_t *handle, zos_bool_t must_exist)
 Create/open a log file with optional encryption/decryption. More...
 
zos_result_t zn_log_file_append (uint32_t handle, const void *data, uint16_t length)
 Append a log record to a previously created/opened log file. More...
 
zos_result_t zn_log_file_read (uint32_t handle, zos_buffer_t *buffer, int32_t record_id)
 Read the specified log record from a log file. More...
 
zos_result_t zn_log_file_get_stats (uint32_t handle, zos_log_stats_t *stats)
 Return statistics about a log file. More...
 

Detailed Description

This contains all file system related functionality.

Function Documentation

zos_result_t zn_file_close ( uint32_t  handle)

Close file stream.

See ZentriOS Command API documentation: stream_close.

If the stream was opened for writing (i.e. zn_file_create() was used) and not all of the specified file size was written then all written data will be lost.

Parameters
[in]handleFile stream handle to close
Returns
zos_result_t result of API call
Examples:
basic/file_encrypt/encrypt.c, basic/json_parser/parse_all_examples.c, basic/json_parser/parse_example1.c, basic/json_parser/parse_example3.c, and basic/log_file/log_file.c.
zos_result_t zn_file_create ( const zos_file_t file_info,
uint32_t *  handle 
)

Create file on file system.

See ZentriOS Command API documentation: file_create {"target":"_blank"}.

This will open a file stream handle for writing. The file will be created with the given information in the zos_file_t file_info. Once this API returns, zn_file_write() must be used to write the specified amount of data in the 'size' member of the zos_file_t argument.

Once the specified amount of file data is written the file is created and the file stream will automatically close.

Note
The checksum member of the zos_file_t argument must be set to UINT32_MAX if NOT used. If the checksum member is less than or equal to UINT16_MAX then the file checksum will be verified before the file is set as valid on the file system. If the checksum does not match then this API call will fail.
If the 'memory_handle` member of the zos_file_t arugment equals:
  • 0 then the file will be created on the bulk flash if available, else extended flash
  • FILE_BULK_HANDLE_FLAG then the file will be created on bulk flash if available, else fail
  • FILE_EXTENDED_HANDLE_FLAG then the file will be created on the extendef flash
Parameters
[in]file_infoInformation amount the file, return to zos_file_t
[out]handleFile stream handle to write
Returns
zos_result_t result of API call
zos_result_t zn_file_delete ( const char *  filename)

Delete file from file system.

See ZentriOS Command API documentation: file_delete.

The filename argument must either be the name of the file on the filesystem or the memory-handle of the file. For instance, if a file is on the extended flash memory at handle 45, the the filename argument would be 'e-45'.

Parameters
[in]filename- Filename or handle of file to delete
Returns
zos_result_t result of API call
zos_result_t zn_file_destroy_list ( zos_file_t zn_file_list)

Destroy list of files returned by zn_file_list(), or zn_file_list_with_callback()

Parameters
zn_file_listList of files to cleanup
Returns
zos_result_t result of API call
Examples:
basic/file_list/file_list.c, and basic/json_parser/parse_all_examples.c.
zos_result_t zn_file_get_descriptor ( uint32_t  handle,
zos_file_descriptor_t fd_buffer 
)

Return a file descriptor about a file currently opened for reading or writing.

A file must have been previously opened using zn_file_open() or zn_file_create()

Parameters
handleThe file handle returned by zn_file_open() or zn_file_create()
fd_bufferBuffer to hold snapshot of file descriptor. zos_file_descriptor_t
Returns
zos_result_t result of API call
zos_result_t zn_file_get_version_int ( uint32_t *  version_ptr,
char *  buffer 
)

Convert file version from string to integer representation.

Parameters
[out]version_ptrPointer to hold file version integer
[in]bufferFile version string
Returns
Result of conversion
const char* zn_file_get_version_str ( char *  buffer,
uint32_t  version,
zos_bool_t  verbose 
)

Convert file version from integer to string representation.

Parameters
[out]bufferBuffer to hold file version string
[in]versionFile version in integer format
[in]verboseAppend release candidate version to string
Returns
Version string (same pointer as 'buffer' argument)
zos_result_t zn_file_list ( zos_file_t **  file_linked_list,
zos_file_memory_t  memory,
uint32_t  offset,
uint32_t  limit 
)

List files in file system.

See ZentriOS Command API documentation: ls {"target":"_blank"}.

This will return a linked list of files in the file system.

Note
zn_file_destroy_list() MUST be called to cleanup the returned file list.
Files are listed by their file 'handle' (i.e. the file's first sector) in increasing order
Parameters
[in]file_linked_listPointer to hold the head of a linked list of files
[in]memory[Optional] zos_file_memory_t memory type to search for files (leave as 0 if unused)
[in]offset[Optional] First sector to begin searching for files to list (leave as 0 if unused)
[in]limit[Optional] Maximum number of results to return (leave as 0 if unused)
Returns
zos_result_t result of API call
zos_result_t zn_file_list_with_callback ( zos_file_t **  file_linked_list,
zos_file_memory_t  memory,
zos_file_list_callback_t  callback,
void *  user 
)

List files in file system with callback.

This will return a linked list of files in the file system. The specified callback zos_file_list_callback_t maybe supplied to optionally limit which files are returned.

Note
zn_file_destroy_list() MUST be called to cleanup the returned file list.
Files are listed by their file 'handle' (i.e. the file's first sector) in increasing order
Parameters
[in]file_linked_list- Pointer to hold head of linked list of files
[in]memory- Optional, zos_file_memory_t memory type to search for files (leave as 0 if unused)
[in]callback- Optional, callback to be called for each found file zos_file_list_callback_t (leave NULL if unused)
[in]user- Optional, argument to be passed to callback (leave NULL if unused)
Returns
zos_result_t result of API call
zos_result_t zn_file_list_with_parameters ( zos_file_t **  file_linked_list,
const zos_file_parameters_t search_parameters 
)

List files in file system with parameters.

This will return a linked list of files in the file system. Search parameters may be optionally specified. Refer to zos_file_parameters_t for more information.

Note
zn_file_destroy_list() MUST be called to cleanup the returned file list.
Files are listed by their file 'handle' (i.e. the file's first sector) in increasing order
Parameters
[in]file_linked_list- Pointer to hold head of linked list of files
[in]search_parameters- Optional, return files only match specified parameters (leave NULL if not used)
Returns
zos_result_t result of API call
zos_result_t zn_file_open ( const char *  filename,
uint32_t *  handle_ptr 
)

Open file stream for reading.

See ZentriOS Command API documentation: file_open {"target":"_blank"}.

This will open the specified filename or filename handle for reading. If the file is found, the handle pointer will contain the file stream handle. zn_file_read() should be used to read the file information.

The filename argument must either be the name of the file on the filesystem or the memory-handle of the file. For instance, if a file is on the extended flash memory at handle 45, the the filename argument would be 'e-45'.

Parameters
[in]filenameFilename or handle of file to open for reading
[out]handle_ptrPointer to contain file stream handle
Returns
zos_result_t result of API call
Examples:
basic/file_encrypt/decrypt.c, basic/json_parser/parse_all_examples.c, basic/json_parser/parse_example1.c, basic/json_parser/parse_example2.c, basic/json_parser/parse_example3.c, and basic/json_parser/parse_example9.c.
zos_result_t zn_file_open_with_decryption ( const char *  filename,
uint32_t *  handle_ptr 
)

Open user entrypted file for reading.

See ZentriOS Command API documentation: file_open.

This API has the exact same functionality as zn_file_open() , except it allows for decrypting user encrypted files on the file system. A user encrypted file is a file that has the FILE_FLAG_USER_ENCRYPTED flag set and is encrypted with a user defines AES key.

If the filename file has the FILE_FLAG_USER_ENCRYPTED flag set and the system.security_key variable is valid, then the file is decrypted as the file is read. If the system.security_key variable is not valid then this API fails.

See ZentriOS variable API documentation: system.security_key {"target":"_blank"}.

Note
If the system.security_key is not valid, a file with the FILE_FLAG_USER_ENCRYPTED flag set can still be read using zn_file_open().
Parameters
filenameFilename or handle of file to open for reading
handle_ptrPointer to contain file stream handle
Returns
zos_result_t result of API call
zos_result_t zn_file_poll ( uint32_t  handle,
uint32_t *  bytes_available 
)

Poll file opened for reading to see if there's more data to be read.

The stream must first be opened with zn_file_open()

Parameters
[in]handleFile stream handle to close
[out]bytes_availablePointer to hold number of bytes remaining to be read
Returns
zos_result_t result of API call
Examples:
basic/json_parser/parse_all_examples.c, basic/json_parser/parse_example1.c, and basic/json_parser/parse_example3.c.
zos_result_t zn_file_read ( uint32_t  handle,
void *  data,
uint32_t  max_size,
uint32_t *  bytes_read 
)

Read file data.

See ZentriOS Command API documentation: stream_read.

zn_file_open() must be called before using this API.

Note
Once all file data has been read the file stream will automatically close.
Parameters
[in]handleReadable file stream handle
[in]dataBuffer to hold read file data
[in]max_sizeSize of 'data' buffer
[out]bytes_readAmount of data actually read
Returns
zos_result_t result of API call
Examples:
basic/file_encrypt/decrypt.c, basic/json_parser/parse_all_examples.c, basic/json_parser/parse_example1.c, basic/json_parser/parse_example2.c, basic/json_parser/parse_example3.c, and basic/json_parser/parse_example9.c.
zos_result_t zn_file_stat ( const char *  filename,
zos_file_t file_info 
)

Get information about file.

See ZentriOS Command API documentation: file_stat.

This populates the supplied zos_file_t with information about a file.

The filename argument must either be the name of the file on the filesystem or the memory-handle of the file. For instance, if a file is on the extended flash memory at handle 45, the the filename argument would be 'e-45'.

Parameters
[in]filename- Filename or handle of file to open for reading
[out]file_info- zos_file_t to be populated with file information
Returns
zos_result_t result of API call
Examples:
basic/file_encrypt/decrypt.c.
zos_result_t zn_file_system_get_stats ( zos_file_memory_t  memory,
zos_file_system_stats_t stats 
)

Return statics about the file system.

This returns statics about a specific file system memory region:

The statistics account for internal file headers, etc.

Parameters
memoryThe flash memory region, FILE_MEMORY_EXTENDED or FILE_MEMORY_BULK
statsBuffer to hold the file system stats
Returns
zos_result_t result of API call
zos_result_t zn_file_write ( uint32_t  handle,
const void *  data,
uint32_t  size 
)

Write file data.

See ZentriOS Command API documentation: stream_write.

zn_file_create() must be called before using this API.

Parameters
[in]handleWritable file stream handle
[in]dataBuffer to file data to write
[in]sizeSize of 'data' buffer
Returns
zos_result_t result of API call
zos_result_t zn_log_file_append ( uint32_t  handle,
const void *  data,
uint16_t  length 
)

Append a log record to a previously created/opened log file.

To use this API, a log file must first be created. This is done using the zn_log_file_open() or zn_file_create() API. The 'flags' member of zos_file_t argument must have the FILE_FLAG_LOG flag set.

Once the log file is created, log records may be appended to the file using this API. One (variable length) log record is appended per zn_log_file_append() call. Once the supplied data is successfully written, the log record's header is set to 'valid'.

This API may also be used with zn_file_open() if the opened file's FILE_FLAG_LOG is set.

Note
If there is an unexpected reboot while log data is being written, then the log record's 'valid' flag won't be set and the record is consider 'invalid'.
Using zn_file_read() or zn_file_write() with this API has undefined behavior.
Parameters
handleHandle of log file returned by zn_log_file_open(), zn_file_create() or zn_file_open()
dataData to write to record of log file
lengthSize of data to write
Returns
zos_result_t result of API call
zos_result_t zn_log_file_get_stats ( uint32_t  handle,
zos_log_stats_t stats 
)

Return statistics about a log file.

The log file must be opened or created with zn_log_file_open(), zn_file_open() or zn_file_create() first.

Note
Using zn_file_read() or zn_file_write() with this API has undefined behavior.
Parameters
handleHandle of log file returned by zn_log_file_open(), zn_file_create() or zn_file_open()
statszos_log_stats_t Statistics about the log file
Returns
zos_result_t result of API call
zos_result_t zn_log_file_open ( const zos_file_t file_info,
uint32_t *  handle,
zos_bool_t  must_exist 
)

Create/open a log file.

See ZentriOS Command API documentation: file_open.

This creates a log file if it doesn't exist otherwise it opens a log file. Only the following members are used in the file_info parameter:

  • name - the name of the log file
  • size - The maximum size of the log file
  • flags - zos_file_flag_t file flags (FILE_FLAG_LOG is automatically set)
  • type - zos_file_type_t file type (leave 0 for default)
  • version - the log file version (leave 0 for default)

Once the file is created/opened, zn_log_file_append() and zn_log_file_read() may be used to write/read the log file.

If the must_exist parameter is ZOS_TRUE and the file doesn't exist then this call will fail.

Note
Only the 'name' member of the file_info parameter is used if the file already exists.
Parameters
file_infoInfo about the log file if it already exists, else the name of the log file to open
handleFile handle of the created/opened log file
must_existIf ZOS_TRUE and the file doesn't exist then this call fails
Returns
zos_result_t result of API call
zos_result_t zn_log_file_open_with_decryption ( const zos_file_t file_info,
uint32_t *  handle,
zos_bool_t  must_exist 
)

Create/open a log file with optional encryption/decryption.

This has the exact same functionality as zn_log_file_open() except it supports opening a user encrypted log file.

If the log file already exists and was created with the FILE_FLAG_USER_ENCRYPTED flag, then this API behaves the exact same as zn_file_open_with_decryption().

If the file doesn't exist, an encrypted log file can be created by setting the FILE_FLAG_USER_ENCRYPTED flag of the supplied zos_file_t parameter.

See zn_file_create() for more info about creating encrypted files.

Parameters
file_infoInfo about the log file if it already exists, else the name of the log file to open
handleFile handle of the created/opened log file
must_existIf ZOS_TRUE and the file doesn't exist then this call fails
Returns
zos_result_t result of API call
zos_result_t zn_log_file_read ( uint32_t  handle,
zos_buffer_t buffer,
int32_t  record_id 
)

Read the specified log record from a log file.

This reads data from a valid log record of a log file. A log file must first be opened or created using zn_file_open(), zn_log_file_open() or zn_file_create().

The record read is specified by the record_id parameter. The record data is read into the supplied buffer up to the maximum size of the buffer parameter. The buffer parameter is updated with the amount of data actually read from the record. If not all the data is read from the current record, subsequent reads will start where the last read left off.

Use ZOS_LOG_GET_NEXT for the record_id parameters to sequentially read from the log file. This call will return ZOS_NOT_FOUND when the specified record_id is not found or no more records are found.

Note
ZOS_INVALID_HEADER will be returned if a record_id is specified that is 'invalid'.
Using zn_file_read() or zn_file_write() with this API has undefined behavior.
Parameters
handleHandle of log file returned by zn_log_file_open(), zn_file_create() or zn_file_open()
bufferzos_buffer_t which contains a pointer to a buffer to hold the log data and the size of the buffer. The size is updated with the amount of data actually read.
record_idThe ID of the log record to read. Use ZOS_LOG_GET_NEXT to read sequentially
Returns
zos_result_t result of API call