1SD_JOURNAL_OPEN(3) sd_journal_open SD_JOURNAL_OPEN(3)
2
6 sd_journal_open, sd_journal_open_directory,
7 sd_journal_open_directory_fd, sd_journal_open_files,
8 sd_journal_open_files_fd, sd_journal_open_namespace, sd_journal_close,
9 sd_journal, SD_JOURNAL_LOCAL_ONLY, SD_JOURNAL_RUNTIME_ONLY,
10 SD_JOURNAL_SYSTEM, SD_JOURNAL_CURRENT_USER, SD_JOURNAL_OS_ROOT,
11 SD_JOURNAL_ALL_NAMESPACES, SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE,
12 SD_JOURNAL_TAKE_DIRECTORY_FD - Open the system journal for reading
13
15 #include <systemd/sd-journal.h>
16 int sd_journal_open(sd_journal **ret, int flags);
18 int sd_journal_open_namespace(sd_journal **ret, const char *namespace,
20 int flags);
21 int sd_journal_open_directory(sd_journal **ret, const char *path,
23 int flags);
24 int sd_journal_open_directory_fd(sd_journal **ret, int fd, int flags);
26 int sd_journal_open_files(sd_journal **ret, const char **paths,
28 int flags);
29 int sd_journal_open_files_fd(sd_journal **ret, int fds[],
31 unsigned n_fds, int flags);
32 void sd_journal_close(sd_journal *j);
34
36 sd_journal_open() opens the log journal for reading. It will find all
37 journal files automatically and interleave them automatically when
38 reading. As first argument it takes a pointer to a sd_journal pointer,
39 which, on success, will contain a journal context object. The second
40 argument is a flags field, which may consist of the following flags
41 ORed together: SD_JOURNAL_LOCAL_ONLY makes sure only journal files
42 generated on the local machine will be opened. SD_JOURNAL_RUNTIME_ONLY
43 makes sure only volatile journal files will be opened, excluding those
44 which are stored on persistent storage. SD_JOURNAL_SYSTEM will cause
45 journal files of system services and the kernel (in opposition to user
46 session processes) to be opened. SD_JOURNAL_CURRENT_USER will cause
47 journal files of the current user to be opened. If neither
48 SD_JOURNAL_SYSTEM nor SD_JOURNAL_CURRENT_USER are specified, all
49 journal file types will be opened.
50 sd_journal_open_namespace() is similar to sd_journal_open() but takes
52 an additional namespace parameter that specifies which journal
53 namespace to operate on. If specified as NULL the call is identical to
54 sd_journal_open(). If non-NULL only data from the namespace identified
55 by the specified parameter is accessed. This call understands two
56 additional flags: if SD_JOURNAL_ALL_NAMESPACES is specified the
57 namespace parameter is ignored and all defined namespaces are accessed
58 simultaneously; if SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE the specified
59 namespace and the default namespace are accessed but no others (this
60 flag has no effect when namespace is passed as NULL). For details about
61 journal namespaces see systemd-journald.service(8).
62 sd_journal_open_directory() is similar to sd_journal_open() but takes
64 an absolute directory path as argument. All journal files in this
65 directory will be opened and interleaved automatically. This call also
66 takes a flags argument. The flags parameters accepted by this call are
67 SD_JOURNAL_OS_ROOT, SD_JOURNAL_SYSTEM, and SD_JOURNAL_CURRENT_USER. If
68 SD_JOURNAL_OS_ROOT is specified, journal files are searched for below
69 the usual /var/log/journal and /run/log/journal relative to the
70 specified path, instead of directly beneath it. The other two flags
71 limit which files are opened, the same as for sd_journal_open().
72 sd_journal_open_directory_fd() is similar to
74 sd_journal_open_directory(), but takes a file descriptor referencing a
75 directory in the file system instead of an absolute file system path.
76 In addition to the flags accepted by sd_journal_open_directory(), this
77 function also accepts SD_JOURNAL_TAKE_DIRECTORY_FD. If
78 SD_JOURNAL_TAKE_DIRECTORY_FD is specified, the function will take the
79 ownership of the specified file descriptor on success, and it will be
80 closed by sd_journal_close(), hence the caller of the function must not
81 close the file descriptor. When the flag is not specified,
82 sd_journal_close() will not close the file descriptor, so the caller
83 should close it after sd_journal_close().
84 sd_journal_open_files() is similar to sd_journal_open() but takes a
86 NULL-terminated list of file paths to open. All files will be opened
87 and interleaved automatically. This call also takes a flags argument,
88 but it must be passed as 0 as no flags are currently understood for
89 this call. Please note that in the case of a live journal, this
90 function is only useful for debugging, because individual journal files
91 can be rotated at any moment, and the opening of specific files is
92 inherently racy.
93 sd_journal_open_files_fd() is similar to sd_journal_open_files() but
95 takes an array of open file descriptors that must reference journal
96 files, instead of an array of file system paths. Pass the array of file
97 descriptors as second argument, and the number of array entries in the
98 third. The flags parameter must be passed as 0.
99 sd_journal objects cannot be used in the child after a fork. Functions
101 which take a journal object as an argument (sd_journal_next() and
102 others) will return -ECHILD after a fork.
103 sd_journal_close() will close the journal context allocated with
105 sd_journal_open() or sd_journal_open_directory() and free its
106 resources.
107 When opening the journal only journal files accessible to the calling
109 user will be opened. If journal files are not accessible to the caller,
110 this will be silently ignored.
111 See sd_journal_next(3) for an example of how to iterate through the
113 journal after opening it with sd_journal_open().
114 A journal context object returned by sd_journal_open() references a
116 specific journal entry as current entry, similar to a file seek index
117 in a classic file system file, but without absolute positions. It may
118 be altered with sd_journal_next(3) and sd_journal_seek_head(3) and
119 related calls. The current entry position may be exported in cursor
120 strings, as accessible via sd_journal_get_cursor(3). Cursor strings may
121 be used to globally identify a specific journal entry in a stable way
122 and then later to seek to it (or if the specific entry is not available
123 locally, to its closest entry in time) sd_journal_seek_cursor(3).
124 Notification of journal changes is available via sd_journal_get_fd()
126 and related calls.
127
129 The sd_journal_open(), sd_journal_open_directory(), and
130 sd_journal_open_files() calls return 0 on success or a negative
131 errno-style error code. sd_journal_close() returns nothing.
132
134 All functions listed here are thread-agnostic and only a single
135 specific thread may operate on a given object during its entire
136 lifetime. It's safe to allocate multiple independent objects and use
137 each from a specific thread in parallel. However, it's not safe to
138 allocate such an object in one thread, and operate or free it from any
139 other, even if locking is used to ensure these threads don't operate on
140 it at the very same time.
141 Functions described here are available as a shared library, which can
143 be compiled against and linked to with the libsystemd pkg-config(1)
144 file.
145
147 systemd(1), sd-journal(3), systemd-journald.service(8),
148 sd_journal_next(3), sd_journal_get_data(3)
149systemd 254 SD_JOURNAL_OPEN(3)