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
-
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:
- 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
andlocation
fields offile_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 .