Struct sd_journal::Journal

pub struct Journal { /* fields omitted */ }

A wrapper for sd-journal as offered by libsystemd based on FFI bindings offered in crate sd-sys.

Journal is a fully implemented, wrapper for submitting and querying log entries from the systemd journal.

Implementations

impl Journal

pub fn log_message<T: Into<Vec<u8>>>(
    level: Level,
    message: T
) -> Result<(), Error>

Submits a simple, plain text log message with a chosen syslog level to the journal (implements sd_journal_print()).

The message submitted to log_message() may be anything that can be turned into a vector of bytes. Journald considers non-UTF-8 values as valid message although 0-bytes within the message cause an error.

Examples

use sd_journal::*;
use std::ffi::CString;
// the following lines are all synonyms
Journal::log_message(Level::Info, "Hello World!").unwrap();
Journal::log_message(Level::Info, String::from("Hello World!").as_str()).unwrap();
Journal::log_message(Level::Info, String::from("Hello World!")).unwrap();
Journal::log_message(Level::Info, CString::new("Hello World!").unwrap()).unwrap();

Return Values

• Ok(): success
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::NullError): the message contained a 0-byte

pub fn log_raw_record<T: AsRef<[u8]>>(data: &[T]) -> Result<(), Error>

Send a raw log record to the journal (implements sd_journal_sendv())

This method may be used to submit structured log entries to the system journal. It takes any slice of byte-slices (e.g. &String or &[&str]).

For libsystemd a single log record consists of multiple tuples each in the format "FIELDNAME=fieldvalue". The field name must be in uppercase and consist only of characters, numbers and underscores, and may not begin with an underscore. All assignments that do not follow this syntax will silently be ignored. A variable may be assigned more than one value per entry. Well known field names are defined in enum Field or may be looked up.

The value can be of any size and format, i.e. the data encoding may differ from UTF8 and may contain binary coding.

Examples

use sd_journal::*;
// the first two lines are synonyms
Journal::log_message(Level::Info, "Hello World!").unwrap();
Journal::log_raw_record(&["PRIORITY=6", "MESSAGE=Hello World!"]).unwrap();
// data: &Vec<String>
Journal::log_raw_record(&vec![format!("PRIORITY={}", Level::Info),
                              "MESSAGE=Hello World!".to_string(),
                              format!("CODE_LINE={}", line!()),
                              format!("CODE_FILE={}", file!()),
                              "CUSTOM_FIELD=42".to_string()]).unwrap();
// data: &[&str]
Journal::log_raw_record(&["MESSAGE=Hello World!",
                          &format!("PRIORITY={}", Level::Info),
                          &format!("CODE_FILE={}", file!()),
                          &format!("CODE_LINE={}", line!()),
                          "CUSTOM_FIELD=42"]).unwrap();

Return Values

• Ok(): success
• Err(Error::SDError): sd-journal returned an error code

pub fn get_catalog_for_message_id(id: ID128) -> Result<String, Error>

Determine the message cataloge entry for a message id (implements sd_journal_get_catalog_for_message_id()).

Return Values

• Ok(String): message catalogue
• Err(Error::UTF8Error): UTF-8 decoding error occured
• Err(Error::SDError): sd-journal returned an error code

pub fn open(
    file_flags: FileFlags,
    user_flags: UserFlags
) -> Result<Journal, Error>

Open a journal for read access (implements sd_journal_open()).

Opens the log journal for reading. It will find all journal files and interleave them automatically when reading.

Examples

use sd_journal::*;
Journal::open(FileFlags::AllFiles, UserFlags::AllUsers).unwrap();
Journal::open(FileFlags::LocalOnly, UserFlags::CurrentUserOnly).unwrap();

Return values

• Ok(Journal): initialized journal
• Err(Error::SDError): sd-journal returned an error code

pub fn open_namespace<T: Into<Vec<u8>>>(
    namespace: T,
    namespace_flags: NamespaceFlags,
    file_flags: FileFlags,
    user_flags: UserFlags
) -> Result<Journal, Error>

