From 639a6a2529dd5a3109b998ccb44fb75b97525e13 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 13 Jul 2012 22:39:02 +0200 Subject: man: document sd_journal_seek_head() --- Makefile.am | 13 +++- man/sd_journal_seek_head.xml | 173 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 man/sd_journal_seek_head.xml diff --git a/Makefile.am b/Makefile.am index b9353f07b9..8e91e4977c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -508,7 +508,8 @@ MANPAGES = \ man/sd_journal_get_cutoff_realtime_usec.3 \ man/sd_journal_get_cursor.3 \ man/sd_journal_get_fd.3 \ - man/sd_journal_add_match.3 + man/sd_journal_add_match.3 \ + man/sd_journal_seek_head.3 MANPAGES_ALIAS = \ man/reboot.8 \ @@ -564,7 +565,11 @@ MANPAGES_ALIAS = \ man/sd_journal_process.3 \ man/sd_journal_wait.3 \ man/sd_journal_add_disjunction.3 \ - man/sd_journal_flush_matches.3 + man/sd_journal_flush_matches.3 \ + man/sd_journal_seek_tail.3 \ + man/sd_journal_seek_monotonic_usec.3 \ + man/sd_journal_seek_realtime_usec.3 \ + man/sd_journal_seek_cursor.3 man/reboot.8: man/halt.8 man/poweroff.8: man/halt.8 @@ -620,6 +625,10 @@ man/sd_journal_process.3: man/sd_journal_get_fd.3 man/sd_journal_wait.3: man/sd_journal_get_fd.3 man/sd_journal_add_disjunction.3: man/sd_journal_add_match.3 man/sd_journal_flush_matches.3: man/sd_journal_add_match.3 +man/sd_journal_seek_tail.3: man/sd_journal_seek_head.3 +man/sd_journal_seek_monotonic_usec.3: man/sd_journal_seek_head.3 +man/sd_journal_seek_realtime_usec.3: man/sd_journal_seek_head.3 +man/sd_journal_seek_cursor.3: man/sd_journal_seek_head.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_seek_head.xml b/man/sd_journal_seek_head.xml new file mode 100644 index 0000000000..b6a9a731c1 --- /dev/null +++ b/man/sd_journal_seek_head.xml @@ -0,0 +1,173 @@ + + + + + + + + + sd_journal_seek_head + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_seek_head + 3 + + + + sd_journal_seek_head + sd_journal_seek_tail + sd_journal_seek_monotonic_usec + sd_journal_seek_realtime_usec + sd_journal_seek_cursor + Seek to a position in the + journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_seek_head + sd_journal* j + + + + int sd_journal_seek_tail + sd_journal* j + + + + int sd_journal_seek_monotonic_usec + sd_journal* j + sd_id128_t boot_id + uint64_t usec + + + + int sd_journal_seek_realtime_usec + sd_journal* j + uint64_t usec + + + + int sd_journal_seek_cursor + sd_journal* j + const char * cursor + + + + + + Description + + sd_journal_seek_head() + seeks to the beginning of the journal, i.e. the oldest + avilable entry. + + Similar, + sd_journal_seek_tail() may be + used to seek to the end of the journal, i.e. the most + recent available entry. + + sd_journal_seek_monotonic_usec() + seeks to the entry with the specified monotonic + timestamp, i.e. CLOCK_MONOOTONIC. Since monotonic time + restarts on every reboot a boot ID needs to be + specified as well. + + sd_journal_seek_realtime_usec() + seeks to the entry with the specified realtime + (wallclock) timestamp, i.e. CLOCK_REALTIME. Note that + the realtime clock is not necessary monotonic. If a + realtime timestamp is ambiguous it is not defined + which position is seeked to. + + sd_journal_seek_cursor() + seeks to the entry located at the specified cursor + string. For details on cursors see + sd_journal_get_cursor3. + + Note that these calls do not actually make any + entry the new current entry, this needs to be done in + a separate step with a subsequent + sd_journal_next3 + invocation (or a similar call). Only then entry data + may be retrieved via + sd_journal_get_data3. If + no entry exists that matches exactly the specified + seek address the next closest is seeked to. If + sd_journal_next3 + is used the closest following entry will be seeked to, + if + sd_journal_previous3 + is used the closest preceeding entry is seeked + to. + + + + Return Value + + The functions return 0 on success or a negative + errno-style error code. + + + + Notes + + The sd_journal_seek_head(), + sd_journal_seek_tail(), + sd_journal_seek_monotonic_usec(), + sd_journal_seek_realtime_usec(), + and sd_journal_seek_cursor() + interfaces are 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_next3, + sd_journal_get_data3, + sd_journal_get_cursor3, + sd_journal_get_realtime_usec3 + + + + -- cgit v1.2.3-54-g00ecf