chiark / gitweb /
util: make http url validity checks more generic, and move them to util.c
[elogind.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
78                 first and last entries accessible in the journal.  It
79                 takes three arguments: the journal context object
80                 <parameter>j</parameter> and two pointers
81                 <parameter>from</parameter> and
82                 <parameter>to</parameter> pointing at 64-bit unsigned
83                 integers to store the timestamps in. The timestamps
84                 are in microseconds since the epoch,
85                 i.e. <constant>CLOCK_REALTIME</constant>. Either one
86                 of the two timestamp arguments may be passed as
87                 <constant>NULL</constant> in case the timestamp is not
88                 needed, but not both.</para>
89
90                 <para><function>sd_journal_get_cutoff_monotonic_usec()</function>
91                 retrieves the monotonic timestamps of the first and
92                 last entries accessible in the journal. It takes three
93                 arguments: the journal context object
94                 <parameter>j</parameter>, a 128-bit identifier for the
95                 boot <parameter>boot_id</parameter>, and two pointers
96                 to 64-bit unsigned integers to store the timestamps,
97                 <parameter>from</parameter> and
98                 <parameter>to</parameter>. The timestamps are in
99                 microseconds since boot-up of the specific boot,
100                 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the
101                 monotonic clock begins new with every reboot it only
102                 defines a well-defined point in time when used
103                 together with an identifier identifying the boot, see
104                 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
105                 for more information. The function will return the
106                 timestamps for the boot identified by the passed boot
107                 ID. Either one of the two timestamp arguments may be
108                 passed as <constant>NULL</constant> in case the
109                 timestamp is not needed, but not both.</para>
110         </refsect1>
111
112         <refsect1>
113                 <title>Return Value</title>
114
115                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
116                 and
117                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
118                 return 1 on success, 0 if not suitable entries are in
119                 the journal or a negative errno-style error code.</para>
120
121                 <para>Locations pointed to by parameters
122                 <parameter>from</parameter> and
123                 <parameter>to</parameter> will be set only if the
124                 return value is positive, and obviously, the
125                 parameters are non-null.</para>
126         </refsect1>
127
128         <refsect1>
129                 <title>Notes</title>
130
131                 <para>The
132                 <function>sd_journal_get_cutoff_realtime_usec()</function>
133                 and
134                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
135                 interfaces are available as a shared library, which can
136                 be compiled and linked to with the
137                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
138                 file.</para>
139         </refsect1>
140
141         <refsect1>
142                 <title>See Also</title>
143
144                 <para>
145                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
146                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
147                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
148                         <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149                         <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
150                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
151                 </para>
152         </refsect1>
153
154 </refentry>