Open the journal for reading records in a specific namespace (implements sd_journal_open_namespace()).

Opens the log journal for reading on a selected namespace only. It will find all journal files and interleave them automatically when reading. This method does not support the SD_JOURNAL_ALL_NAMESPACES flag. If you want to open all namespaces, see open_all_namespaces().

Return values

• Ok(Journal): initialized journal
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::NullError): the namespace contained a 0-byte

pub fn open_all_namespaces(
    file_flags: FileFlags,
    user_flags: UserFlags
) -> Result<Journal, Error>

Open the journal for read access including all available namespaces (implements sd_journal_open_namespace() with flag SD_JOURNAL_ALL_NAMESPACES set).

Opens the log journal for reading for all namespaces. It will find all journal files automatically and interleave them automatically when reading.

Return values

• Ok(Journal): initialized journal
• Err(Error::SDError): sd-journal returned an error code

pub fn open_directory<P: Into<PathBuf>>(
    path: P,
    path_flags: PathFlags,
    user_flags: UserFlags
) -> Result<Journal, Error>

Open the journal located at a specific path (implements sd_journal_open_directory()).

Open the journal located at a specific path: takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved automatically.

Examples

use sd_journal::*;
use std::path::{Path, PathBuf};
// open the system journal by pointing to root with path flags set to
// PathToOSRoot
Journal::open_directory("/", PathFlags::PathToOSRoot, UserFlags::AllUsers).unwrap();
Journal::open_directory(Path::new("/"), PathFlags::PathToOSRoot, UserFlags::AllUsers).unwrap();
Journal::open_directory(PathBuf::from("/"),
                        PathFlags::PathToOSRoot,
                        UserFlags::AllUsers).unwrap();
// open test data included in a project located in a folder "test-data" in the
// project root
let mut test_data = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
test_data.push("test-data/");
println!("looking for test data in folder {}", test_data.display());
Journal::open_directory(test_data, PathFlags::FullPath, UserFlags::AllUsers).unwrap();

Return values

• Ok(Journal): initialized journal
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::NullError): the path contains a 0-byte

pub fn open_files<A: Into<Vec<P>>, P: Into<PathBuf>>(
    files: A
) -> Result<Journal, Error>

Open the journal stored in a list of files (implements sd_journal_open_files()).

Examples

use sd_journal::*;
use std::path::PathBuf;
// to open the curreńt system.journal file in the default location for
// journals: /var/log/journal/<MACHINE-ID>/system.journal
let machine_id = sd_id128::ID128::machine_id().unwrap()
                                              .to_string_sd()
                                              .unwrap();
let mut sdjournal_path = PathBuf::from("/var/log/journal/");
sdjournal_path.push(&machine_id);
sdjournal_path.push("system.journal");
println!("looking for sd-journal in {}", sdjournal_path.display());
Journal::open_files([sdjournal_path]).unwrap();
// to open test data included in a project located in a folder
// "test-data" in the project root
let mut test_data = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
test_data.push("test-data/test.journal");
println!("looking for test data in folder {}", test_data.display());
Journal::open_files([test_data]).unwrap();

Return values

• Ok(Journal): initialized journal
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::NullError): a file path contains a 0-byte

pub fn next(&self) -> Result<CursorMovement, Error>

Advance the read pointer of the journal by one entry (implements sd_journal_next()).

This method wraps the sd-journal native function. There is also a rustified iterator CursorIterator avalaible via the iter() method or the IntoIterator trait implemented for &Journal. Although the official documentation doesn't mention any error handling, libsystemd may return an error on performing next().

Examples

// loop over a journal & print it's messages
while let Ok(CursorMovement::Done) = journal.next() {
    // do something on each cursor, e.g. print the MESSAGE
    println!("{}", journal.get_data("MESSAGE").unwrap());
}

