sd_journal_get_data(3)

1SD_JOURNAL_GET_DATA(3)        sd_journal_get_data       SD_JOURNAL_GET_DATA(3)
2
3
4

NAME

6       sd_journal_get_data, sd_journal_enumerate_data,
7       sd_journal_restart_data, SD_JOURNAL_FOREACH_DATA,
8       sd_journal_set_data_threshold, sd_journal_get_data_threshold - Read
9       data fields from the current journal entry
10

SYNOPSIS

12       #include <systemd/sd-journal.h>
13
14       int sd_journal_get_data(sd_journal *j, const char *field,
15                               const void **data, size_t *length);
16
17       int sd_journal_enumerate_data(sd_journal *j, const void **data,
18                                     size_t *length);
19
20       void sd_journal_restart_data(sd_journal *j);
21
22       SD_JOURNAL_FOREACH_DATA(sd_journal *j, const void *data,
23                               size_t length);
24
25       int sd_journal_set_data_threshold(sd_journal *j, size_t sz);
26
27       int sd_journal_get_data_threshold(sd_journal *j, size_t *sz);
28

DESCRIPTION

30       sd_journal_get_data() gets the data object associated with a specific
31       field from the current journal entry. It takes four arguments: the
32       journal context object, a string with the field name to request, plus a
33       pair of pointers to pointer/size variables where the data object and
34       its size shall be stored in. The field name should be an entry field
35       name. Well-known field names are listed in systemd.journal-fields(7).
36       The returned data is in a read-only memory map and is only valid until
37       the next invocation of sd_journal_get_data() or
38       sd_journal_enumerate_data(), or the read pointer is altered. Note that
39       the data returned will be prefixed with the field name and '='. Also
40       note that, by default, data fields larger than 64K might get truncated
41       to 64K. This threshold may be changed and turned off with
42       sd_journal_set_data_threshold() (see below).
43
44       sd_journal_enumerate_data() may be used to iterate through all fields
45       of the current entry. On each invocation the data for the next field is
46       returned. The order of these fields is not defined. The data returned
47       is in the same format as with sd_journal_get_data() and also follows
48       the same life-time semantics.
49
50       sd_journal_restart_data() resets the data enumeration index to the
51       beginning of the entry. The next invocation of
52       sd_journal_enumerate_data() will return the first field of the entry
53       again.
54
55       Note that the SD_JOURNAL_FOREACH_DATA() macro may be used as a handy
56       wrapper around sd_journal_restart_data() and
57       sd_journal_enumerate_data().
58
59       Note that these functions will not work before sd_journal_next(3) (or
60       related call) has been called at least once, in order to position the
61       read pointer at a valid entry.
62
63       sd_journal_set_data_threshold() may be used to change the data field
64       size threshold for data returned by sd_journal_get_data(),
65       sd_journal_enumerate_data() and sd_journal_enumerate_unique(). This
66       threshold is a hint only: it indicates that the client program is
67       interested only in the initial parts of the data fields, up to the
68       threshold in size — but the library might still return larger data
69       objects. That means applications should not rely exclusively on this
70       setting to limit the size of the data fields returned, but need to
71       apply an explicit size limit on the returned data as well. This
72       threshold defaults to 64K by default. To retrieve the complete data
73       fields this threshold should be turned off by setting it to 0, so that
74       the library always returns the complete data objects. It is recommended
75       to set this threshold as low as possible since this relieves the
76       library from having to decompress large compressed data objects in
77       full.
78
79       sd_journal_get_data_threshold() returns the currently configured data
80       field size threshold.
81

RETURN VALUE

83       sd_journal_get_data() returns 0 on success or a negative errno-style
84       error code. If the current entry does not include the specified field,
85       -ENOENT is returned. If sd_journal_next(3) has not been called at least
86       once, -EADDRNOTAVAIL is returned.  sd_journal_enumerate_data() returns
87       a positive integer if the next field has been read, 0 when no more
88       fields are known, or a negative errno-style error code.
89       sd_journal_restart_data() returns nothing.
90       sd_journal_set_data_threshold() and sd_journal_get_threshold() return 0
91       on success or a negative errno-style error code.
92

NOTES

94       All functions listed here are thread-agnostic and only a single
95       specific thread may operate on a given object during its entire
96       lifetime. It's safe to allocate multiple independent objects and use
97       each from a specific thread in parallel. However, it's not safe to
98       allocate such an object in one thread, and operate or free it from any
99       other, even if locking is used to ensure these threads don't operate on
100       it at the very same time.
101
102       These APIs are implemented as a shared library, which can be compiled
103       and linked to with the libsystemd pkg-config(1) file.
104

EXAMPLES

106       See sd_journal_next(3) for a complete example how to use
107       sd_journal_get_data().
108
109       Use the SD_JOURNAL_FOREACH_DATA macro to iterate through all fields of
110       the current journal entry:
111
112           ...
113           int print_fields(sd_journal *j) {
114             const void *data;
115             size_t length;
116             SD_JOURNAL_FOREACH_DATA(j, data, length)
117               printf("%.*s\n", (int) length, data);
118           }
119           ...
120

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

EXAMPLES

SEE ALSO