diff --git a/Makefile.am b/Makefile.am index a7a1db7c052..119d9688898 100644 --- a/Makefile.am +++ b/Makefile.am @@ -501,7 +501,8 @@ MANPAGES = \ man/sd-journal.3 \ man/sd_journal_print.3 \ man/sd_journal_stream_fd.3 \ - man/sd_journal_open.3 + man/sd_journal_open.3 \ + man/sd_journal_next.3 MANPAGES_ALIAS = \ man/reboot.8 \ @@ -543,7 +544,10 @@ MANPAGES_ALIAS = \ man/sd_journal_send.3 \ man/sd_journal_sendv.3 \ man/sd_journal_open_directory.3 \ - man/sd_journal_close.3 + man/sd_journal_close.3 \ + man/sd_journal_previous.3 \ + man/sd_journal_next_skip.3 \ + man/sd_journal_previous_skip.3 man/reboot.8: man/halt.8 man/poweroff.8: man/halt.8 @@ -585,6 +589,9 @@ man/sd_journal_send.3: man/sd_journal_print.3 man/sd_journal_sendv.3: man/sd_journal_print.3 man/sd_journal_open_directory.3: man/sd_journal_open.3 man/sd_journal_close.3: man/sd_journal_open.3 +man/sd_journal_previous.3: man/sd_journal_next.3 +man/sd_journal_next_skip.3: man/sd_journal_next.3 +man/sd_journal_previous_skip.3: man/sd_journal_next.3 XML_FILES = \ ${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,${patsubst %.8,%.xml,$(MANPAGES)}}}}} diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml new file mode 100644 index 00000000000..f55ee157444 --- /dev/null +++ b/man/sd_journal_next.xml @@ -0,0 +1,194 @@ + + + + + + + + + sd_journal_next + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_next + 3 + + + + sd_journal_next + sd_journal_previous + sd_journal_next_skip + sd_journal_previous_skip + Advance or set back the read pointer in the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_next + sd_journal* j + + + + int sd_journal_previous + sd_journal* j + + + + int sd_journal_next_skip + sd_journal* j + uint64_t skip + + + + int sd_journal_previous_skip + sd_journal* j + uint64_t skip + + + + + + + Description + + sd_journal_next() advances + the read pointer into the journal by one entry. The + only argument taken is a journal context object as + allocated via + sd_journal_open3. After + successful invocation the entry may be read with + functions such as + sd_journal_get_data3. + + Similar, sd_journal_previous() sets + the read pointer back one entry. + + sd_journal_next_skip() and + sd_journal_previous_skip() + advance/set back the read pointer by multiple entries + at once, as specified in the skip + parameter. + + The journal is strictly ordered by reception + time, and hence advancing to the next entry guarantees + that the entry then pointing to is later in time than + then previous one, or has the same timestamp. + + Note that the + SD_JOURNAL_FOREACH() macro may be used + as a wrapper around + sd_journal_seek_head3 + and sd_journal_next() in order to + make iteratring through the journal easier. See below + for an example. Similar, + SD_JOURNAL_FOREACH_BACKWARDS() + may be used for iterating the journal in reverse + order. + + + + Return Value + + The four calls return the number of entries + advanced/set back on success or a negative errno-style + error code. When the end (resp. beginning) of the journal + is reached a number smaller than requested is + returned. More specifically, if + sd_journal_next() or + sd_journal_previous() reach the + end/beginning of the journal they will return 0, + instead of 1 when they are successful. This should be + considered an EOF marker. + + + + Notes + + The sd_journal_next(), sd_journal_previous(), + sd_journal_next_skip() and + sd_journal_previous_skip() interfaces are + available as shared library, which can be compiled and + linked to with the + libsystemd-journal + pkg-config1 + file. + + + + Examples + + Iterating through the journal: + + #include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH(j) { + const char *d; + size_t l; + + r = sd_journal_get_data(j, "MESSAGE", &d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + + printf("%.*s\n", (int) l, d); + } + sd_journal_close(j); + return 0; +} + + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_get_data3 + + + + diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index eb0b8c515ec..12b80551a27 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -89,7 +89,7 @@ be opened. SD_JOURNAL_RUNTIME_ONLY makes sure only volatile journal files will be opened, excluding those which are stored on persistant - storage. SD_JOURNAL_RUNTIME_ONLY + storage. SD_JOURNAL_SYSTEM_ONLY will ensure that only journal files of system services and the kernel (in opposition to user session processes) will be opened. @@ -112,6 +112,12 @@ accessible to the calling user will be opened. If journal files are not accessible to the caller this will be silently ignored. + + See + sd_journal_next3 + for an example how to iterate through the journal + after opening it it with + sd_journal_open(). diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index 3d2ed1d8f3d..917ab4fe816 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -127,6 +127,8 @@ #include <syslog.h> #include <stdio.h> +#include <string.h> +#include <unistd.h> #include <systemd/sd-journal.h> #include <systemd/sd-daemon.h>