Return values

• Ok(CursorMovement::Done): full success
• Ok(CursorMovement::EoF): no movement was executed, since the cursor is already placed at EoF.
• Err(Error::SDError): sd-journal returned an error code

pub fn iter(&self) -> CursorIterator<'_>

Returns an iterator on the journal.

CursorIterator is the rustified version of the next() method. Since next() may fail, the advanced cursor may be invalid. For such reason, the iterator returns a Result<Cursor, _> on each next() and thus the cursor must be unwrapped first.

Examples

// loop over a journal & print it's messages
for cursor in journal.iter() {
    match cursor {
        Err(_) => break,
        Ok(cursor) => println!("{}", cursor.get_data("MESSAGE").unwrap())
    }
}
// ...
let cursor = journal.iter_reverse().next().unwrap().unwrap();
// the following two lines are actually return the same value
let m1 = cursor.get_data("MESSAGE").unwrap();
let m2 = journal.get_data("MESSAGE").unwrap();
assert_eq!(m1, m2);

pub fn previous(&self) -> Result<CursorMovement, Error>

Set back the read pointer of the journal by one entry (implements sd_journal_previous()).

This method wraps the sd-journal native function. There is also a rustified iterator CursorReverseIterator avalaible via the iter_reverse() method.

Examples

journal.seek_tail().unwrap();
// loop over a journal in reverse order & print it's messages
while let Ok(CursorMovement::Done) = journal.previous() {
    // do something on each cursor, e.g. print the MESSAGE
    println!("{}", journal.get_data("MESSAGE").unwrap());
}

Return values

• Ok(CursorMovement::Done): full success
• Ok(CursorMovement::EoF): no movement was executed, since the cursor is already placed at EoF.
• Err(Error::SDError): sd-journal returned an error code

pub fn iter_reverse(&self) -> CursorReverseIterator<'_>

Returns an iterator on the journal that runs in reverse order.

CursorReverseIterator is the rustified version of the previous() method. Since previous() may fail, the advanced cursor may be invalid. For such reason, the iterator returns a Result<Cursor, _> on each next() and thus the cursor must be unwrapped first.

Examples

journal.seek_tail().unwrap();
// loop over a journal & print it's messages
for cursor in journal.iter_reverse() {
    match cursor {
        Err(_) => break,
        Ok(cursor) => println!("{}", cursor.get_data("MESSAGE").unwrap())
    }
}
// ...
let cursor = journal.iter_reverse().next().unwrap().unwrap();
// the following two lines are actually return the same value
let m1 = cursor.get_data("MESSAGE").unwrap();
let m2 = journal.get_data("MESSAGE").unwrap();
assert_eq!(m1, m2);

pub fn next_skip(&self, skip: c_int) -> Result<CursorMovement, Error>

Advance the read pointer of the journal by multiple entries (implements sd_journal_next_skip()).

Return values

• Ok(CursorMovement::Done): full success
• Ok(CursorMovement::Limited(actual)): the movement was executed but limited by the EoF of the journal. The actual movement is given in the parameter.
• Ok(CursorMovement::EoF): no movement was executed, since the cursor is already placed at EoF.
• Err(Error::SDError): sd-journal returned an error code

pub fn previous_skip(&self, skip: c_int) -> Result<CursorMovement, Error>

Set back the read pointer by multiple entries at once (implements sd_journal_previous_skip()).

• Ok(CursorMovement::Done): full success
• Ok(CursorMovement::Limited(actual)): the movement was executed but limited by the EoF of the journal. The actual movement is given in the parameter.
• Ok(CursorMovement::EoF): no movement was executed, since the cursor is already placed at EoF.
• Err(Error::SDError): sd-journal returned an error code

pub fn seek_head(&self) -> Result<(), Error>

UNSTABLE API Seek to the head of the journal (implements sd_journal_seek_head).

