Log Files
File System

This contains functional for reading/writing log files. More...

Modules

Types
Log file types.
Macros
Log file specific macros.

Functions

gos_result_t gos_log_file_open (const gos_file_t *file_details, gos_handle_t *handle_ptr, bool must_exist)
Create/open a log file. See Gecko OS Command API documentation: file_open . More...
gos_result_t gos_log_file_append ( gos_handle_t handle, const void *data, uint16_t length)
Append a log record to a previously created/opened log file. More...
gos_result_t gos_log_file_read ( gos_handle_t handle, gos_buffer_t *buffer, int32_t record_id)
Read the specified log record from a log file. More...
gos_result_t gos_log_file_get_stats ( gos_handle_t handle, gos_log_file_stats_t *stats)
Return statistics about a log file. More...

Detailed Description

This contains functional for reading/writing log files.

Function Documentation

◆ gos_log_file_append()

gos_result_t gos_log_file_append ( gos_handle_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 gos_log_file_open() API.

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 gos_log_file_append() call. Once the supplied data is successfully written, the log record's header is set to 'valid'.

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'.
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handle Handle of log file returned by gos_log_file_open()
data Data to write to record of log file
length Size of data to write
Returns
gos_result_t result of API call
Examples:
file/log_file/main.c , and file/log_file_encrypted/main.c .

◆ gos_log_file_get_stats()

gos_result_t gos_log_file_get_stats ( gos_handle_t handle,
gos_log_file_stats_t * stats
)

Return statistics about a log file.

The log file must be opened or created with gos_log_file_open() first.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handle Handle of log file returned by gos_log_file_open()
stats gos_log_file_stats_t Statistics about the log file
Returns
gos_result_t result of API call
Examples:
file/log_file/main.c , and file/log_file_encrypted/main.c .

◆ gos_log_file_open()

gos_result_t gos_log_file_open ( const gos_file_t * file_details,
gos_handle_t * handle_ptr,
bool must_exist
)

Create/open a log file. See Gecko OS 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_details parameter:

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

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

Note
Only the name and location fields of file_details are used if the file already exists.
Using gos_file_read() or gos_file_write() with the handle returned by this API is not allowed.
Parameters
file_details Creation details about the log file if it does not exist, else the name and location of the log file to open
handle_ptr File handle of the created/opened log file
must_exist If true and the file doesn't exist then this call fails
Returns
gos_result_t result of API call
Examples:
file/log_file/main.c , and file/log_file_encrypted/main.c .

◆ gos_log_file_read()

gos_result_t gos_log_file_read ( gos_handle_t handle,
gos_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 gos_file_open() .

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.

Note
If the record_id argument changes, then the previous read position is cleared and subsequent reads start from the beginning of the specified log record.

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

Note
GOS_INVALID_HEADER will be returned if a record_id is specified that is 'invalid'.
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handle Handle of log file returned by gos_log_file_open()
buffer gos_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 GOS_LOG_FILE_GET_NEXT to read sequentially
Returns
gos_result_t result of API call
Examples:
file/log_file/main.c , and file/log_file_encrypted/main.c .