The libdlogutil API provides functions for receiving logs programatically. More...

Macros
#define	DLOGUTIL_MAX_DUMP_SIZE UINT_MAX
	Enables the full dump mode which prints every stored log.

Typedefs
typedef struct dlogutil_entry	dlogutil_entry_s
	A struct containing the metadata and contents for a single dlog entry.
typedef struct dlogutil_config	dlogutil_config_s
	A struct containing libdlogutil initialisation configuration.
typedef struct dlogutil_state	dlogutil_state_s
	A struct containing the state of a log handling request.

Enumerations
enum	dlogutil_sorting_order_e { DLOGUTIL_SORT_SENT_MONO = 0 , DLOGUTIL_SORT_SENT_REAL , DLOGUTIL_SORT_RECV_MONO , DLOGUTIL_SORT_RECV_REAL , DLOGUTIL_SORT_DEFAULT }
	Enumeration for timestamp-based log sorting orderings. More...

Functions
void	dlogutil_entry_destroy (dlogutil_entry_s *entry)
	Destroys the dlogutil_entry_s struct and cleans up its memory. @since_tizen 9.0.
int	dlogutil_entry_get_tid (const dlogutil_entry_s entry, pid_t tid)
	Retrieves the TID (thread identificator) of the log sender.
int	dlogutil_entry_get_pid (const dlogutil_entry_s entry, pid_t pid)
	Retrieves the PID (process identificator) of the log sender.
int	dlogutil_entry_get_tag (const dlogutil_entry_s entry, const char *tag)
	Retrieves the tag (arbitrary label) of the log entry.
int	dlogutil_entry_get_message (const dlogutil_entry_s entry, const char *msg)
	Retrieves the message (without any metadata) of the log entry.
int	dlogutil_entry_get_timestamp (const dlogutil_entry_s entry, dlogutil_sorting_order_e order, struct timespec ts)
	Retrieves the timestamp of given type from the log entry.
int	dlogutil_entry_get_priority (const dlogutil_entry_s entry, log_priority prio)
	Retrieves the priority level metadata of the log entry.
dlogutil_config_s *	dlogutil_config_create (void)
	Creates a new dlogutil_config_s struct to be filled with configuration.
void	dlogutil_config_destroy (dlogutil_config_s *config)
	Destroys the dlogutil_config_s struct and cleans up its memory.
int	dlogutil_config_filter_tid (dlogutil_config_s *config, pid_t tid)
	Enables retrieving only those logs that are logged by the thread with the given TID.
int	dlogutil_config_filter_pid (dlogutil_config_s *config, pid_t pid)
	Enables retrieving only those logs that are logged by the process with the given PID.
int	dlogutil_config_filter_filterspec (dlogutil_config_s config, const char query)
	Enables retrieving only those logs that match a given filter.
int	dlogutil_config_sorting_disable (dlogutil_config_s *config)
	Disables log sorting for given log retrieval request.
int	dlogutil_config_sorting_enable (dlogutil_config_s *config)
	Enables log sorting for given log retrieval request. @since_tizen 6.0.
int	dlogutil_config_sorting_enable_with_size (dlogutil_config_s *config, unsigned int entry_count)
	Enables sorting, choosing the sort buffer size manually. @since_tizen 6.0.
int	dlogutil_config_order_set (dlogutil_config_s *config, dlogutil_sorting_order_e sort_by)
	Chooses a timestamp type by which returned logs are sorted by @since_tizen 6.0.
int	dlogutil_config_buffer_add (dlogutil_config_s *config, log_id_t buf)
	Adds a buffer whence logs will be taken to a request.
void	dlogutil_state_destroy (dlogutil_state_s *state)
	Destroys the dlogutil_state_s struct and frees its memory.
int	dlogutil_config_mode_set_continuous (dlogutil_config_s *config)
	Set log retrieval mode to retrieving all the logs since the start of the system without an end.
int	dlogutil_config_mode_set_monitor (dlogutil_config_s *config)
	Set log retrieval mode to retrieving all the logs since the call without an end.
