From 4a010f4e6e95964d7acaa33be768dbdb5e46d72a Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 13 Jul 2012 20:39:05 +0200 Subject: [PATCH] man: document sd_journal_get_cursor() --- Makefile.am | 3 +- man/sd_journal_get_cursor.xml | 122 ++++++++++++++++++++ man/sd_journal_get_cutoff_realtime_usec.xml | 2 +- man/sd_journal_get_data.xml | 2 +- man/sd_journal_get_realtime_usec.xml | 2 +- man/sd_journal_next.xml | 4 +- man/sd_journal_open.xml | 19 +++ 7 files changed, 149 insertions(+), 5 deletions(-) create mode 100644 man/sd_journal_get_cursor.xml diff --git a/Makefile.am b/Makefile.am index f6301f1283e..50b2a9f3638 100644 --- a/Makefile.am +++ b/Makefile.am @@ -505,7 +505,8 @@ MANPAGES = \ man/sd_journal_next.3 \ man/sd_journal_get_data.3 \ man/sd_journal_get_realtime_usec.3 \ - man/sd_journal_get_cutoff_realtime_usec.3 + man/sd_journal_get_cutoff_realtime_usec.3 \ + man/sd_journal_get_cursor.3 MANPAGES_ALIAS = \ man/reboot.8 \ diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml new file mode 100644 index 00000000000..9e00ef7c82f --- /dev/null +++ b/man/sd_journal_get_cursor.xml @@ -0,0 +1,122 @@ + + + + + + + + + sd_journal_get_cursor + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_cursor + 3 + + + + sd_journal_get_cursor + Get cursor string for the current journal entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_cursor + sd_journal* j + char ** cursor + + + + + + + Description + + sd_journal_get_cursor() + returns a cursor string for the current journal + entry. A cursor is a serialization of the current + journal position in text form. The string only + contains printable characters and can be passed around + in text form. The cursor identifies a journal entry + globally and in a stable way and may be used to later + seek to it via + sd_journal_seek_cursor3. The + cursor string should be considered opaque and not be + parsed by clients. Seeking to a cursor position + without the specific entry being available locally + will seek to the next closest (in terms of time) + available entry. The call takes two arguments: a + journal context object and a pointer to a + string pointer where the cursor string will be + placed. The string is allocated via libc malloc3 and should + be freed after use with + free3. + + Note that this function will not work before + sd_journal_next3 + (or related call) has been called at least + once, in order to position the read pointer at a valid entry. + + + + Return Value + + sd_journal_get_cursor() + returns 0 on success or a negative errno-style error + code. + + + + Notes + + The sd_journal_get_cursor() + interface is available as shared library, which can be + compiled and linked to with the + libsystemd-journal + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_seek_cursor3 + + + + diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml index c60e8f43ad1..ed014cb5093 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -45,7 +45,7 @@ sd_journal_get_cutoff_realtime_usec sd_journal_get_cutoff_monotonic_usec - Read timestamps from the current journal entry + Read cut-off timestamps from the current journal entry diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 6f20c62012a..a7754129f0e 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -127,7 +127,7 @@ 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. diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml index a8aa3a47720..515932c6d89 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -99,7 +99,7 @@ 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. diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index 90fcecb1070..95429fa6ff6 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -205,7 +205,9 @@ int main(int argc, char *argv[]) { systemd1, sd-journal3, sd_journal_open3, - sd_journal_get_data3 + sd_journal_get_data3, + sd_journal_get_realtime_usec3, + sd_journal_get_cursor3 diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 12b80551a27..ff089a88e03 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -118,6 +118,25 @@ for an example how to iterate through the journal after opening it it with sd_journal_open(). + + A journal context object returned by + sd_journal_open() references a + specific journal entry as current entry, + similar to a file seek index in a classic file system + file, but without absolute positions. It may be + altered with + sd_journal_next3 + and + sd_journal_seek_head3 + and related calls. The current entry position may be + exported in cursor strings, as accessible + via + sd_journal_get_cursor3. Cursor + strings may be used to globally identify a specific + journal entry in a stable way and then later to seek + to it (or if the specific entry is not available + locally, to its closest entry in time) + sd_journal_seek_cursor3.