# sd_journal_open

## NAME



           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
    


## SYNOPSIS



           **#include <systemd/sd-journal.h>**
    
           **int sd_journal_open(sd_journal ****_ret_**, int** _flags_**);**
    
           **int sd_journal_open_namespace(sd_journal ****_ret_**,**
                                         **const char ***_namespace_**, int** _flags_**);**
    
           **int sd_journal_open_directory(sd_journal ****_ret_**, const char ***_path_**,**
                                         **int** _flags_**);**
    
           **int sd_journal_open_directory_fd(sd_journal ****_ret_**, int** _fd_**,**
                                            **int** _flags_**);**
    
           **int sd_journal_open_files(sd_journal ****_ret_**, const char ****_paths_**,**
                                     **int** _flags_**);**
    
           **int sd_journal_open_files_fd(sd_journal ****_ret_**, int** _fds[]_**,**
                                        **unsigned** _n_fds_**, int** _flags_**);**
    
           **void sd_journal_close(sd_journal ***_j_**);**
    


## DESCRIPTION



           **sd_journal_open()** 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 _sd_journal_
           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: **SD_JOURNAL_LOCAL_ONLY** makes sure
           only journal files generated on the local machine will be opened.
           **SD_JOURNAL_RUNTIME_ONLY** makes sure only volatile journal files
           will be opened, excluding those which are stored on persistent
           storage.  **SD_JOURNAL_SYSTEM** will cause journal files of system
           services and the kernel (in opposition to user session processes)
           to be opened.  **SD_JOURNAL_CURRENT_USER** will cause journal files of
           the current user to be opened. If neither **SD_JOURNAL_SYSTEM** nor
           **SD_JOURNAL_CURRENT_USER** are specified, all journal file types will
           be opened.
    
           **sd_journal_open_namespace()** is similar to **sd_journal_open()** but
           takes an additional _namespace_ parameter that specifies which
           journal namespace to operate on. If specified as **NULL** the call is
           identical to **sd_journal_open()**. If non-**NULL** only data from the
           namespace identified by the specified parameter is accessed. This
           call understands two additional flags: if
           **SD_JOURNAL_ALL_NAMESPACES** is specified the _namespace_ parameter is
           ignored and all defined namespaces are accessed simultaneously; if
           **SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE** the specified namespace and
           the default namespace are accessed but no others (this flag has no
           effect when _namespace_ is passed as **NULL**). For details about
           journal namespaces see systemd-journald.service(8).
    
           **sd_journal_open_directory()** is similar to **sd_journal_open()** 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 **SD_JOURNAL_OS_ROOT** , **SD_JOURNAL_SYSTEM** , and
           **SD_JOURNAL_CURRENT_USER**. If **SD_JOURNAL_OS_ROOT** is specified,
           journal files are searched for below the usual /var/log/journal
           and /run/log/journal relative to the specified path, instead of
           directly beneath it. The other two flags limit which files are
           opened, the same as for **sd_journal_open()**.
    
           **sd_journal_open_directory_fd()** is similar to
           **sd_journal_open_directory()** , 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
           **sd_journal_open_directory()** , this function also accepts
           **SD_JOURNAL_TAKE_DIRECTORY_FD**. If **SD_JOURNAL_TAKE_DIRECTORY_FD** is
           specified, the function will take the ownership of the specified
           file descriptor on success, and it will be closed by
           **sd_journal_close()** , hence the caller of the function must not
           close the file descriptor. When the flag is not specified,
           **sd_journal_close()** will not close the file descriptor, so the
           caller should close it after **sd_journal_close()**.
    
           **sd_journal_open_files()** is similar to **sd_journal_open()** but takes
           a **NULL** -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.
    
           **sd_journal_open_files_fd()** is similar to **sd_journal_open_files()**
           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.
    
           _sd_journal_ objects cannot be used in the child after a fork.
           Functions which take a journal object as an argument
           (**sd_journal_next()** and others) will return **-ECHILD** after a fork.
    
           **sd_journal_close()** will close the journal context allocated with
           **sd_journal_open()** or **sd_journal_open_directory()** and free its
           resources.
    
           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.
    
           See sd_journal_next(3) for an example of how to iterate through
           the journal after opening it with **sd_journal_open()**.
    
           A journal context object returned by **sd_journal_open()** references
           a specific journal entry as _current_ entry, similar to a file seek
           index in a classic file system file, but without absolute
           positions. It may be altered with sd_journal_next(3) and
           sd_journal_seek_head(3) and related calls. The current entry
           position may be exported in _cursor_ strings, as accessible via
           sd_journal_get_cursor(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) sd_journal_seek_cursor(3).
    
           Notification of journal changes is available via
           **sd_journal_get_fd()** and related calls.
    


## RETURN VALUE



           The **sd_journal_open()** , **sd_journal_open_directory()** , and
           **sd_journal_open_files()** calls return 0 on success or a negative
           errno-style error code.  **sd_journal_close()** returns nothing.
    


## NOTES



           All functions listed here are thread-agnostic and only a single
           specific thread may operate on a given object during its entire
           lifetime. It is safe to allocate multiple independent objects and
           use each from a specific thread in parallel. However, it is not
           safe to allocate such an object in one thread, and operate or free
           it from any other, even if locking is used to ensure these threads
           do not operate on it at the very same time.
    
           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    


* * *