Seek to the beginning of the journal, i.e. to the position before the oldest available entry. Be aware that after a seek_head() the journal cursor does not point to a valid entry. One must perform a cursor movement before being able to retrieve data.

Examples

journal.seek_head().unwrap();
// seek_head() should be followed by a next() before any previous() --> issues
journal.next().unwrap();
// previous() should hit EoF
assert_eq!(journal.previous(), Ok(CursorMovement::EoF));

libsystemd Issues

While seek_head() is supposed to move the cursor before the first available journal entry, libsystemd may still successfully perform previous() cursor movements for multiple times. All these unexpected entries will report a full set of data and may appear fully valid although be assured they are not. An error has been reported to the systemd project. The issue can be avoided if a next() operation is executed immediately after seek_head() before issuing any previous(). If done, previous()thereafter will correctly report EoF.

Stability

Due to the issue described above, this method may be changed in future to include a next() in future releases and thus position the cursor rather on the first available entry rather than positioning the cursor before the oldest available entry. Such change is likely and will be based on the issue handling of the systemd team as well as on user feedback.

Return values

• Ok(()): success
• Err(Error::SDError): sd-journal returned an error code

pub fn seek_tail(&self) -> Result<(), Error>

UNSTABLE API Seek to the tail of the journal (implements sd_journal_seek_tail).

Seek to the end of the journal, i.e. the position after the most recent available entry. Be aware that after a seek_head() the journal cursor does not point to a valid entry. One must perform a cursor movement before being able to retrieve data.

Examples

journal.seek_tail().unwrap();
// seek_head() should be followed by a previous() before any next() --> issues
journal.previous().unwrap();
// next() should hit EoF
assert_eq!(journal.next(), Ok(CursorMovement::EoF));

libsystemd Issues

While seek_head() is supposed to move the cursor before the first available journal entry, libsystemd may still successfully perform previous() cursor movements for multiple times. All these unexpected entries will report a full set of data and may appear fully valid although be assured they are not. An error has been reported to the systemd project. The issue can be avoided if a next() operation is executed immediately after seek_head() before issuing any previous(). If done, previous()thereafter will correctly report EoF.

Stability

Due to the issue described above, this method may be changed in future to include a next() in future releases and thus position the cursor rather on the first available entry rather than positioning the cursor before the oldest available entry. Such change is likely and will be based on the issue handling of the systemd team as well as on user feedback.

Return values

• Ok(()): success
• Err(Error::SDError): sd-journal returned an error code

pub fn seek_monotonic(
    &self,
    boot_id: ID128,
    clock_monotonic: Duration
) -> Result<(), Error>

UNSTABLE API Seek to a monotonic timestamp of a certain boot id (implements sd_journal_seek_monotonic_usec()).

