]>
Commit | Line | Data |
---|---|---|
14228c0d | 1 | '\" t |
e3bff60a | 2 | .TH "SD_JOURNAL_GET_CURSOR" "3" "" "systemd 220" "sd_journal_get_cursor" |
14228c0d MB |
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_get_cursor, sd_journal_test_cursor \- Get cursor string for or test cursor string against the current journal entry | |
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_get_cursor('u | |
60f067b4 | 32 | .BI "int sd_journal_get_cursor(sd_journal\ *" "j" ", char\ **" "cursor" ");" |
14228c0d | 33 | .HP \w'int\ sd_journal_test_cursor('u |
60f067b4 | 34 | .BI "int sd_journal_test_cursor(sd_journal\ *" "j" ", const\ char\ *" "cursor" ");" |
14228c0d MB |
35 | .SH "DESCRIPTION" |
36 | .PP | |
37 | \fBsd_journal_get_cursor()\fR | |
38 | returns a cursor string for the current journal entry\&. A cursor is a serialization of the current journal position formatted as text\&. 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 | |
39 | \fBsd_journal_seek_cursor\fR(3)\&. 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 | |
40 | \fBmalloc\fR(3) | |
41 | and should be freed after use with | |
42 | \fBfree\fR(3)\&. | |
43 | .PP | |
44 | Note that | |
45 | \fBsd_journal_get_cursor()\fR | |
46 | will not work before | |
47 | \fBsd_journal_next\fR(3) | |
48 | (or related call) has been called at least once, in order to position the read pointer at a valid entry\&. | |
49 | .PP | |
50 | \fBsd_journal_test_cursor()\fR | |
51 | may be used to check whether the current position in the journal matches the specified cursor\&. This is useful since cursor strings do not uniquely identify an entry: the same entry might be referred to by multiple different cursor strings, and hence string comparing cursors is not possible\&. Use this call to verify after an invocation of | |
52 | \fBsd_journal_seek_cursor\fR(3) | |
53 | whether the entry being sought to was actually found in the journal or the next closest entry was used instead\&. | |
54 | .SH "RETURN VALUE" | |
55 | .PP | |
56 | \fBsd_journal_get_cursor()\fR | |
57 | returns 0 on success or a negative errno\-style error code\&. | |
58 | \fBsd_journal_test_cursor()\fR | |
59 | returns positive if the current entry matches the specified cursor, 0 if it does not match the specified cursor or a negative errno\-style error code on failure\&. | |
60 | .SH "NOTES" | |
61 | .PP | |
62 | The | |
63 | \fBsd_journal_get_cursor()\fR | |
64 | and | |
65 | \fBsd_journal_test_cursor()\fR | |
60f067b4 JS |
66 | interfaces are available as a shared library, which can be compiled and linked to with the |
67 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) | |
14228c0d MB |
68 | file\&. |
69 | .SH "SEE ALSO" | |
70 | .PP | |
71 | \fBsystemd\fR(1), | |
72 | \fBsd-journal\fR(3), | |
73 | \fBsd_journal_open\fR(3), | |
74 | \fBsd_journal_seek_cursor\fR(3) |