Debian Codegraph @

upstream/debian-unstable/man3/sd_journal_seek_head.3

raw
1 '\" t
2 .TH "SD_JOURNAL_SEEK_HEAD" "3" "" "systemd 261~rc3" "sd_journal_seek_head"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 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
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-journal\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_journal_seek_head('u
32 .BI "int sd_journal_seek_head(sd_journal\ *" "j" ");"
33 .HP \w'int\ sd_journal_seek_tail('u
34 .BI "int sd_journal_seek_tail(sd_journal\ *" "j" ");"
35 .HP \w'int\ sd_journal_seek_monotonic_usec('u
36 .BI "int sd_journal_seek_monotonic_usec(sd_journal\ *" "j" ", sd_id128_t\ " "boot_id" ", uint64_t\ " "usec" ");"
37 .HP \w'int\ sd_journal_seek_realtime_usec('u
38 .BI "int sd_journal_seek_realtime_usec(sd_journal\ *" "j" ", uint64_t\ " "usec" ");"
39 .HP \w'int\ sd_journal_seek_cursor('u
40 .BI "int sd_journal_seek_cursor(sd_journal\ *" "j" ", const\ char\ *" "cursor" ");"
41 .SH "DESCRIPTION"
42 .PP
43 \fBsd_journal_seek_head()\fR
44 seeks to the beginning of the journal, i\&.e\&. to the position before the oldest available entry\&.
45 .PP
46 Similarly,
47 \fBsd_journal_seek_tail()\fR
48 may be used to seek to the end of the journal, i\&.e\&. the position after the most recent available entry\&.
49 .PP
50 \fBsd_journal_seek_monotonic_usec()\fR
51 seeks to a position with the specified monotonic timestamp, i\&.e\&.
52 \fBCLOCK_MONOTONIC\fR\&. Since monotonic time restarts on every reboot a boot ID needs to be specified as well\&.
53 .PP
54 \fBsd_journal_seek_realtime_usec()\fR
55 seeks to a position with the specified realtime (wallclock) timestamp, i\&.e\&.
56 \fBCLOCK_REALTIME\fR\&. Note that the realtime clock is not necessarily monotonic\&. If a realtime timestamp is ambiguous, it is not defined which position is sought to\&.
57 .PP
58 \fBsd_journal_seek_cursor()\fR
59 seeks to the position at the specified cursor string\&. For details on cursors, see
60 \fBsd_journal_get_cursor\fR(3)\&. If no entry matching the specified cursor is found the call will seek to the next closest entry (in terms of time) instead\&.
61 .PP
62 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
63 \fBsd_journal_next\fR(3)
64 invocation (or a similar call)\&. Only then, entry data may be retrieved via
65 \fBsd_journal_get_data\fR(3)
66 or an entry cursor be retrieved via
67 \fBsd_journal_get_cursor\fR(3)\&. If no entry exists that matches exactly the specified seek address, the next closest is sought to\&. If
68 \fBsd_journal_next\fR(3)
69 is used, the closest following entry will be sought to, if
70 \fBsd_journal_previous\fR(3)
71 is used the closest preceding entry is sought to\&.
72 .PP
73 After the seek is done, and
74 \fBsd_journal_next\fR(3)
75 or a similar call has been made,
76 \fBsd_journal_test_cursor\fR(3)
77 may be used to verify whether the newly selected entry actually matches the cursor\&.
78 .SH "RETURN VALUE"
79 .PP
80 The functions return 0 on success or a negative errno\-style error code\&.
81 .SH "NOTES"
82 .PP
83 All functions listed here are thread\-agnostic and only a single thread may operate on a given object at any given time\&. Different threads may access the same object at different times\&. Multiple independent objects may be used from different threads in parallel\&.
84 .PP
85 Functions described here are available as a shared library, which can be compiled against and linked to with the
86 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
87 file\&.
88 .SH "HISTORY"
89 .PP
90 \fBsd_journal_seek_head()\fR,
91 \fBsd_journal_seek_tail()\fR,
92 \fBsd_journal_seek_monotonic_usec()\fR,
93 \fBsd_journal_seek_realtime_usec()\fR, and
94 \fBsd_journal_seek_cursor()\fR
95 were added in version 187\&.
96 .SH "SEE ALSO"
97 .PP
98 \fBsystemd\fR(1), \fBsd-journal\fR(3), \fBsd_journal_open\fR(3), \fBsd_journal_next\fR(3), \fBsd_journal_get_data\fR(3), \fBsd_journal_get_cursor\fR(3), \fBsd_journal_get_realtime_usec\fR(3)