int	dlogutil_config_mode_set_dump (dlogutil_config_s *config, unsigned int entry_count)
	Set log retrieval mode to dumping all the logs since the start of the system until the call (possibly a specified amount of the most recent of them instead).
int	dlogutil_config_mode_set_compressed_memory_dump (dlogutil_config_s config, const char compression_buffer)
	Set log retrieval mode to dumping compressed historical logs.
int	dlogutil_config_connect (dlogutil_config_s config, dlogutil_state_s *state_out)
	Finalizes the config into a state struct by connecting to buffers.
int	dlogutil_get_log (dlogutil_state_s state, int timeout, dlogutil_entry_s *entry_out)
	Retrieves a single log according to a dump request.
int	dlogutil_buffer_clear (dlogutil_state_s *state, log_id_t buffer)
	Irreversibly clears a log buffer from any logs inside.
int	dlogutil_buffer_get_name (log_id_t buffer, const char **name)
	Gets the human-readable, constant name of a buffer.
int	dlogutil_buffer_get_capacity (dlogutil_state_s state, log_id_t buffer, unsigned int capacity)
	Gets the data storage capacity of a log buffer in bytes.
int	dlogutil_buffer_get_usage (dlogutil_state_s state, log_id_t buffer, unsigned int usage)
	Gets the storage data usage of a log buffer, in bytes.
int	dlogutil_buffer_get_default_ts_type (log_id_t buffer, dlogutil_sorting_order_e *type)
	Gets the default sorting timestamp type of a buffer. @since_tizen 6.0.
int	dlogutil_buffer_check_ts_type_available (log_id_t buffer, dlogutil_sorting_order_e type, bool *available)
	Checks if a buffer contains timestamps of a given type. @since_tizen 6.0.
int	dlogutil_buffer_get_alias (dlogutil_state_s state, log_id_t buffer, log_id_t real_buffer)
	Gets the buffer aliasing (same storage) information @since_tizen 6.0.

Detailed Description

libdlogutil lets you retrieve logs much like the dlogutil CLI tool. In fact, dlogutil is just a trivial client of libdlogutil. See the overview section for more.

Required Header

#include <dlogutil.h>

Overview

This API can be used to do everything that the dlogutil CLI can (see dlogutil CLI). The most important use, however, is to receive the logs of the working Tizen system.

Permissions

We used to require libdlogutil user to either have the CAP_SYSLOG capability, or be in the log group. We still require this for some control operations, however it is not needed to have it in order to get logs, which is the most common operation. However, user without CAP_SYSLOG/log group will with high probability only see part of the logs; therefore, we suggest to operate with CAP_SYSLOG/log group.

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 first configuring the library using the config struct (dlogutil_config_s) and then calling the dlogutil_config_connect() function.

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_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 calling the corresponding functions on the dlogutil_config_s struct. You can also pass a timeout to the dlogutil_get_log() function.

Timestamp types

The timestamps can be generated by one of the two types of clocks:

