X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_journal_open.xml;h=2d1dbc32f8a1619c9c06646c311ab2ee2a9b4800;hp=ffd9a2c481eefecc93de3fd758bd854fd3264ce2;hb=4c213d6cf416917c61f82d8bee795b8f3a4c5372;hpb=976c46f84f896782fa1e839904ab74cc4460c7b0 diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index ffd9a2c48..2d1dbc32f 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -45,11 +45,14 @@ 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_ONLY + SD_JOURNAL_SYSTEM + SD_JOURNAL_CURRENT_USER Open the system journal for reading @@ -59,20 +62,34 @@ int sd_journal_open - sd_journal** ret + sd_journal **ret int flags int sd_journal_open_directory - sd_journal** ret - const char* path + sd_journal **ret + const char *path int flags - int sd_journal_close - sd_journal* j + int sd_journal_open_files + sd_journal **ret + const char **paths + int flags + + + + int sd_journal_open_container + sd_journal **ret + const char *machine + int flags + + + + void sd_journal_close + sd_journal *j @@ -80,23 +97,27 @@ Description - sd_journal_open() opens the + 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 journal context object afterwards. The + 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 + SD_JOURNAL_LOCAL_ONLY makes sure only journal files generated on the local machine will - be opened. SD_JOURNAL_RUNTIME_ONLY + be opened. SD_JOURNAL_RUNTIME_ONLY makes sure only volatile journal files will be opened, - excluding those which are stored on persistant - storage. SD_JOURNAL_SYSTEM_ONLY - will ensure that only journal files of system services - and the kernel (in opposition to user session processes) 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_directory() is similar to sd_journal_open() @@ -106,6 +127,32 @@ flags argument, but it must be passed as 0 as no flags are currently understood for this call. + 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_container() + is similar to sd_journal_open() + but opens the journal files of a running + OS container. The specified machine name refers to a + container that is registered with + systemd-machined8. + + 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 @@ -114,13 +161,13 @@ 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 + journal files are not accessible to the caller, this will be silently ignored. See sd_journal_next3 - for an example how to iterate through the journal - after opening it it with + for an example of how to iterate through the journal + after opening it with sd_journal_open(). A journal context object returned by @@ -150,8 +197,9 @@ Return Value - The sd_journal_open() and - sd_journal_open_directory() calls + 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. @@ -163,13 +211,33 @@ The sd_journal_open(), sd_journal_open_directory() and sd_journal_close() interfaces are - available as shared library, which can be compiled and + available as a shared library, which can be compiled and linked to with the - libsystemd-journal - pkg-config1 + libsystemd pkg-config1 file. + + History + + sd_journal_open(), + sd_journal_close(), + SD_JOURNAL_LOCAL_ONLY, + SD_JOURNAL_RUNTIME_ONLY, + SD_JOURNAL_SYSTEM_ONLY were added + in systemd-38. + + sd_journal_open_directory() + was added in systemd-187. + + SD_JOURNAL_SYSTEM, + SD_JOURNAL_CURRENT_USER, + and sd_journal_open_files() + were added in systemd-205. + SD_JOURNAL_SYSTEM_ONLY + was deprecated. + + See Also @@ -177,7 +245,8 @@ systemd1, sd-journal3, sd_journal_next3, - sd_journal_get_data3 + sd_journal_get_data3, + systemd-machined8