X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_get_data.xml;h=6ed52b569e7897fa0d5def8d53b53fe7d29362ae;hb=6bb648a16ae4a682ad4784412af706d2e6a3e4da;hp=9d8a4a2221440fb0207db9dd81c76cdb9b4c2b3f;hpb=4171a6676c74846c9c189f3a92b97bbcd4a11a13;p=elogind.git
diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml
index 9d8a4a222..6ed52b569 100644
--- a/man/sd_journal_get_data.xml
+++ b/man/sd_journal_get_data.xml
@@ -47,6 +47,8 @@
sd_journal_enumerate_data
sd_journal_restart_data
SD_JOURNAL_FOREACH_DATA
+ sd_journal_set_data_threshold
+ sd_journal_get_data_threshold
Read data fields from the current journal entry
@@ -70,7 +72,7 @@
- int sd_journal_restart_data
+ void sd_journal_restart_data
sd_journal* j
@@ -81,6 +83,17 @@
size_t length
+
+ int sd_journal_set_data_threshold
+ sd_journal* j
+ size_t sz
+
+
+
+ int sd_journal_get_data_threshold
+ sd_journal* j
+ size_t* sz
+
@@ -102,7 +115,11 @@
sd_journal_enumerate_data(), or
the read pointer is altered. Note that the data
returned will be prefixed with the field name and
- '='.
+ '='. Also note that by default data fields larger than
+ 64K might get truncated to 64K. This threshold may be
+ changed and turned off with
+ sd_journal_set_data_threshold() (see
+ below).
sd_journal_enumerate_data()
may be used to iterate through all fields of the
@@ -120,14 +137,40 @@
Note that the
SD_JOURNAL_FOREACH_DATA() macro
- may be used as a wrapper around
+ may be used as a handy wrapper around
sd_journal_restart_data() and
sd_journal_enumerate_data().
Note that these functions will not work before
sd_journal_next3
- (or related call) has not been called at least
- once.
+ (or related call) has been called at least
+ once, in order to position the read pointer at a valid entry.
+
+ sd_journal_set_data_threshold()
+ may be used to change the data field size threshold
+ for data returned by
+ sd_journal_get_data(),
+ sd_journal_enumerate_data() and
+ sd_journal_enumerate_unique(). This
+ threshold is a hint only: it indicates that the client
+ program is interested only in the initial parts of the
+ data fields, up to the threshold in size -- but the
+ library might still return larger data objects. That
+ means applications should not rely exclusively on this
+ setting to limit the size of the data fields returned,
+ but need to apply a explicit size limit on the
+ returned data as well. This threshold defaults to 64K
+ by default. To retrieve the complete data fields this
+ threshold should be turned off by setting it to 0, so
+ that the library always returns the complete data
+ objects. It is recommended to set this threshold as
+ low as possible since this relieves the library from
+ having to decompress large compressed data objects in
+ full.
+
+ sd_journal_get_data_threshold()
+ returns the currently configured data field size
+ threshold.
@@ -136,27 +179,33 @@
sd_journal_get_data()
returns 0 on success or a negative errno-style error
code. If the current entry does not include the
- specified field -ENOENT is returned. If
+ specified field, -ENOENT is returned. If
sd_journal_next3
- has not been called at least once -EADDRNOTAVAIL is
+ has not been called at least once, -EADDRNOTAVAIL is
returned. sd_journal_enumerate_data()
returns a positive integer if the next field has been
read, 0 when no more fields are known, or a negative
errno-style error
code. sd_journal_restart_data()
- returns nothing.
+ returns
+ nothing. sd_journal_set_data_threshold()
+ and sd_journal_get_threshold()
+ return 0 on success or a negative errno-style error
+ code.
Notes
The sd_journal_get_data(),
- sd_journal_enumerate_data() and
- sd_journal_restart_data()
- interfaces are available as shared library, which can
+ sd_journal_enumerate_data(),
+ sd_journal_restart_data(),
+ sd_journal_set_data_threshold()
+ and
+ sd_journal_get_data_threshold()
+ interfaces are available as a shared library, which can
be compiled and linked to with the
- libsystemd-journal
- pkg-config1
+ libsystemd-journal pkg-config1
file.
@@ -192,7 +241,9 @@ int print_fields(sd_journal *j) {
systemd.journal-fields7,
sd-journal3,
sd_journal_open3,
- sd_journal_next3
+ sd_journal_next3,
+ sd_journal_get_realtime_usec3,
+ sd_journal_query_unique3