## Receiving logs
-In order to receive logs, you have to use the dlogutil_get_log() function repeatedly. In order to call it, you need to pass a state struct (#dlogutil_state_s). You can get it by using one of the dlogutil_prepare_continuous(), dlogutil_prepare_monitor(), and dlogutil_prepare_dump() functions.
+In order to receive logs, you have to use the dlogutil_get_log() function repeatedly. In order to call it, you need to pass a state struct (#dlogutil_state_s). You can get it by first configuring the library using the config struct (#dlogutil_config_s) and then calling the dlogutil_config_connect() function.
-The difference between the three functions is that dlogutil_prepare_monitor() is meant to monitor the buffer for fresh logs without terminating, dlogutil_prepare_dump() dumps the current logs and quits, and dlogutil_prepare_continuous() combines the two - it returns everything in the buffer and waits for more.
+In order to receive the logs, you have to choose one of three modes: dlogutil_config_mode_set_monitor() is meant to monitor the buffer for fresh logs without terminating, dlogutil_config_mode_set_dump() dumps the current logs and quits, and dlogutil_config_mode_set_continuous() combines the two - it returns everything in the buffer and waits for more. If you set no mode, you will be unable to receive logs, but will still be able to fetch information about the buffers.
-One possible issue to be aware of is that reading timestamp data in dlog is nontrivial. In particular, the data might be missing, and the functions will return the special missing value. You can, however, avoid this, by using the dlogutil_get_traits() function. It allows you to receive information about a buffer; in particular, which timestamps are guaranteed to be available, and which timestamp is the default one (which not only is guaranteed to be available, but also is considered by dlog as the best possible representation of the true log sending time).
+One possible issue to be aware of is that reading timestamp data in dlog is nontrivial. In particular, the data might be missing, and the functions will return the special missing value. You can, however, avoid this, by using the dlogutil_buffer_* functions. They allow you to receive information about a buffer; in particular, which timestamps are guaranteed to be available, and which timestamp is the default one (which not only is guaranteed to be available, but also is considered by dlog as the best possible representation of the true log sending time). Some of the functions require #dlogutil_state_s to be passed, while others don't.
-While receiving logs, you can decide to also sort or filter them. These can be configured by passing custom #dlogutil_sorting_options_s and #dlogutil_filter_options_s structs to one of the prepare functions. You can also pass a timeout to the dlogutil_get_log() function.
+While receiving logs, you can decide to also sort or filter them. These can be configured by calling the corresponding functions on the #dlogutil_config_s struct. You can also pass a timeout to the dlogutil_get_log() function.
## Timestamp types
- when the oldest log is older than the time limit specified in dlog configuration file, it is returned and removed from the buffer,
- when we receive all logs in the dump mode, the buffer is cleaned up by returning all the remaining logs.
-Note that in the first two cases, it is possible, that we will receive in the future a log that should be returned before the returned one. The probability of this happening in the second case depends on the configured time limit, but in general it is extremely low. However, in the first case, missort is possible, and the probability directly depends on the buffer size, which is configurable using the dlogutil_sorting_enable_sorting_with_size() function. The argument will set the size of the sort buffer in entries, which means that the memory usage of the log receiving funtion is mostly linear to this argument (as the buffer will usually stay full most of the time). The default value is currently `131072` and there exists a maximum of `1048576`.
+Note that in the first two cases, it is possible, that we will receive in the future a log that should be returned before the returned one. The probability of this happening in the second case depends on the configured time limit, but in general it is extremely low. However, in the first case, missort is possible, and the probability directly depends on the buffer size, which is configurable using the dlogutil_config_sorting_enable_with_size() function. The argument will set the size of the sort buffer in entries, which means that the memory usage of the log receiving funtion is mostly linear to this argument (as the buffer will usually stay full most of the time). The default value is currently `131072` and there exists a maximum of `1048576`.
We'd like to reiterate that usually you don't need to worry about this, as if you disable sorting or sort by the default timestamp, the data is already received in the correct form, and there isn't even a need to create a buffer, so the data will come sorted as well as the source allows (which usually means perfect sorting).
/**
* @brief Retrieves the TID of the log sender.
* @since_tizen 6.0
- * @remarks If #DLOGUTIL_BUF_KMSG is used as the buffer, this function will always return
+ * @remarks If LOG_ID_KMSG is used as the buffer, this function will always return
* TIZEN_ERROR_NO_DATA. This is because the KMSG buffer contains no TID information.
* @param[in] entry Log entry
* @param[out] tid TID of the log sender
/**
* @brief Retrieves the PID of the log sender.
* @since_tizen 6.0
- * @remarks If #DLOGUTIL_BUF_KMSG is used as the buffer, this function will always return
+ * @remarks If LOG_ID_KMSG is used as the buffer, this function will always return
* TIZEN_ERROR_NO_DATA. This is because the KMSG buffer contains no PID information.
* @param[in] entry Log entry
* @param[out] pid PID of the log sender
/**
* @brief Destroys the #dlogutil_config_s struct.
* @since_tizen 6.0
- * @param[in] filter A handle to the settings struct
+ * @param[in] config A handle to the settings struct
* @see dlogutil_config_create()
*/
void dlogutil_config_destroy(dlogutil_config_s *config);
* @retval TIZEN_ERROR_INVALID_PARAMETER The pointer was NULL
* @retval TIZEN_ERROR_OUT_OF_MEMORY Out of memory
*/
-int dlogutil_config_filter_pid(dlogutil_config_s *config, pid_t tid);
+int dlogutil_config_filter_pid(dlogutil_config_s *config, pid_t pid);
/**
* @brief Enables retrieving only those logs that match a given filter.
* @retval TIZEN_ERROR_INVALID_PARAMETER The pointer was NULL
* @retval TIZEN_ERROR_INVALID_PARAMETER Invalid buffer
*/
-int dlogutil_config_buffer_add(dlogutil_config_s *c, log_id_t buf);
+int dlogutil_config_buffer_add(dlogutil_config_s *config, log_id_t buf);
/**
* @brief A callback for log retrieval.
/**
* @brief Destroys the #dlogutil_state_s struct.
* @since_tizen 6.0
- * @param[in] filter A handle to the state struct
+ * @param[in] state A handle to the state struct
* @see dlogutil_config_connect()
*/
void dlogutil_state_destroy(dlogutil_state_s *state);
* to reboot the system in such a case).
* @param[in] state A handle to the state struct
* @param[in] buffer A single buffer to be inspected
- * @param[out] real_buffer Buffer aliasing information: #LOG_ID_INVALID if the buffer is disabled,
- * the #log_id_t value corresponding to the real buffer otherwise
+ * @param[out] real_buffer Buffer aliasing information: LOG_ID_INVALID if the buffer is disabled,
+ * the log_id_t value corresponding to the real buffer otherwise
* @return An error code
* @retval TIZEN_ERROR_NONE Success
* @retval TIZEN_ERROR_INVALID_PARAMETER Invalid buffer
projects / platform / core / system / dlog.git / commitdiff