X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_next.xml;fp=man%2Fsd_journal_next.xml;h=f55ee157444f5d954f11f4de84fe4a879a8c1223;hb=67c3cf4f9ea35c1f789526b24a4d052d071902c0;hp=0000000000000000000000000000000000000000;hpb=3bb55eee6aecdab6bfdbb670299fa59801145cb6;p=elogind.git diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml new file mode 100644 index 000000000..f55ee1574 --- /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 + + + +