mirror of
https://git.proxmox.com/git/systemd
synced 2025-05-29 11:51:49 +00:00
158 lines
6.4 KiB
Groff
158 lines
6.4 KiB
Groff
'\" t
|
|
.TH "SD_JOURNAL_OPEN" "3" "" "systemd 219" "sd_journal_open"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
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
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.ft B
|
|
.nf
|
|
#include <systemd/sd\-journal\&.h>
|
|
.fi
|
|
.ft
|
|
.HP \w'int\ sd_journal_open('u
|
|
.BI "int sd_journal_open(sd_journal\ **" "ret" ", int\ " "flags" ");"
|
|
.HP \w'int\ sd_journal_open_directory('u
|
|
.BI "int sd_journal_open_directory(sd_journal\ **" "ret" ", const\ char\ *" "path" ", int\ " "flags" ");"
|
|
.HP \w'int\ sd_journal_open_files('u
|
|
.BI "int sd_journal_open_files(sd_journal\ **" "ret" ", const\ char\ **" "paths" ", int\ " "flags" ");"
|
|
.HP \w'int\ sd_journal_open_container('u
|
|
.BI "int sd_journal_open_container(sd_journal\ **" "ret" ", const\ char\ *" "machine" ", int\ " "flags" ");"
|
|
.HP \w'void\ sd_journal_close('u
|
|
.BI "void sd_journal_close(sd_journal\ *" "j" ");"
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fBsd_journal_open()\fR
|
|
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
|
|
\fIsd_journal\fR
|
|
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:
|
|
\fBSD_JOURNAL_LOCAL_ONLY\fR
|
|
makes sure only journal files generated on the local machine will be opened\&.
|
|
\fBSD_JOURNAL_RUNTIME_ONLY\fR
|
|
makes sure only volatile journal files will be opened, excluding those which are stored on persistent storage\&.
|
|
\fBSD_JOURNAL_SYSTEM\fR
|
|
will cause journal files of system services and the kernel (in opposition to user session processes) to be opened\&.
|
|
\fBSD_JOURNAL_CURRENT_USER\fR
|
|
will cause journal files of the current user to be opened\&. If neither
|
|
\fBSD_JOURNAL_SYSTEM\fR
|
|
nor
|
|
\fBSD_JOURNAL_CURRENT_USER\fR
|
|
are specified, all journal file types will be opened\&.
|
|
.PP
|
|
\fBsd_journal_open_directory()\fR
|
|
is similar to
|
|
\fBsd_journal_open()\fR
|
|
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\&.
|
|
.PP
|
|
\fBsd_journal_open_files()\fR
|
|
is similar to
|
|
\fBsd_journal_open()\fR
|
|
but takes a
|
|
\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\&.
|
|
.PP
|
|
\fBsd_journal_open_container()\fR
|
|
is similar to
|
|
\fBsd_journal_open()\fR
|
|
but opens the journal files of a running OS container\&. The specified machine name refers to a container that is registered with
|
|
\fBsystemd-machined\fR(8)\&.
|
|
.PP
|
|
\fIsd_journal\fR
|
|
objects cannot be used in the child after a fork\&. Functions which take a journal object as an argument (\fBsd_journal_next()\fR
|
|
and others) will return
|
|
\fB\-ECHILD\fR
|
|
after a fork\&.
|
|
.PP
|
|
\fBsd_journal_close()\fR
|
|
will close the journal context allocated with
|
|
\fBsd_journal_open()\fR
|
|
or
|
|
\fBsd_journal_open_directory()\fR
|
|
and free its resources\&.
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
See
|
|
\fBsd_journal_next\fR(3)
|
|
for an example of how to iterate through the journal after opening it with
|
|
\fBsd_journal_open()\fR\&.
|
|
.PP
|
|
A journal context object returned by
|
|
\fBsd_journal_open()\fR
|
|
references a specific journal entry as
|
|
\fIcurrent\fR
|
|
entry, similar to a file seek index in a classic file system file, but without absolute positions\&. It may be altered with
|
|
\fBsd_journal_next\fR(3)
|
|
and
|
|
\fBsd_journal_seek_head\fR(3)
|
|
and related calls\&. The current entry position may be exported in
|
|
\fIcursor\fR
|
|
strings, as accessible via
|
|
\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)
|
|
\fBsd_journal_seek_cursor\fR(3)\&.
|
|
.PP
|
|
Notification of journal changes is available via
|
|
\fBsd_journal_get_fd()\fR
|
|
and related calls\&.
|
|
.SH "RETURN VALUE"
|
|
.PP
|
|
The
|
|
\fBsd_journal_open()\fR,
|
|
\fBsd_journal_open_directory()\fR, and
|
|
\fBsd_journal_open_files()\fR
|
|
calls return 0 on success or a negative errno\-style error code\&.
|
|
\fBsd_journal_close()\fR
|
|
returns nothing\&.
|
|
.SH "NOTES"
|
|
.PP
|
|
The
|
|
\fBsd_journal_open()\fR,
|
|
\fBsd_journal_open_directory()\fR
|
|
and
|
|
\fBsd_journal_close()\fR
|
|
interfaces are available as a shared library, which can be compiled and linked to with the
|
|
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
|
|
file\&.
|
|
.SH "HISTORY"
|
|
.PP
|
|
\fBsd_journal_open()\fR,
|
|
\fBsd_journal_close()\fR,
|
|
\fBSD_JOURNAL_LOCAL_ONLY\fR,
|
|
\fBSD_JOURNAL_RUNTIME_ONLY\fR,
|
|
\fBSD_JOURNAL_SYSTEM_ONLY\fR
|
|
were added in systemd\-38\&.
|
|
.PP
|
|
\fBsd_journal_open_directory()\fR
|
|
was added in systemd\-187\&.
|
|
.PP
|
|
\fBSD_JOURNAL_SYSTEM\fR,
|
|
\fBSD_JOURNAL_CURRENT_USER\fR, and
|
|
\fBsd_journal_open_files()\fR
|
|
were added in systemd\-205\&.
|
|
\fBSD_JOURNAL_SYSTEM_ONLY\fR
|
|
was deprecated\&.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBsystemd\fR(1),
|
|
\fBsd-journal\fR(3),
|
|
\fBsd_journal_next\fR(3),
|
|
\fBsd_journal_get_data\fR(3),
|
|
\fBsystemd-machined\fR(8)
|