From: Lennart Poettering Date: Fri, 13 Jul 2012 18:39:05 +0000 (+0200) Subject: man: document sd_journal_get_cursor() X-Git-Tag: v187~98 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=4a010f4e6e95964d7acaa33be768dbdb5e46d72a man: document sd_journal_get_cursor() --- diff --git a/Makefile.am b/Makefile.am index f6301f128..50b2a9f36 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 000000000..9e00ef7c8 --- /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 c60e8f43a..ed014cb50 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 6f20c6201..a7754129f 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 a8aa3a477..515932c6d 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 90fcecb10..95429fa6f 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 12b80551a..ff089a88e 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.