Log Files

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
handleHandle of log file returned by gos_log_file_open()
dataData to write to record of log file
lengthSize 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
handleHandle of log file returned by gos_log_file_open()
statsgos_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:

  • name - The name of the log file
  • size - The maximum size of the log file
  • flags - Only GOS_FILE_FLAG_ESSENTIAL is used
  • version - The log file version, leave 0 for default
  • owner - The file's owner, see gos_file_owner_t, leave 0 for default
  • permissions - The file's permissions, see gos_file_permission_t, leave 0 for default
  • location - The file's location, see gos_file_location_t, leave 0 for default

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_detailsCreation details about the log file if it does not exist, else the name and location of the log file to open
handle_ptrFile handle of the created/opened log file
must_existIf 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
handleHandle of log file returned by gos_log_file_open()
buffergos_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 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.