man/sd_event_now.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2015 Lennart Poettering
  11 -->
  12
  13 <refentry id="sd_event_now" xmlns:xi="http://www.w3.org/2001/XInclude">
  14
  15   <refentryinfo>
  16     <title>sd_event_now</title>
  17     <productname>systemd</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>sd_event_now</refentrytitle>
  31     <manvolnum>3</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>sd_event_now</refname>
  36
  37     <refpurpose>Retrieve current event loop iteration timestamp</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_event_now</function></funcdef>
  46         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  47         <paramdef>clockid_t <parameter>clock</parameter></paramdef>
  48         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  49       </funcprototype>
  50
  51     </funcsynopsis>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56
  57     <para><function>sd_event_now()</function> returns the time when
  58     the most recent event loop iteration began. A timestamp
  59     is taken right after returning from the event sleep, and before
  60     dispatching any event sources. The <parameter>event</parameter>
  61     parameter specifies the event loop object to retrieve the timestamp
  62     from. The <parameter>clock</parameter> parameter specifies the clock to
  63     retrieve the timestamp for, and is one of
  64     <constant>CLOCK_REALTIME</constant> (or equivalently
  65     <constant>CLOCK_REALTIME_ALARM</constant>),
  66     <constant>CLOCK_MONOTONIC</constant>, or
  67     <constant>CLOCK_BOOTTIME</constant> (or equivalently
  68     <constant>CLOCK_BOOTTIME_ALARM</constant>), see
  69     <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  70     for more information on the various clocks. The retrieved
  71     timestamp is stored in the <parameter>usec</parameter> parameter,
  72     in µs since the clock's epoch. If this function is invoked before
  73     the first event loop iteration, the current time is returned, as
  74     reported by <function>clock_gettime()</function>. To distinguish
  75     this case from a regular invocation the return value will be
  76     positive, and zero when the returned timestamp refers to an actual
  77     event loop iteration.</para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Return Value</title>
  82
  83     <para>If the first event loop iteration has not run yet
  84     <function>sd_event_now()</function> writes current time to
  85     <parameter>usec</parameter> and returns a positive return value.
  86     Otherwise, it will write the requested timestamp to <parameter>usec</parameter>
  87     and return 0. On failure, the call returns a negative errno-style
  88     error code.</para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>Errors</title>
  93
  94     <para>Returned values may indicate the following problems:</para>
  95
  96     <variablelist>
  97       <varlistentry>
  98         <term><constant>-EINVAL</constant></term>
  99
 100         <listitem><para>An invalid parameter was
 101         passed.</para></listitem>
 102
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term><constant>-EOPNOTSUPP</constant></term>
 107
 108         <listitem><para>Unsupported clock type.
 109         </para></listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><constant>-ECHILD</constant></term>
 114
 115         <listitem><para>The event loop object was created in a
 116         different process.</para></listitem>
 117       </varlistentry>
 118     </variablelist>
 119   </refsect1>
 120
 121   <xi:include href="libsystemd-pkgconfig.xml" />
 122
 123   <refsect1>
 124     <title>See Also</title>
 125
 126     <para>
 127       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 128       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 129       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 130       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 131       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 132     </para>
 133   </refsect1>
 134
 135 </refentry>