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] handle File 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.

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.

Parameters

[in]	`file_info`	Information amount the file, return to zos_file_t
[out]	`handle`	File 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_list List 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

`handle`	The file handle returned by zn_file_open() or zn_file_create()
`fd_buffer`	Buffer 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_ptr`	Pointer to hold file version integer
[in]	`buffer`	File 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]	`buffer`	Buffer to hold file version string
[in]	`version`	File version in integer format
[in]	`verbose`	Append 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.

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_list`	Pointer 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.

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]	`filename`	Filename or handle of file to open for reading
[out]	`handle_ptr`	Pointer 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.

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

`filename`	Filename or handle of file to open for reading
`handle_ptr`	Pointer 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]	`handle`	File stream handle to close
[out]	`bytes_available`	Pointer 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]	`handle`	Readable file stream handle
[in]	`data`	Buffer to hold read file data
[in]	`max_size`	Size of 'data' buffer
[out]	`bytes_read`	Amount 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

`memory`	The flash memory region, FILE_MEMORY_EXTENDED or FILE_MEMORY_BULK
`stats`	Buffer 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]	`handle`	Writable file stream handle
[in]	`data`	Buffer to file data to write
[in]	`size`	Size 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

`handle`	Handle of log file returned by zn_log_file_open(), zn_file_create() or zn_file_open()
`data`	Data to write to record of log file
`length`	Size 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

`handle`	Handle of log file returned by zn_log_file_open(), zn_file_create() or zn_file_open()
`stats`	zos_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_info`	Info about the log file if it already exists, else the name of the log file to open
`handle`	File handle of the created/opened log file
`must_exist`	If 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_info`	Info about the log file if it already exists, else the name of the log file to open
`handle`	File handle of the created/opened log file
`must_exist`	If 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

`handle`	Handle of log file returned by zn_log_file_open(), zn_file_create() or zn_file_open()
`buffer`	zos_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_id`	The ID of the log record to read. Use ZOS_LOG_GET_NEXT to read sequentially

Returns: zos_result_t result of API call

File System

Modules

Functions

Detailed Description

Function Documentation