]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/sd_journal_get_cutoff_realtime_usec.xml
test-execute: Add tests for new PassEnvironment= directive
[thirdparty/systemd.git] / man / sd_journal_get_cutoff_realtime_usec.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2012 Lennart Poettering
9
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
14
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_journal_get_cutoff_realtime_usec">
25
26 <refentryinfo>
27 <title>sd_journal_get_cutoff_realtime_usec</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle>
42 <manvolnum>3</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>sd_journal_get_cutoff_realtime_usec</refname>
47 <refname>sd_journal_get_cutoff_monotonic_usec</refname>
48 <refpurpose>Read cut-off timestamps from the current journal entry</refpurpose>
49 </refnamediv>
50
51 <refsynopsisdiv>
52 <funcsynopsis>
53 <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
54
55 <funcprototype>
56 <funcdef>int <function>sd_journal_get_cutoff_realtime_usec</function></funcdef>
57 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
58 <paramdef>uint64_t *<parameter>from</parameter></paramdef>
59 <paramdef>uint64_t *<parameter>to</parameter></paramdef>
60 </funcprototype>
61
62 <funcprototype>
63 <funcdef>int <function>sd_journal_get_cutoff_monotonic_usec</function></funcdef>
64 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
65 <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef>
66 <paramdef>uint64_t *<parameter>from</parameter></paramdef>
67 <paramdef>uint64_t *<parameter>to</parameter></paramdef>
68 </funcprototype>
69
70 </funcsynopsis>
71 </refsynopsisdiv>
72
73 <refsect1>
74 <title>Description</title>
75
76 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
77 retrieves the realtime (wallclock) timestamps of the first and
78 last entries accessible in the journal. It takes three arguments:
79 the journal context object <parameter>j</parameter> and two
80 pointers <parameter>from</parameter> and <parameter>to</parameter>
81 pointing at 64-bit unsigned integers to store the timestamps in.
82 The timestamps are in microseconds since the epoch, i.e.
83 <constant>CLOCK_REALTIME</constant>. Either one of the two
84 timestamp arguments may be passed as <constant>NULL</constant> in
85 case the timestamp is not needed, but not both.</para>
86
87 <para><function>sd_journal_get_cutoff_monotonic_usec()</function>
88 retrieves the monotonic timestamps of the first and last entries
89 accessible in the journal. It takes three arguments: the journal
90 context object <parameter>j</parameter>, a 128-bit identifier for
91 the boot <parameter>boot_id</parameter>, and two pointers to
92 64-bit unsigned integers to store the timestamps,
93 <parameter>from</parameter> and <parameter>to</parameter>. The
94 timestamps are in microseconds since boot-up of the specific boot,
95 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the monotonic
96 clock begins new with every reboot it only defines a well-defined
97 point in time when used together with an identifier identifying
98 the boot, see
99 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
100 for more information. The function will return the timestamps for
101 the boot identified by the passed boot ID. Either one of the two
102 timestamp arguments may be passed as <constant>NULL</constant> in
103 case the timestamp is not needed, but not both.</para>
104 </refsect1>
105
106 <refsect1>
107 <title>Return Value</title>
108
109 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
110 and <function>sd_journal_get_cutoff_monotonic_usec()</function>
111 return 1 on success, 0 if not suitable entries are in the journal
112 or a negative errno-style error code.</para>
113
114 <para>Locations pointed to by parameters
115 <parameter>from</parameter> and <parameter>to</parameter> will be
116 set only if the return value is positive, and obviously, the
117 parameters are non-null.</para>
118 </refsect1>
119
120 <refsect1>
121 <title>Notes</title>
122
123 <para>The
124 <function>sd_journal_get_cutoff_realtime_usec()</function> and
125 <function>sd_journal_get_cutoff_monotonic_usec()</function>
126 interfaces are available as a shared library, which can be
127 compiled and linked to with the
128 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
129 file.</para>
130 </refsect1>
131
132 <refsect1>
133 <title>See Also</title>
134
135 <para>
136 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
137 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
138 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
139 <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
140 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
141 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
142 </para>
143 </refsect1>
144
145 </refentry>