Debian Codegraph @

upstream/debian-unstable/man3/sd_journal_open.3

raw
1 '\" t
2 .TH "SD_JOURNAL_OPEN" "3" "" "systemd 261~rc3" "sd_journal_open"
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_open, sd_journal_open_directory, sd_journal_open_directory_fd, sd_journal_open_files, sd_journal_open_files_fd, sd_journal_open_namespace, sd_journal_close, sd_journal, SD_JOURNAL_LOCAL_ONLY, SD_JOURNAL_RUNTIME_ONLY, SD_JOURNAL_SYSTEM, SD_JOURNAL_CURRENT_USER, SD_JOURNAL_OS_ROOT, SD_JOURNAL_ALL_NAMESPACES, SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE, SD_JOURNAL_TAKE_DIRECTORY_FD \- Open the system journal for reading
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
32 .BI "int sd_journal_open(sd_journal\ **" "ret" ", int\ " "flags" ");"
33 .HP \w'int\ sd_journal_open_namespace('u
34 .BI "int sd_journal_open_namespace(sd_journal\ **" "ret" ", const\ char\ *" "namespace" ", int\ " "flags" ");"
35 .HP \w'int\ sd_journal_open_directory('u
36 .BI "int sd_journal_open_directory(sd_journal\ **" "ret" ", const\ char\ *" "path" ", int\ " "flags" ");"
37 .HP \w'int\ sd_journal_open_directory_fd('u
38 .BI "int sd_journal_open_directory_fd(sd_journal\ **" "ret" ", int\ " "fd" ", int\ " "flags" ");"
39 .HP \w'int\ sd_journal_open_files('u
40 .BI "int sd_journal_open_files(sd_journal\ **" "ret" ", const\ char\ **" "paths" ", int\ " "flags" ");"
41 .HP \w'int\ sd_journal_open_files_fd('u
42 .BI "int sd_journal_open_files_fd(sd_journal\ **" "ret" ", int\ " "fds[]" ", unsigned\ " "n_fds" ", int\ " "flags" ");"
43 .HP \w'void\ sd_journal_close('u
44 .BI "void sd_journal_close(sd_journal\ *" "j" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_journal_open()\fR
48 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
49 \fIsd_journal\fR
50 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:
51 \fBSD_JOURNAL_LOCAL_ONLY\fR
52 makes sure only journal files generated on the local machine will be opened\&.
53 \fBSD_JOURNAL_RUNTIME_ONLY\fR
54 makes sure only volatile journal files will be opened, excluding those which are stored on persistent storage\&.
55 \fBSD_JOURNAL_SYSTEM\fR
56 will cause journal files of system services and the kernel (in opposition to user session processes) to be opened\&.
57 \fBSD_JOURNAL_CURRENT_USER\fR
58 will cause journal files of the current user to be opened\&. If neither
59 \fBSD_JOURNAL_SYSTEM\fR
60 nor
61 \fBSD_JOURNAL_CURRENT_USER\fR
62 are specified, all journal file types will be opened\&.
63 .PP
64 \fBsd_journal_open_namespace()\fR
65 is similar to
66 \fBsd_journal_open()\fR
67 but takes an additional
68 \fInamespace\fR
69 parameter that specifies which journal namespace to operate on\&. If specified as
70 \fBNULL\fR
71 the call is identical to
72 \fBsd_journal_open()\fR\&. If non\-\fBNULL\fR
73 only data from the namespace identified by the specified parameter is accessed\&. This call understands two additional flags: if
74 \fBSD_JOURNAL_ALL_NAMESPACES\fR
75 is specified the
76 \fInamespace\fR
77 parameter is ignored and all defined namespaces are accessed simultaneously; if
78 \fBSD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE\fR
79 the specified namespace and the default namespace are accessed but no others (this flag has no effect when
80 \fInamespace\fR
81 is passed as
82 \fBNULL\fR)\&. For details about journal namespaces see
83 \fBsystemd-journald.service\fR(8)\&.
84 .PP
85 \fBsd_journal_open_directory()\fR
86 is similar to
87 \fBsd_journal_open()\fR
88 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\&. The flags parameters accepted by this call are
89 \fBSD_JOURNAL_OS_ROOT\fR,
90 \fBSD_JOURNAL_SYSTEM\fR, and
91 \fBSD_JOURNAL_CURRENT_USER\fR\&. If
92 \fBSD_JOURNAL_OS_ROOT\fR
93 is specified, journal files are searched for below the usual
94 /var/log/journal
95 and
96 /run/log/journal
97 relative to the specified path, instead of directly beneath it\&. The other two flags limit which files are opened, the same as for
98 \fBsd_journal_open()\fR\&.
99 .PP
100 \fBsd_journal_open_directory_fd()\fR
101 is similar to
102 \fBsd_journal_open_directory()\fR, but takes a file descriptor referencing a directory in the file system instead of an absolute file system path\&. In addition to the flags accepted by
103 \fBsd_journal_open_directory()\fR, this function also accepts
104 \fBSD_JOURNAL_TAKE_DIRECTORY_FD\fR\&. If
105 \fBSD_JOURNAL_TAKE_DIRECTORY_FD\fR
106 is specified, the function will take the ownership of the specified file descriptor on success, and it will be closed by
107 \fBsd_journal_close()\fR, hence the caller of the function must not close the file descriptor\&. When the flag is not specified,
108 \fBsd_journal_close()\fR
109 will not close the file descriptor, so the caller should close it after
110 \fBsd_journal_close()\fR\&.
111 .PP
112 \fBsd_journal_open_files()\fR
113 is similar to
114 \fBsd_journal_open()\fR
115 but takes a
116 \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\&.
117 .PP
118 \fBsd_journal_open_files_fd()\fR
119 is similar to
120 \fBsd_journal_open_files()\fR
121 but takes an array of open file descriptors that must reference journal files, instead of an array of file system paths\&. Pass the array of file descriptors as second argument, and the number of array entries in the third\&. The flags parameter must be passed as 0\&.
122 .PP
123 \fIsd_journal\fR
124 objects cannot be used in the child after a fork\&. Functions which take a journal object as an argument (\fBsd_journal_next()\fR
125 and others) will return
126 \fB\-ECHILD\fR
127 after a fork\&.
128 .PP
129 \fBsd_journal_close()\fR
130 will close the journal context allocated with
131 \fBsd_journal_open()\fR
132 or
133 \fBsd_journal_open_directory()\fR
134 and free its resources\&.
135 .PP
136 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\&.
137 .PP
138 See
139 \fBsd_journal_next\fR(3)
140 for an example of how to iterate through the journal after opening it with
141 \fBsd_journal_open()\fR\&.
142 .PP
143 A journal context object returned by
144 \fBsd_journal_open()\fR
145 references a specific journal entry as
146 \fIcurrent\fR
147 entry, similar to a file seek index in a classic file system file, but without absolute positions\&. It may be altered with
148 \fBsd_journal_next\fR(3)
149 and
150 \fBsd_journal_seek_head\fR(3)
151 and related calls\&. The current entry position may be exported in
152 \fIcursor\fR
153 strings, as accessible via
154 \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)
155 \fBsd_journal_seek_cursor\fR(3)\&.
156 .PP
157 Notification of journal changes is available via
158 \fBsd_journal_get_fd()\fR
159 and related calls\&.
160 .SH "RETURN VALUE"
161 .PP
162 The
163 \fBsd_journal_open()\fR,
164 \fBsd_journal_open_directory()\fR, and
165 \fBsd_journal_open_files()\fR
166 calls return 0 on success or a negative errno\-style error code\&.
167 \fBsd_journal_close()\fR
168 returns nothing\&.
169 .SH "NOTES"
170 .PP
171 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\&.
172 .PP
173 Functions described here are available as a shared library, which can be compiled against and linked to with the
174 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
175 file\&.
176 .SH "HISTORY"
177 .PP
178 \fBsd_journal_open()\fR,
179 \fBsd_journal_open_directory()\fR, and
180 \fBsd_journal_close()\fR
181 were added in version 187\&.
182 .PP
183 \fBsd_journal_open_files()\fR
184 was added in version 205\&.
185 .PP
186 \fBsd_journal_open_directory_fd()\fR
187 and
188 \fBsd_journal_open_files_fd()\fR
189 were added in version 230\&.
190 .PP
191 \fBsd_journal_open_namespace()\fR
192 was added in version 245\&.
193 .SH "SEE ALSO"
194 .PP
195 \fBsystemd\fR(1), \fBsd-journal\fR(3), \fBsystemd-journald.service\fR(8), \fBsd_journal_next\fR(3), \fBsd_journal_get_data\fR(3)