Seek to a position with the specified monotonic timestamp, i.e. `clockMonotonic'. Since monotonic time restarts on every reboot a boot ID needs to be specified as well.

Examples

use sd_id128::*;
use sd_journal::*;
let journal = Journal::open(FileFlags::AllFiles, UserFlags::AllUsers).unwrap();
// get the current system boot id
let boot_id = ID128::boot_id().unwrap();
// get the monotonic clock range of today
let (from, _) = journal.get_monotonic_cutoff(boot_id.clone()).unwrap();
// seek to the start of journal for the current boot
journal.seek_monotonic(boot_id.clone(), from).unwrap();
journal.previous().unwrap();
// do something with the first cursor of today...

libsystemd Issues

According to the specification of sd_journal_seek_monotonic_usec():

If no entry exists that matches exactly the specified seek address, the next closest is sought to.

Unfortunately libsystemd fails to comply if the monotonic timestamp provided points to a position outside the journal range. Lets assume the first valid log entry for a certain boot id exists at timestamp 500usec. Seeking to anything beyond 500usec will work as expected while seeking to anything before 500usec followed by a next() won't position the cursor at the first entry of that boot id but rather position the cursor at some random position. An issue has been reported to the systemd project.

Stability

This method expects chrono::Duration in the same way as get_monotonic() for the same reasons: get_realtime() refers to chrono::NaiveDateTime. In future releases this method may be changed to microsenconds (u128) or std::time::Duration. Such change is reasonable likely and will be made based on user feedback.

Return values

• Ok(())
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::TimeStampOutOfRange): the clock_monotonic time stamp either reflects a negative duration or the duration exceeds i64 microseconds

pub fn seek_realtime(&self, clock_realtime: NaiveDateTime) -> Result<(), Error>

UNSTABLE API Seek to realtime timestamp (implements sd_journal_seek_realtime_usec()).

Seeks to a position with the specified realtime (wallclock) timestamp, i.e. 'clockRealtime'. Note that the realtime clock is not necessarily monotonic. If a realtime timestamp is ambiguous, it is not defined which position is sought to.

Stability

Currently the function expects a chrono::NaiveDateTime. In future releases this method may be changed to expect microseconds (u128) or std::time::Duration although this is very unlikely. Changes will be made based on user feedback.

Return values

• Ok(())
• Err(Error::SDError): sd-journal returned an error code

pub fn seek_cursor_id(&self, cursor_id: String) -> Result<(), Error>

UNSTABLE API Seeks the journal to the position of the cursor provided (implements sd_journal_seek_cursor()).

Stability

See get_cursor_id() for reasons why there is a small chance this method may be adjusted in future releases.

Return Values

• Ok(())
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::NullError): a file path contains a 0-byte

pub fn add_match<T: AsRef<[c_uchar]>>(&self, filter: T) -> Result<(), Error>

Adds a match to filter journal entries (implements sd_journal_add_match()).

Adds a filter on a field that will be applied on cursor movement thereafter. The filter must follow the format "FIELDNAME=fieldvalue".

Examples

journal.add_match("MESSAGE=Hello World!").unwrap();
while let Ok(CursorMovement::Done) = journal.next() {
    // do something on the journal entries
}

Return Values

• Ok(()): done
• Err(Error::SDError): sd-journal returned an error code

pub fn add_disjunction(&self) -> Result<(), Error>

Adds a disjuntion marker to match definitions (implements sd_jounal_add_disjunction().)

Return Values

• Ok(()): done
• Err(Error::SDError): sd-journal returned an error code

pub fn add_conjunction(&self) -> Result<(), Error>

Adds a conjuntion marker to match definitions (implements sd_jounal_add_conjunction().)

Return Values

• Ok(()): done
• Err(Error::SDError): sd-journal returned an error code

pub fn flush_matches(&self)

Flushes the match definition (implements sd_journal_flush_matches())

pub fn get_realtime_cutoff(
    &self
) -> Result<(NaiveDateTime, NaiveDateTime), Error>

UNSTABLE API Determines the timestamps of the first and last entry in journal (implements sd_journal_get_cutoff_realtime_usec).

Stability

Currently the function returns a chrono::NaiveDateTime calculated from the microseconds since EPOCH returned by the wrapped libsystemd function. In future releases this method may be changed to return microseconds (u128) or std::time::Duration although this is very unlikely. Changes will be made based on user feedback.

Return Values:

• Ok((NaiveDateTime, NaiveDateTime)): (from, to) timestamps of the journal
• Err(Error::SDError): sd-journal returned an error code

pub fn get_monotonic_cutoff(
    &self,
    boot_id: ID128
) -> Result<(Duration, Duration), Error>

UNSTABLE API Determines the duration since boot of the first and last entry in journal for a specific boot id (implements sd_journal_get_cutoff_realtime_usec()).

Stability

Currently the function returns a chrono::Duration calculated from the microseconds since boot returned by the wrapped libsystemd function. The choice for chrono::Duration has been made based on the return value for get_realtime(). In future releases this method may be changed to microsenconds (u128) or std::time::Duration. Such change is reasonable likely and will be made based on user feedback.

Return Values

• Ok((Duration, Duration)): (from, to) respective duration since boot
• Err(Error::SDError): sd-journal returned an error code

pub fn set_data_treshold(&self, size: size_t) -> Result<(), Error>

Sets the data treshold limit for certain methods returning data fields (implements sd_journal_set_data_threshold()).

Return Values

• Ok(())
• Err(Error::SDError): sd-journal returned an error code

pub fn get_data_treshold(&self) -> Result<size_t, Error>

Gets the currently applied data treshold (implements sd_journal_get_data_threshold()).

Return Values

• Ok(size_t)
• Err(Error::SDError): sd-journal returned an error code

pub fn enumerate_field_names(&self) -> Result<Enumeration<String>, Error>

Enumerate the field names of the journal (implements sd_journal_enumerate_fields()).

This method follows the principle of libsystemd to call this method repeatedly until you reach EoF. See iter_fields for a rustified iterator over fields.

Return Values

• Ok(Enumeration::EoF): no more fields
• Ok(Enumeration::Value(String)): field name
• Err(Error::SDError): sd-journal returned an error code

pub fn restart_field_name_enumeration(&self)

Restart field enumeration (implements sd_journal_restart_fields()).

pub fn iter_field_names<'a>(&'a self) -> FieldNames<'a>

Get an iterator of the field names of the journal.

This is the rustified version of enumerate_field_names().

Examples

// loop over field names and print them
for fieldname in journal.iter_field_names() {
    println!("{}", fieldname.unwrap());
}

pub fn get_fd(&self) -> Result<RawFd, Error>

Returns a read only file descriptor to be used in polling the journal (implements sd_journal_get_fd()).

Return Values

• Ok(RawFd)
• Err(Error::SDError): sd-journal returned an error code

pub fn get_events(&self) -> Result<c_int, Error>

Returns events to be used in polling the journal on the file descriptor (implements sd_journal_get_events()).

Return Values

• Ok(c_int): events to be used in polling the file descriptor
• Err(Error::SDError): sd-journal returned an error code

pub fn get_timeout(&self) -> Result<u64, Error>

Returns the timeout to be used in polling the journal on the file descriptor (implements sd_journal_get_timeout()).

Return Values

• Ok(u64): timeout
• Err(Error::SDError): sd-journal returned an error code

pub fn process(&self) -> Result<Event, Error>

Processes events after each wake-up and returns the type of events (implements sd_journal_process()).

Return Values

• Ok(Event): journal wake event
• Err(Error::SDError): sd-journal returned an error code

pub fn wait(&self, timeout: u64) -> Result<Event, Error>

Wait for changes in the journal for a maximum period defined in timeout (implements sd_journal_wait()).

Use uint64_t-1 for timeout to wait indefinitely.

Return Values

• Ok(Event): journal wake event
• Err(Error::SDError): sd-journal returned an error code

pub fn has_runtime_files(&self) -> Result<bool, Error>

Checks whether the journal owns runtime files (implements sd_journal_has_runtime_files()).

Return Values

• Ok(bool)
• Err(Error::SDError): sd-journal returned an error code

pub fn has_persistent_files(&self) -> Result<bool, Error>

Checks whether the journal owns persistent files (implements sd_journal_has_persistent_files()).

Return Values

• Ok(bool)
• Err(Error::SDError): sd-journal returned an error code

pub fn get_usage(&self) -> Result<u64, Error>

UNSTABLE API Determines the disk space used by the journal in Bytes (implements sd_journal_get_usage()).

Stability

Currently a plain u64 is returned. There is a reasonable chance for a change in future releases towards a SI unit type.

Return Values

• Ok(u64): space required in Bytes
• Err(Error::SDError): sd-journal returned an error code

pub fn get_realtime(&self) -> Result<NaiveDateTime, Error>

UNSTABLE API Retrieves the realtime timestamp as chrono::NaiveDateTime of the current record (implements sd_journal_get_realtime_usec()).

Stability

Currently the function returns a chrono::NaiveDateTime calculated from the microseconds since EPOCH returned by the wrapped libsystemd function. In future releases this method may be changed to return microseconds (u128) or std::time::Duration although this is very unlikely. Changes will be made based on user feedback.

Return Values:

• Ok(NaiveDateTime): realtime timestamp of current record
• Err(Error::SDError): sd-journal returned an error code

pub fn get_monotonic(&self) -> Result<(Duration, ID128), Error>

UNSTABLE API Retrieves the monotonic timestamp of the current record altogether with it's boot id (implements sd_journal_get_monotonic_usec()).

Stability

Currently the function returns a chrono::Duration calculated from the microseconds since boot returned by the wrapped libsystemd function. The choice for chrono::Duration has been made based on the return value for get_realtime(). In future releases this method may be changed to microsenconds (u128) or std::time::Duration. Such change is reasonable likely and will be made based on user feedback.

Return Values

• Ok(chrono::Duration, ID128): tuple of a monotonic timestamp since boot and boot id
• Err(Error::SDError): sd-journal returned an error code

pub fn get_cursor_id(&self) -> Result<String, Error>

UNSTABLE API Retrieve a text representation of the cursor (implements sd_journal_get_cursor()).

Stability

sd_journal_get_cursor() returns a ownership of a memory location. Currently the content is copied into a rustified String and the memory freed immediately. In future releases a new data type could be defined which avoids the immediate conversion into a String. The new data type could be handed over into seek_cursor(). The chance for such change is low. The decission will be taken based on typical usage scenarios and user feedback.

Return values

• Ok(String): cursor representation of sd-journal
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::UTF8Error): UTF-8 decoding error occured; although this should never happen since the journal internal cursor id is stored in valid UTF-8

pub fn cursor_id_matches<S: Into<Vec<u8>>>(
    &self,
    cursor_id: S
) -> Result<bool, Error>

UNSTABLE API Checks whether the current journal position matches a cursor id (implements sd_journal_get_cursor).

Stability

See get_cursor_id() for reasons why there is a small chance this method may be adjusted in future releases.

Return Values

• Ok(bool)
• Err(Error::SDError): sd-journal returned an error code

pub fn get_catalog(&self) -> Result<String, Error>

Determine the message cataloge entry for the current record (implements sd_journal_get_catalog()).

Return Values

• Ok(String): message catalogue
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::UTF8Error): UTF-8 decoding error occured

pub fn get_data<F: Into<Vec<u8>>>(&self, field: F) -> Result<String, Error>

Retrieve the data of a specific field (implements sd_journal_get_data()).

Retrieve the data of a specific field. The fieldname must be provided in all upper case letters. See the documentation of well-known field names. Field names may not contain 0x00 bytes (would raise a NullError). If the current entry does not contain the field, an SDError(-2) is returned.

Examples

// loop over the journal and print the timestamp and message of each record
for cursor in &journal {
    let cursor = cursor.unwrap();
    let message = cursor.get_data("MESSAGE")
                        .unwrap_or("[no message available]".to_string());
    let datetime = cursor.get_realtime().unwrap();
    println!("{} - {}", datetime, message);
}

Return values

• Ok(String): value in the format FIELDNAME=FIELDVALUE
• Err(Error::NullError): the requested field name contains 0-bytes
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::UTF8Error): UTF-8 decoding error occured
• Err(Error::UnexpectedDataFormat): libsystemd is expected to return data in the format FIELDNAME=field value. Before returning that data, FIELDNAME= are stripped of. If that operation fails, this error is raised.
• Err(Error::StringError): if this error is raised, please report an issue against sd_journal

pub fn enumerate_fields(&self) -> Result<Enumeration<(String, String)>, Error>

Enumerate the fields of the current record (implements sd_journal_enumerate_data()).

This is the libsystemd way of iterating over fields. There is also a rustified alternative method iter_fields().

Examples

// loop over all fields of the current record and print FIELDNAME: field value
while let Ok(Enumeration::Value((field, value))) = journal.enumerate_fields() {
    println!("{}: {}", field, value)
}

Return values

• Ok(Enumeration::Value(String, String)): field name and value
• Ok(Enumeration::EoF): no more fields to enumerate
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::UTF8Error): UTF-8 decoding error occured
• Err(Error::UnexpectedDataFormat): libsystemd is expected to return data in the format FIELDNAME=field value. Field name and value are separated at the =. If the format does not match, this error is raised.

pub fn enumerate_available_fields(
    &self
) -> Result<Enumeration<(String, String)>, Error>

Enumerate the available & supported fields of the current record (implements sd_journal_enumerate_available_data()).

Return values

• Ok(Enumeration::Value(String, String)): field name and value
• Ok(Enumeration::EoF): no more fields to enumerate
• Err(Error::SDError): sd-journal returned an error code
• Err(Error::UTF8Error): UTF-8 decoding error occured
• Err(Error::UnexpectedDataFormat): libsystemd is expected to return data in the format FIELDNAME=field value. Field name and value are separated at the =. If the format does not match, this error is raised.

pub fn restart_fields_enumeration(&self)

Restart enumeration of fields (implements sd_journal_restart_data).

pub fn iter_fields<'a>(&'a self) -> Fields<'a>

Returns an iterator over the fields of the current records.

Examples

let journal = Journal::open(FileFlags::AllFiles, UserFlags::AllUsers).unwrap();
// The following 2 loops are synonyms
while let Ok(Enumeration::Value((field, value))) = journal.enumerate_fields() {
    println!("{}: {}", field, value);
}
for field in journal.iter_fields() {
    let (field, value) = field.unwrap();
    println!("{}: {}", field, value);
}

pub fn query_unique_values<S: Into<Vec<u8>>>(
    &self,
    field: S
) -> Result<(), Error>

Query the journal for unique field values of a certain field (implements sd_journal_query_unique()).

libsystemd Issues

sd_journal_query_unique() and the related functions do not always succeed to return unique values, i.e. a value may be returned repeatedly. An issue has been reported.

Return Values

• Ok(())
• Err(Error::SDError): sd-journal returned an error code

pub fn enumerate_unique_values(&self) -> Result<Enumeration<String>, Error>

Enumerate all unique values for the field requested (implements sd_journal_enumerate_unique).

Return Values

• Ok(Enumeration::Value(String)): value
• Ok(Enumeration::EoF): no more unique values to enumerate
• Err(Error::UTF8Error): UTF-8 decoding error occured
• Err(Error::SDError): sd-journal returned an error code

pub fn enumerate_available_unique_values(
    &self
) -> Result<Enumeration<String>, Error>

Enumerate available unique values for the field requested (implements sd_journal_enumerate_available_unique).

Return Values:

• Ok(Enumeration::Value(String)): value
• Ok(Enumeration::EoF): no more unique values to enumerate
• Err(Error::UTF8Error): UTF-8 decoding error occured
• Err(Error::SDError): sd-journal returned an error code

pub fn restart_unique_value_enumeration(&self)

Restart enumeration of unique values (implements sd_journal_restart_unique).

pub fn iter_unique_values<'a, S: Into<Vec<u8>>>(
    &'a self,
    field: S
) -> Result<UniqueValues<'a>, Error>

Returns an iterator over unique values of a field.

Examples

for value in journal.iter_unique_values("MESSAGE").unwrap() {
    let value = value.unwrap();
    println!("{}", value);
}

Return Values

• Ok(UniqueValues)
• Err(Error::SDError): sd-journal returned an error code

Trait Implementations

impl Debug for Journal

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> IntoIterator for &'a Journal

type IntoIter = CursorIterator<'a>

Which kind of iterator are we turning this into?

type Item = Result<Cursor<'a>, Error>

The type of the elements being iterated over.

pub fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.