X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_get_data.xml;h=c01db4eb9364acfc26f22d1815cdbce6ce6dcb3f;hb=0f62019c34e546f7c069a3b9f46deaa4b1608276;hp=6f20c62012a4d7987441122909bc8d3435809b4c;hpb=7a8a6e88545bf22909941c9b022873709a1a1c9e;p=elogind.git
diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml
index 6f20c6201..c01db4eb9 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 been called at least
- once.
+ 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 pkg-config1
file.
@@ -193,7 +242,8 @@ int print_fields(sd_journal *j) {
sd-journal3,
sd_journal_open3,
sd_journal_next3,
- sd_journal_get_realtime_usec3
+ sd_journal_get_realtime_usec3,
+ sd_journal_query_unique3