~ubuntu-branches/ubuntu/trusty/systemd/trusty

sd_journal_get_data, 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

.SH "SYNOPSIS"

.sp

.ft B

.nf

#include <systemd/sd\-journal\&.h>

.fi

.ft

.HP \w'int\ sd_journal_get_data('u

.BI "int sd_journal_get_data(sd_journal*\ " "j" ", const\ char*\ " "field" ", const\ void**\ " "data" ", size_t*\ " "length" ");"

.HP \w'int\ sd_journal_enumerate_data('u

.BI "int sd_journal_enumerate_data(sd_journal*\ " "j" ", const\ void**\ " "data" ", size_t*\ " "length" ");"

.HP \w'void\ sd_journal_restart_data('u

.BI "void sd_journal_restart_data(sd_journal*\ " "j" ");"

.HP \w'SD_JOURNAL_FOREACH_DATA('u

.BI "SD_JOURNAL_FOREACH_DATA(sd_journal*\ " "j" ", const\ void*\ " "data" ", size_t\ " "length" ");"

.HP \w'int\ sd_journal_set_data_threshold('u

.BI "int sd_journal_set_data_threshold(sd_journal*\ " "j" ", size_t\ " "sz" ");"

.HP \w'int\ sd_journal_get_data_threshold('u

.BI "int sd_journal_get_data_threshold(sd_journal*\ " "j" ", size_t*\ " "sz" ");"

.SH "DESCRIPTION"

.PP

\fBsd_journal_get_data()\fR

gets the data object associated with a specific field from the current journal entry\&. It takes four arguments: the journal context object, a string with the field name to request, plus a pair of pointers to pointer/size variables where the data object and its size shall be stored in\&. The field name should be an entry field name\&. Well\-known field names are listed in

\fBsystemd.journal-fields\fR(7)\&. The returned data is in a read\-only memory map and is only valid until the next invocation of

\fBsd_journal_get_data()\fR

\fBsd_journal_enumerate_data()\fR, or the read pointer is altered\&. Note that the data returned will be prefixed with the field name and \*(Aq=\*(Aq\&. Also note that by default data fields larger than 64K might get truncated to 64K\&. This threshold may be changed and turned off with

\fBsd_journal_set_data_threshold()\fR

(see below)\&.

.PP

\fBsd_journal_enumerate_data()\fR

may be used to iterate through all fields of the current entry\&. On each invocation the data for the next field is returned\&. The order of these fields is not defined\&. The data returned is in the same format as with

\fBsd_journal_get_data()\fR

and also follows the same life\-time semantics\&.

.PP

\fBsd_journal_restart_data()\fR

resets the data enumeration index to the beginning of the entry\&. The next invocation of

\fBsd_journal_enumerate_data()\fR

will return the first field of the entry again\&.

.PP

Note that the

\fBSD_JOURNAL_FOREACH_DATA()\fR

macro may be used as a handy wrapper around

\fBsd_journal_restart_data()\fR

and

\fBsd_journal_enumerate_data()\fR\&.

.PP

Note that these functions will not work before

\fBsd_journal_next\fR(3)

(or related call) has been called at least once, in order to position the read pointer at a valid entry\&.

.PP

\fBsd_journal_set_data_threshold()\fR

may be used to change the data field size threshold for data returned by

\fBsd_journal_get_data()\fR,

\fBsd_journal_enumerate_data()\fR

and

\fBsd_journal_enumerate_unique()\fR\&. 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\&.

.PP

\fBsd_journal_get_data_threshold()\fR

returns the currently configured data field size threshold\&.

.SH "RETURN VALUE"

.PP

\fBsd_journal_get_data()\fR

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

\fBsd_journal_next\fR(3)

has not been called at least once \-EADDRNOTAVAIL is returned\&.

\fBsd_journal_enumerate_data()\fR

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\&.

100

\fBsd_journal_restart_data()\fR

101

returns nothing\&.

102

\fBsd_journal_set_data_threshold()\fR

103

and

104

\fBsd_journal_get_threshold()\fR

105

return 0 on success or a negative errno\-style error code\&.

106

.SH "NOTES"

107

.PP

108

The

109

\fBsd_journal_get_data()\fR,

110

\fBsd_journal_enumerate_data()\fR,

111

\fBsd_journal_restart_data()\fR,

112

\fBsd_journal_set_data_threshold()\fR

113

and

114

\fBsd_journal_get_data_threshold()\fR

115

interfaces are available as shared library, which can be compiled and linked to with the

116

libsystemd\-journal

117

\fBpkg-config\fR(1)

118

file\&.

119

.SH "EXAMPLES"

120

.PP

121

See

122

\fBsd_journal_next\fR(3)

123

for a complete example how to use

124

\fBsd_journal_get_data()\fR\&.

125

.PP

126

Use the

127

\fBSD_JOURNAL_FOREACH_DATA\fR

128

macro to iterate through all fields of the current journal entry:

129

.sp

130

.if n \{\

131

.RS 4

132

.\}

133

.nf

134

\&.\&.\&.

135

int print_fields(sd_journal *j) {

136

const void *data;

137

size_t l;

138

SD_JOURNAL_FOREACH_DATA(j, data, length)

139

printf("%\&.*s\en", (int) length, data);

140

}

141

\&.\&.\&.

142

.fi

143

.if n \{\

144

.RE

145

.\}

146

.SH "SEE ALSO"

147

.PP

148

149

\fBsystemd\fR(1),

150

\fBsystemd.journal-fields\fR(7),

151

\fBsd-journal\fR(3),

152

\fBsd_journal_open\fR(3),

153

\fBsd_journal_next\fR(3),

154

\fBsd_journal_get_realtime_usec\fR(3),

155

\fBsd_journal_query_unique\fR(3)

Older »