X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_get_data.xml;h=19fbcd35c0e87b1701a7beae62fe3989e34c158e;hb=2822da4fb7f891e5320f02f1d00f64b72221ced4;hp=6470f19cc6e442f47775a28b6aaac4ec73af110f;hpb=3c1668da6202f1ead3d4d3981b89e9da1a0e98e3;p=elogind.git
diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml
index 6470f19cc..19fbcd35c 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
@@ -56,31 +58,42 @@
int sd_journal_get_data
- sd_journal* j
- const char* field
- const void** data
- size_t* length
+ sd_journal *j
+ const char *field
+ const void **data
+ size_t *length
int sd_journal_enumerate_data
- sd_journal* j
- const void** data
- size_t* length
+ sd_journal *j
+ const void **data
+ size_t *length
void sd_journal_restart_data
- sd_journal* j
+ sd_journal *j
SD_JOURNAL_FOREACH_DATA
- sd_journal* j
- const void* data
+ sd_journal *j
+ const void *data
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
@@ -128,6 +145,32 @@
sd_journal_next3
(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 pkg-config1
file.
@@ -176,7 +225,7 @@
...
int print_fields(sd_journal *j) {
const void *data;
- size_t l;
+ size_t length;
SD_JOURNAL_FOREACH_DATA(j, data, length)
printf("%.*s\n", (int) length, data);
}