monotonic, which give the time since device boot (which isn't comparable across devices, nor across device boots),
and realtime, which give the wall-clock time (which isn't sortable, being adjustable backwards by a user).

These map directly to CLOCK_MONOTONIC and CLOCK_REALTIME as described in the clock_getres(2) manpage. Additionally, each timestamp can be either generated by:

the sender, which means the timestamp is the close representation of the log sending time,
or the receiver, which means the timestamp tells us when the dlog daemon received the log from the application.

Usually, the sender timestamps are preferable, but they aren't always available.

Sorting quality

When it comes to sorting, there are two options possible:

sorting may be unnecessary. This might happen when you disable sorting manually, or when you enable sorting by the default timestamp (by which the data is already sorted). In this case, there will be no additional sorting (because it is unnecessary), so the sorting quality will be as good as the log source provides,
sorting may be necessary, which happens in all other situations. In this case, sorting will be performed.

Unfortunately, sorting the logs in a perfect way is harder than it might look. This is due to the need to output the logs in a timely manner, as well as the sheer amount of them. What if we receive a log from an hour ago? If we have already output the logs from the last second, it is now impossible to output the new log before them. Therefore, correct sorting is impossible in this case. In theory, this issue does not appear in the dump mode, but in this case, the number of logs might become an issue — some products based on Tizen have huge amounts of logs generated every second. In this case, we could end up timing out even if O(nlogn) sorting is used.

Our solution is to compare only close logs, while returning it as they come. The idea is to hold a circular buffer of logs of a fixed size, and, instead of returning incoming logs immediately, put them into the buffer. As we put the log into the buffer, we immediately make sure it's sorted. This is performant in our case because the input is almost sorted (the timestamps of different types should be correlated with each other, and the input is sorted by one of them).

A log will be finally returned in three cases:

when the buffer is filled up and we receive a new log, the oldest log in the buffer is returned and removed from the buffer to create space for the new one,
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_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).

Other operations

You can also use the API to erase the log buffers — this can be done using the dlogutil_buffer_clear() function.

Macro Definition Documentation

◆ DLOGUTIL_MAX_DUMP_SIZE

#define DLOGUTIL_MAX_DUMP_SIZE UINT_MAX

Pass this constant when you want to dump everything and not just N most recent logs. @since_tizen 6.0

See also: dlogutil_config_mode_set_dump()

Typedef Documentation

◆ dlogutil_config_s

typedef struct dlogutil_config dlogutil_config_s

This is the handle to a one-time setup you have to do before sending a log retrieval request. @since_tizen 6.0

◆ dlogutil_entry_s

typedef struct dlogutil_entry dlogutil_entry_s

An individual log, received after all filters were applied.

Bug: Currently missing a dlogutil_entry_destroy() function. Use regular libc free(). @since_tizen 6.0

◆ dlogutil_state_s

typedef struct dlogutil_state dlogutil_state_s

Represents a connection to dlog backend. You can't change config anymore at this point, but can start retrieving logs. @since_tizen 6.0

Enumeration Type Documentation

◆ dlogutil_sorting_order_e

enum dlogutil_sorting_order_e

Log messages get up to 4 different timestamps which don't necessarily produce the same ordering. This enum lets you specify which ordering you want in given context. @since_tizen 6.0

Remarks: For information on the timestamp documentation, refer to Overview.

Enumerator
DLOGUTIL_SORT_SENT_MONO	Monotonic timestamp applied by the sender
DLOGUTIL_SORT_SENT_REAL	Real-time timestamp applied by the sender
DLOGUTIL_SORT_RECV_MONO	Monotonic timestamp applied by the receiver
DLOGUTIL_SORT_RECV_REAL	Real-time timestamp applied by the receiver
DLOGUTIL_SORT_DEFAULT	The default timestamp of the buffer See also dlogutil_buffer_get_default_ts_type()

Function Documentation

◆ dlogutil_buffer_check_ts_type_available()

int dlogutil_buffer_check_ts_type_available	(	log_id_t	buffer,
		dlogutil_sorting_order_e	type,
		bool *	available )

If false is returned, the timestamp may still be available in some of the logs. However, if true is returned, the timestamp will always be available. You can check the timestamp availability per log using the dlogutil_entry_get_timestamp() function.

Bug: This is currently evaluated using the config file, which can change at runtime. In particular, this can desync from the value of the server if the config file changes. Note that this is mostly a theoretical concern, since the file is not intended to change during the runtime (the daemon asks to reboot the system in such a case).

Parameters

[in]	buffer	A single buffer to be inspected
[in]	type	The timestamp type to be considered
[out]	available	Whether the given timestamp type is guaranteed to be available

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	More than one buffer
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL
TIZEN_ERROR_IO_ERROR	Couldn't read config file

◆ dlogutil_buffer_clear()

int dlogutil_buffer_clear	(	dlogutil_state_s *	state,
		log_id_t	buffer )

Tells the backend to get rid of any stored logs. Good for chaff management. @since_tizen 6.0

Remarks: You can't use one of the log-getting modes (dlogutil_config_mode_set_*).

Parameters

[in]	state	A handle to the state struct
[in]	buffer	A buffer to be cleared

Remarks: Either CAP_SYSLOG or being in the log group is required.

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	State pointer was null
TIZEN_ERROR_INVALID_PARAMETER	State in log-getting mode
TIZEN_ERROR_IO_ERROR	Couldn't fulfill request
Other	An arbitrary Tizen error code

◆ dlogutil_buffer_get_alias()

int dlogutil_buffer_get_alias	(	dlogutil_state_s *	state,
		log_id_t	buffer,
		log_id_t *	real_buffer )

Sometimes, multiple buffers will be backed by a single log storage (for example, by the same kernel device). In such cases, the storage will only be opened once. This function allows you to see whether this is the case.

Bug: This is currently evaluated using the config file, which can change at runtime. In particular, this can desync from the value of the server if the config file changes. Note that this is mostly a theoretical concern, since the file is not intended to change during the runtime (the daemon asks to reboot the system in such a case).

Parameters

[in]	state	A handle to the state struct
[in]	buffer	A single buffer to be inspected
[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

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL

◆ dlogutil_buffer_get_capacity()

int dlogutil_buffer_get_capacity	(	dlogutil_state_s *	state,
		log_id_t	buffer,
		unsigned int *	capacity )

Returns how many bytes of logs can fit in given buffer on the backend. @since_tizen 6.0

Remarks: Either CAP_SYSLOG or being in the log group is required. Also, you can't use one of the log-getting modes (dlogutil_config_mode_set_*).

Bug: This is currently evaluated using the config file, which can change at runtime. In particular, this can desync from the value of the server if the config file changes. Note that this is mostly a theoretical concern, since the file is not intended to change during the runtime (the daemon asks to reboot the system in such a case).

Parameters

[in]	state	A handle to the state struct
[in]	buffer	A buffer to be inspected
[out]	capacity	The buffer's maximum capacity, in bytes

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	The state pointer was NULL
TIZEN_ERROR_INVALID_PARAMETER	The capacity pointer was NULL
TIZEN_ERROR_INVALID_PARAMETER	State in log-getting mode
TIZEN_ERROR_IO_ERROR	Couldn't fulfill request
Other	An arbitrary Tizen error code

◆ dlogutil_buffer_get_default_ts_type()

int dlogutil_buffer_get_default_ts_type	(	log_id_t	buffer,
		dlogutil_sorting_order_e *	type )

This is the timestamp type that will be used for sorting by default. We assume that it is always available and the input is sorted by it. See Overview for more details.

Bug: This is currently evaluated using the config file, which can change at runtime. In particular, this can desync from the value of the server if the config file changes. Note that this is mostly a theoretical concern, since the file is not intended to change during the runtime (the daemon asks to reboot the system in such a case).

Parameters

[in]	buffer	A single buffer to be inspected
[out]	type	The default timestamp type of the passed buffer

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL
TIZEN_ERROR_IO_ERROR	Couldn't read config file
Other	An arbitrary Tizen error code

◆ dlogutil_buffer_get_name()

int dlogutil_buffer_get_name	(	log_id_t	buffer,
		const char **	name )

Gets the name of a buffer according to dlog. Mostly for convenience. @since_tizen 6.0

Remarks: The returned string will have the static lifetime.

Parameters

[in]	buffer	A buffer to be inspected
[out]	name	The name of the passed buffer

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL

◆ dlogutil_buffer_get_usage()

int dlogutil_buffer_get_usage	(	dlogutil_state_s *	state,
		log_id_t	buffer,
		unsigned int *	usage )

Returns how many bytes of logs are currently stored in given buffer on the backend. @since_tizen 6.0

Remarks: Either CAP_SYSLOG or being in the log group is required. Also, you can't use one of the log-getting modes (dlogutil_config_mode_set_*).

Bug: This is currently evaluated using the config file, which can change at runtime. In particular, this can desync from the value of the server if the config file changes. Note that this is mostly a theoretical concern, since the file is not intended to change during the runtime (the daemon asks to reboot the system in such a case).

Parameters

[in]	state	A handle to the state struct
[in]	buffer	A buffer to be inspected
[out]	usage	Buffer's current usage, in bytes

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer
TIZEN_ERROR_INVALID_PARAMETER	The state pointer was NULL
TIZEN_ERROR_INVALID_PARAMETER	The usage pointer was NULL
TIZEN_ERROR_INVALID_PARAMETER	State in log-getting mode
TIZEN_ERROR_IO_ERROR	Couldn't fulfill request
Other	An arbitrary Tizen error code

◆ dlogutil_config_buffer_add()

int dlogutil_config_buffer_add	(	dlogutil_config_s *	config,
		log_id_t	buf )

Specifies which buffer to retrieve logs from. Usually this will be main or apps. @since_tizen 6.0

Parameters

[in]	config	A handle to the settings struct
[in]	buf	The buffer ID to add to the handled set

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL
TIZEN_ERROR_INVALID_PARAMETER	Invalid buffer

◆ dlogutil_config_connect()

int dlogutil_config_connect	(	dlogutil_config_s *	config,
		dlogutil_state_s **	state_out )

Gives you a state, letting you start getting logs. You can get rid of the config at this point. @since_tizen 6.0

Remarks: An application having platform privilege level can read platform log data by declaring http://tizen.org/privilege/log, which has been added since 6.5.

Parameters

[in]	config	A handle to the settings struct
[out]	state_out	A handle to the state struct, which can be used in dlogutil_get_log() and has to be destroyed by you

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Config or state_out was NULL
TIZEN_ERROR_INVALID_PARAMETER	No buffers selected
TIZEN_ERROR_NOT_SUPPORTED	Unsupported buffer set (KMSG + non-KMSG)
TIZEN_ERROR_NOT_SUPPORTED	Unsupported backend (zero-copy)
TIZEN_ERROR_NO_DATA	No buffers were opened (incl. due to null backend)
TIZEN_ERROR_IO_ERROR	Couldn't read config file
TIZEN_ERROR_IO_ERROR	Couldn't contact log backend
TIZEN_ERROR_OUT_OF_MEMORY	There's not enough memory

◆ dlogutil_config_create()

dlogutil_config_s * dlogutil_config_create ( void )

Creates a config to be filled in, this is the first function you should call. @since_tizen 6.0

Remarks: Needs to be freed using dlogutil_config_destroy().

Returns: A handle to the new struct, or NULL if out of memory

See also: dlogutil_config_destroy()

◆ dlogutil_config_destroy()

void dlogutil_config_destroy ( dlogutil_config_s * config )

Frees resources of a config. Call it after you've connected and received a dlogutil state. @since_tizen 6.0

Parameters

[in] config A handle to the settings struct

See also: dlogutil_config_create()

◆ dlogutil_config_filter_filterspec()

int dlogutil_config_filter_filterspec	(	dlogutil_config_s *	config,
		const char *	query )

Filters by tag and priority. Useful for dumping logs of a specific program or subcomponent, or of sufficient importance. @since_tizen 6.0

Parameters

[in]	config	A handle to the settings struct.
[in]	query	The filter query. For syntax, see dlogutil's –help or dlogutil CLI documentation.

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid syntax of the filterspec
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_OUT_OF_MEMORY	Out of memory

◆ dlogutil_config_filter_pid()

int dlogutil_config_filter_pid	(	dlogutil_config_s *	config,
		pid_t	pid )

Filters by PID. Useful for dumping the logs of a specific process. @since_tizen 6.0

Parameters

[in]	config	A handle to the settings struct.
[in]	pid	The PID value.

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL
TIZEN_ERROR_OUT_OF_MEMORY	Out of memory

◆ dlogutil_config_filter_tid()

int dlogutil_config_filter_tid	(	dlogutil_config_s *	config,
		pid_t	tid )

Filters by TID. Useful for dumping the logs of a specific thread in a multithreaded process. @since_tizen 6.0

Parameters

[in]	config	A handle to the settings struct
[in]	tid	The TID value

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL
TIZEN_ERROR_OUT_OF_MEMORY	Out of memory

◆ dlogutil_config_mode_set_compressed_memory_dump()

int dlogutil_config_mode_set_compressed_memory_dump	(	dlogutil_config_s *	config,
		const char *	compression_buffer )

Similar to the dump mode, but works on a named compressed buffer. @since_tizen 7.0

Remarks: This is similar to cat /var/log/dlog/xyz. After dumping all the logs, dlogutil_get_log() will signal this by returning TIZEN_ERROR_NO_DATA.

Parameters

[in,out]	config	The configuration struct
[in]	compression_buffer	The name of the compression storage entry

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_OUT_OF_MEMORY	Not enough memory. Parameters left unchanged
TIZEN_ERROR_INVALID_PARAMETER	Config or compression_buffer was NULL

See also: dlogutil_config_mode_set_continuous(); dlogutil_config_mode_set_monitor(); dlogutil_config_mode_set_dump()

◆ dlogutil_config_mode_set_continuous()

int dlogutil_config_mode_set_continuous ( dlogutil_config_s * config )

Essentially a dump, followed by monitoring. See those modes. @since_tizen 6.0

Remarks: This is similar to dlogutil in a default mode.

Parameters

[in,out] config The configuration struct

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Config was NULL

See also: dlogutil_config_mode_set_monitor(); dlogutil_config_mode_set_dump(); dlogutil_config_mode_set_compressed_memory_dump()

◆ dlogutil_config_mode_set_dump()

int dlogutil_config_mode_set_dump	(	dlogutil_config_s *	config,
		unsigned int	entry_count )

Will only retrieve existing logs. Any logs incoming after the connection are ignored. Good for avoiding floods. @since_tizen 6.0

Remarks: This is similar to dlogutil -d. After dumping all the logs, dlogutil_get_log() will signal this by returning TIZEN_ERROR_NO_DATA.

Parameters

[in,out]	config	The configuration struct
[in]	entry_count	Number of logs to be returned. It can be DLOGUTIL_MAX_DUMP_SIZE, in which case all the logs will be dumped

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Config was NULL

See also: dlogutil_config_mode_set_continuous(); dlogutil_config_mode_set_monitor(); dlogutil_config_mode_set_compressed_memory_dump()

◆ dlogutil_config_mode_set_monitor()

int dlogutil_config_mode_set_monitor ( dlogutil_config_s * config )

Will only retrieve new logs. Any logs present before the connection are ignored. Good for live debugging. @since_tizen 6.0

Remarks: This is similar to dlogutil -m.

Parameters

[in,out] config The configuration struct

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Config was NULL

See also: dlogutil_config_mode_set_continuous(); dlogutil_config_mode_set_dump(); dlogutil_config_mode_set_compressed_memory_dump()

◆ dlogutil_config_order_set()

int dlogutil_config_order_set	(	dlogutil_config_s *	config,
		dlogutil_sorting_order_e	sort_by )

If the chosen timestamp is missing in the logs, currently they will not be sorted at all. This should, however, still become a reasonable order, since logs are usually stored sorted by one of timestamps. If only some logs are missing the chosen timestamp, ordering of the logs is undefined. See dlogutil_buffer_get_default_ts_type() for the default.

Parameters

[in]	config	A handle to the settings struct
[in]	sort_by	Which timestamp type to sort by. DLOGUTIL_SORT_DEFAULT is allowed

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL

◆ dlogutil_config_sorting_disable()

int dlogutil_config_sorting_disable ( dlogutil_config_s * config )

Logs are still received in some order that is usually largely sorted, but if sorting is disabled logutil-side there may be cases where a log with a later timestamp is in front of a log with an earlier one. The use case here is performance, since the failure case above is rare. @since_tizen 6.0

Parameters

[in] config A handle to the settings struct

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL

See also: dlogutil_config_sorting_enable(); dlogutil_config_sorting_enable_with_size()

◆ dlogutil_config_sorting_enable()

int dlogutil_config_sorting_enable ( dlogutil_config_s * config )

Makes sure logs are sorted. This is the default but has a modest performance cost.

Parameters

[in] config A handle to the settings struct

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL

See also: dlogutil_config_sorting_disable(); dlogutil_config_sorting_enable_with_size()

◆ dlogutil_config_sorting_enable_with_size()

int dlogutil_config_sorting_enable_with_size	(	dlogutil_config_s *	config,
		unsigned int	entry_count )

Remarks: The count parameter influences the quality of sorting, but also memory usage. This version is a somewhat lower level version of dlogutil_config_sorting_enable(). For more information on sorting quality, see Overview.

Parameters

[in]	config	A handle to the settings struct
[in]	entry_count	How many logs to keep at a given time. At least 1

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Zero size
TIZEN_ERROR_INVALID_PARAMETER	The pointer was NULL

See also: dlogutil_config_sorting_disable(); dlogutil_config_sorting_enable()

◆ dlogutil_entry_destroy()

void dlogutil_entry_destroy ( dlogutil_entry_s * entry )

Parameters

[in] entry A handle to the entry struct

See also: dlogutil_get_log()

◆ dlogutil_entry_get_message()

int dlogutil_entry_get_message	(	const dlogutil_entry_s *	entry,
		const char **	msg )

Gets the raw message itself, which is the essence of a log. @since_tizen 6.0

Remarks: The message is owned by the entry so do not free nor modify it. In some rare cases the entry may be malformed and the message may turn out to be unavailable. In such cases, an empty string may be returned instead.

Parameters

[in]	entry	Log entry
[out]	msg	Log message

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_NO_DATA	The message is missing

◆ dlogutil_entry_get_pid()

int dlogutil_entry_get_pid	(	const dlogutil_entry_s *	entry,
		pid_t *	pid )

Retrieves the PID who sent a log, useful for debugging in a multi-program environment. @since_tizen 6.0

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.

Parameters

[in]	entry	Log entry
[out]	pid	PID of the log sender

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_NO_DATA	PID missing or not applicable

◆ dlogutil_entry_get_priority()

int dlogutil_entry_get_priority	(	const dlogutil_entry_s *	entry,
		log_priority *	prio )

Checks how important the log was. Note that you only receive logs that pass any priority filters you set, so you don't need to worry about chaff. @since_tizen 6.0

Parameters

[in]	entry	Log entry
[out]	prio	Log priority

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_NO_DATA	The priority is missing

◆ dlogutil_entry_get_tag()

int dlogutil_entry_get_tag	(	const dlogutil_entry_s *	entry,
		const char **	tag )

Gets the log's tag, which has two main purposes. One is to identify multiple instances of the same program. The other is to identify subcomponents of a program, e.g. libraries. @since_tizen 6.0

Remarks: The tag is owned by the entry so do not free nor modify it. In some rare cases the entry may be malformed and the message may turn out to be unavailable. In such cases, an empty string may be returned instead.

Parameters

[in]	entry	Log entry
[out]	tag	Log tag

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_NO_DATA	The tag is missing

◆ dlogutil_entry_get_tid()

int dlogutil_entry_get_tid	(	const dlogutil_entry_s *	entry,
		pid_t *	tid )

Retrieves the TID who sent a log, useful for debugging multithreaded programs. @since_tizen 6.0

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.

Parameters

[in]	entry	Log entry
[out]	tid	TID of the log sender

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_NO_DATA	TID missing or not applicable

◆ dlogutil_entry_get_timestamp()

int dlogutil_entry_get_timestamp	(	const dlogutil_entry_s *	entry,
		dlogutil_sorting_order_e	order,
		struct timespec *	ts )

Gets the timestamp of a log, which lets you know when it was sent. @since_tizen 6.0

Remarks: The information about timestamp availability can be retrieved using the dlogutil_buffer_check_ts_type_available() function. For information on the timespec struct, refer to the clock_gettime(2) manpage.

Parameters

[in]	entry	Log entry
[in]	order	Which timestamp to extract. DLOGUTIL_SORT_DEFAULT is NOT allowed currently
[out]	ts	Timestamp of the entry

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_INVALID_PARAMETER	Invalid value of order
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_NO_DATA	The timestamp is missing

See also: dlogutil_buffer_check_ts_type_available()

◆ dlogutil_get_log()

int dlogutil_get_log	(	dlogutil_state_s *	state,
		int	timeout,
		dlogutil_entry_s **	entry_out )

Gets a log from the backend. See the API for dlogutil entry. @since_tizen 6.0

Remarks: If the calling process doesn't have CAP_SYSLOG and is not in the log group, you will only get some of the logs. Also, you must set the mode (dlogutil_config_mode_set_*).

Parameters

[in]	state	A handle to the state struct
[in]	timeout	How many milliseconds to wait for the log. The actual runtime of the call can obviously be slightly longer than this argument. 0 means don't wait, -1 means wait indefinitely
[out]	entry_out	A returned log. It is owned by you and must be freed using dlogutil_entry_destroy function. In case of an error, NULL is returned

Returns: An error code

Return values

TIZEN_ERROR_NONE	Success
TIZEN_ERROR_TIMED_OUT	Timeout exceeded
TIZEN_ERROR_NO_DATA	In dump mode, no more logs remaining
TIZEN_ERROR_INVALID_PARAMETER	One of the pointers was NULL
TIZEN_ERROR_INVALID_PARAMETER	State not in log-getting mode
TIZEN_ERROR_OUT_OF_MEMORY	There's not enough memory
TIZEN_ERROR_IO_ERROR	Couldn't fulfill request

See also: dlogutil_entry_destroy()

◆ dlogutil_state_destroy()

void dlogutil_state_destroy ( dlogutil_state_s * state )

Use after you're done retrieving logs and are cleaning up. @since_tizen 6.0

Parameters

[in] state A handle to the state struct

See also: dlogutil_config_connect()

Macros

Typedefs

Enumerations

Functions

Detailed Description

Required Header

Overview

Permissions

Receiving logs

Timestamp types

Sorting quality

Other operations

Macro Definition Documentation

◆ DLOGUTIL_MAX_DUMP_SIZE

Typedef Documentation

◆ dlogutil_config_s

◆ dlogutil_entry_s

◆ dlogutil_state_s

Enumeration Type Documentation

◆ dlogutil_sorting_order_e

Function Documentation

◆ dlogutil_buffer_check_ts_type_available()

◆ dlogutil_buffer_clear()

◆ dlogutil_buffer_get_alias()

◆ dlogutil_buffer_get_capacity()

◆ dlogutil_buffer_get_default_ts_type()

◆ dlogutil_buffer_get_name()

◆ dlogutil_buffer_get_usage()

◆ dlogutil_config_buffer_add()

◆ dlogutil_config_connect()

◆ dlogutil_config_create()

◆ dlogutil_config_destroy()

◆ dlogutil_config_filter_filterspec()

◆ dlogutil_config_filter_pid()

◆ dlogutil_config_filter_tid()

◆ dlogutil_config_mode_set_compressed_memory_dump()

◆ dlogutil_config_mode_set_continuous()

◆ dlogutil_config_mode_set_dump()

◆ dlogutil_config_mode_set_monitor()

◆ dlogutil_config_order_set()

◆ dlogutil_config_sorting_disable()

◆ dlogutil_config_sorting_enable()

◆ dlogutil_config_sorting_enable_with_size()

◆ dlogutil_entry_destroy()

◆ dlogutil_entry_get_message()

◆ dlogutil_entry_get_pid()

◆ dlogutil_entry_get_priority()

◆ dlogutil_entry_get_tag()

◆ dlogutil_entry_get_tid()

◆ dlogutil_entry_get_timestamp()

◆ dlogutil_get_log()

◆ dlogutil_state_destroy()