]>
Commit | Line | Data |
---|---|---|
14228c0d | 1 | '\" t |
e735f4d4 | 2 | .TH "SD_JOURNAL_OPEN" "3" "" "systemd 219" "sd_journal_open" |
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" | |
60f067b4 | 23 | sd_journal_open, sd_journal_open_directory, sd_journal_open_files, sd_journal_open_container, sd_journal_close, sd_journal, SD_JOURNAL_LOCAL_ONLY, SD_JOURNAL_RUNTIME_ONLY, SD_JOURNAL_SYSTEM, SD_JOURNAL_CURRENT_USER \- Open the system journal for reading |
14228c0d MB |
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_open('u | |
60f067b4 | 32 | .BI "int sd_journal_open(sd_journal\ **" "ret" ", int\ " "flags" ");" |
14228c0d | 33 | .HP \w'int\ sd_journal_open_directory('u |
60f067b4 | 34 | .BI "int sd_journal_open_directory(sd_journal\ **" "ret" ", const\ char\ *" "path" ", int\ " "flags" ");" |
14228c0d | 35 | .HP \w'int\ sd_journal_open_files('u |
60f067b4 JS |
36 | .BI "int sd_journal_open_files(sd_journal\ **" "ret" ", const\ char\ **" "paths" ", int\ " "flags" ");" |
37 | .HP \w'int\ sd_journal_open_container('u | |
38 | .BI "int sd_journal_open_container(sd_journal\ **" "ret" ", const\ char\ *" "machine" ", int\ " "flags" ");" | |
14228c0d | 39 | .HP \w'void\ sd_journal_close('u |
60f067b4 | 40 | .BI "void sd_journal_close(sd_journal\ *" "j" ");" |
14228c0d MB |
41 | .SH "DESCRIPTION" |
42 | .PP | |
43 | \fBsd_journal_open()\fR | |
44 | opens the log journal for reading\&. It will find all journal files automatically and interleave them automatically when reading\&. As first argument it takes a pointer to a | |
45 | \fIsd_journal\fR | |
46 | pointer, which on success will contain a journal context object\&. The second argument is a flags field, which may consist of the following flags ORed together: | |
47 | \fBSD_JOURNAL_LOCAL_ONLY\fR | |
48 | makes sure only journal files generated on the local machine will be opened\&. | |
49 | \fBSD_JOURNAL_RUNTIME_ONLY\fR | |
50 | makes sure only volatile journal files will be opened, excluding those which are stored on persistent storage\&. | |
51 | \fBSD_JOURNAL_SYSTEM\fR | |
52 | will cause journal files of system services and the kernel (in opposition to user session processes) to be opened\&. | |
53 | \fBSD_JOURNAL_CURRENT_USER\fR | |
54 | will cause journal files of the current user to be opened\&. If neither | |
55 | \fBSD_JOURNAL_SYSTEM\fR | |
56 | nor | |
57 | \fBSD_JOURNAL_CURRENT_USER\fR | |
58 | are specified, all journal file types will be opened\&. | |
59 | .PP | |
60 | \fBsd_journal_open_directory()\fR | |
61 | is similar to | |
62 | \fBsd_journal_open()\fR | |
63 | but takes an absolute directory path as argument\&. All journal files in this directory will be opened and interleaved automatically\&. This call also takes a flags argument, but it must be passed as 0 as no flags are currently understood for this call\&. | |
64 | .PP | |
65 | \fBsd_journal_open_files()\fR | |
66 | is similar to | |
67 | \fBsd_journal_open()\fR | |
68 | but takes a | |
69 | \fBNULL\fR\-terminated list of file paths to open\&. All files will be opened and interleaved automatically\&. This call also takes a flags argument, but it must be passed as 0 as no flags are currently understood for this call\&. Please note that in the case of a live journal, this function is only useful for debugging, because individual journal files can be rotated at any moment, and the opening of specific files is inherently racy\&. | |
70 | .PP | |
60f067b4 JS |
71 | \fBsd_journal_open_container()\fR |
72 | is similar to | |
73 | \fBsd_journal_open()\fR | |
74 | but opens the journal files of a running OS container\&. The specified machine name refers to a container that is registered with | |
75 | \fBsystemd-machined\fR(8)\&. | |
76 | .PP | |
14228c0d MB |
77 | \fIsd_journal\fR |
78 | objects cannot be used in the child after a fork\&. Functions which take a journal object as an argument (\fBsd_journal_next()\fR | |
79 | and others) will return | |
80 | \fB\-ECHILD\fR | |
81 | after a fork\&. | |
82 | .PP | |
83 | \fBsd_journal_close()\fR | |
84 | will close the journal context allocated with | |
85 | \fBsd_journal_open()\fR | |
86 | or | |
87 | \fBsd_journal_open_directory()\fR | |
88 | and free its resources\&. | |
89 | .PP | |
90 | When opening the journal only journal files accessible to the calling user will be opened\&. If journal files are not accessible to the caller, this will be silently ignored\&. | |
91 | .PP | |
92 | See | |
93 | \fBsd_journal_next\fR(3) | |
94 | for an example of how to iterate through the journal after opening it with | |
95 | \fBsd_journal_open()\fR\&. | |
96 | .PP | |
97 | A journal context object returned by | |
98 | \fBsd_journal_open()\fR | |
99 | references a specific journal entry as | |
100 | \fIcurrent\fR | |
101 | entry, similar to a file seek index in a classic file system file, but without absolute positions\&. It may be altered with | |
102 | \fBsd_journal_next\fR(3) | |
103 | and | |
104 | \fBsd_journal_seek_head\fR(3) | |
105 | and related calls\&. The current entry position may be exported in | |
106 | \fIcursor\fR | |
107 | strings, as accessible via | |
108 | \fBsd_journal_get_cursor\fR(3)\&. 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) | |
109 | \fBsd_journal_seek_cursor\fR(3)\&. | |
110 | .PP | |
111 | Notification of journal changes is available via | |
112 | \fBsd_journal_get_fd()\fR | |
113 | and related calls\&. | |
114 | .SH "RETURN VALUE" | |
115 | .PP | |
116 | The | |
117 | \fBsd_journal_open()\fR, | |
118 | \fBsd_journal_open_directory()\fR, and | |
119 | \fBsd_journal_open_files()\fR | |
120 | calls return 0 on success or a negative errno\-style error code\&. | |
121 | \fBsd_journal_close()\fR | |
122 | returns nothing\&. | |
123 | .SH "NOTES" | |
124 | .PP | |
125 | The | |
126 | \fBsd_journal_open()\fR, | |
127 | \fBsd_journal_open_directory()\fR | |
128 | and | |
129 | \fBsd_journal_close()\fR | |
130 | interfaces are available as a shared library, which can be compiled and linked to with the | |
60f067b4 | 131 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) |
14228c0d MB |
132 | file\&. |
133 | .SH "HISTORY" | |
134 | .PP | |
135 | \fBsd_journal_open()\fR, | |
136 | \fBsd_journal_close()\fR, | |
137 | \fBSD_JOURNAL_LOCAL_ONLY\fR, | |
138 | \fBSD_JOURNAL_RUNTIME_ONLY\fR, | |
139 | \fBSD_JOURNAL_SYSTEM_ONLY\fR | |
140 | were added in systemd\-38\&. | |
141 | .PP | |
142 | \fBsd_journal_open_directory()\fR | |
143 | was added in systemd\-187\&. | |
144 | .PP | |
145 | \fBSD_JOURNAL_SYSTEM\fR, | |
146 | \fBSD_JOURNAL_CURRENT_USER\fR, and | |
147 | \fBsd_journal_open_files()\fR | |
148 | were added in systemd\-205\&. | |
149 | \fBSD_JOURNAL_SYSTEM_ONLY\fR | |
150 | was deprecated\&. | |
151 | .SH "SEE ALSO" | |
152 | .PP | |
153 | \fBsystemd\fR(1), | |
154 | \fBsd-journal\fR(3), | |
155 | \fBsd_journal_next\fR(3), | |
60f067b4 JS |
156 | \fBsd_journal_get_data\fR(3), |
157 | \fBsystemd-machined\fR(8) |