diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3/sd_event_add_time.3')
| -rw-r--r-- | upstream/mageia-cauldron/man3/sd_event_add_time.3 | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3/sd_event_add_time.3 b/upstream/mageia-cauldron/man3/sd_event_add_time.3 new file mode 100644 index 00000000..c6d4cc0a --- /dev/null +++ b/upstream/mageia-cauldron/man3/sd_event_add_time.3 @@ -0,0 +1,273 @@ +'\" t +.TH "SD_EVENT_ADD_TIME" "3" "" "systemd 255" "sd_event_add_time" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +sd_event_add_time, sd_event_add_time_relative, sd_event_source_get_time, sd_event_source_set_time, sd_event_source_set_time_relative, sd_event_source_get_time_accuracy, sd_event_source_set_time_accuracy, sd_event_source_get_time_clock, sd_event_time_handler_t \- Add a timer event source to an event loop +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include <systemd/sd\-event\&.h> +.fi +.ft +.sp +.ft B +.nf +typedef struct sd_event_source sd_event_source; +.fi +.ft +.HP \w'typedef\ int\ (*sd_event_time_handler_t)('u +.BI "typedef int (*sd_event_time_handler_t)(sd_event_source\ *" "s" ", uint64_t\ " "usec" ", void\ *" "userdata" ");" +.HP \w'int\ sd_event_add_time('u +.BI "int sd_event_add_time(sd_event\ *" "event" ", sd_event_source\ **" "source" ", clockid_t\ " "clock" ", uint64_t\ " "usec" ", uint64_t\ " "accuracy" ", sd_event_time_handler_t\ " "handler" ", void\ *" "userdata" ");" +.HP \w'int\ sd_event_add_time_relative('u +.BI "int sd_event_add_time_relative(sd_event\ *" "event" ", sd_event_source\ **" "source" ", clockid_t\ " "clock" ", uint64_t\ " "usec" ", uint64_t\ " "accuracy" ", sd_event_time_handler_t\ " "handler" ", void\ *" "userdata" ");" +.HP \w'int\ sd_event_source_get_time('u +.BI "int sd_event_source_get_time(sd_event_source\ *" "source" ", uint64_t\ *" "usec" ");" +.HP \w'int\ sd_event_source_set_time('u +.BI "int sd_event_source_set_time(sd_event_source\ *" "source" ", uint64_t\ " "usec" ");" +.HP \w'int\ sd_event_source_set_time_relative('u +.BI "int sd_event_source_set_time_relative(sd_event_source\ *" "source" ", uint64_t\ " "usec" ");" +.HP \w'int\ sd_event_source_get_time_accuracy('u +.BI "int sd_event_source_get_time_accuracy(sd_event_source\ *" "source" ", uint64_t\ *" "usec" ");" +.HP \w'int\ sd_event_source_set_time_accuracy('u +.BI "int sd_event_source_set_time_accuracy(sd_event_source\ *" "source" ", uint64_t\ " "usec" ");" +.HP \w'int\ sd_event_source_get_time_clock('u +.BI "int sd_event_source_get_time_clock(sd_event_source\ *" "source" ", clockid_t\ *" "clock" ");" +.SH "DESCRIPTION" +.PP +\fBsd_event_add_time()\fR +adds a new timer event source to an event loop\&. The event loop object is specified in the +\fIevent\fR +parameter, the event source object is returned in the +\fIsource\fR +parameter\&. The +\fIclock\fR +parameter takes a clock identifier, one of +\fBCLOCK_REALTIME\fR, +\fBCLOCK_MONOTONIC\fR, +\fBCLOCK_BOOTTIME\fR, +\fBCLOCK_REALTIME_ALARM\fR, or +\fBCLOCK_BOOTTIME_ALARM\fR\&. See +\fBtimerfd_create\fR(2) +for details regarding the various types of clocks\&. The +\fIusec\fR +parameter specifies the earliest time, in microseconds (μs), relative to the clock\*(Aqs epoch, when the timer shall be triggered\&. If a time already in the past is specified (including +\fB0\fR), this timer source "fires" immediately and is ready to be dispatched\&. If the parameter is specified as +\fBUINT64_MAX\fR +the timer event will never elapse, which may be used as an alternative to explicitly disabling a timer event source with +\fBsd_event_source_set_enabled\fR(3)\&. The +\fIaccuracy\fR +parameter specifies an additional accuracy value in μs specifying how much the timer event may be delayed\&. Use +\fB0\fR +to select the default accuracy (250ms)\&. Use 1μs for maximum accuracy\&. Consider specifying 60000000μs (1min) or larger for long\-running events that may be delayed substantially\&. Picking higher accuracy values allows the system to coalesce timer events more aggressively, improving power efficiency\&. +.PP +The +\fIhandler\fR +is a function to call when the timer elapses or +\fBNULL\fR\&. The +\fIuserdata\fR +pointer will be passed to the handler function, and may be chosen freely by the caller\&. The configured trigger time is also passed to the handler, even if the call actually happens slightly later, subject to the specified accuracy value, the kernel timer slack (see +\fBprctl\fR(2)), and additional scheduling latencies\&. To query the actual time the handler was called use +\fBsd_event_now\fR(3)\&. The handler may return negative to signal an error (see below), other return values are ignored\&. If +\fIhandler\fR +is +\fBNULL\fR, a default handler that calls +\fBsd_event_exit\fR(3) +will be used\&. +.PP +By default, the timer will elapse once (\fBSD_EVENT_ONESHOT\fR), but this may be changed with +\fBsd_event_source_set_enabled\fR(3)\&. If the handler function returns a negative error code, it will either be disabled after the invocation, even if the +\fBSD_EVENT_ON\fR +mode was requested before, or it will cause the loop to terminate, see +\fBsd_event_source_set_exit_on_failure\fR(3)\&. Note that a timer event set to +\fBSD_EVENT_ON\fR +will fire continuously unless its configured time is updated using +\fBsd_event_source_set_time()\fR\&. +.PP +\fBsd_event_add_time_relative()\fR +is like +\fBsd_event_add_time()\fR, but takes a relative time specification\&. It\*(Aqs relative to the current time of the event loop iteration, as returned by +\fBsd_event_now\fR(3)\&. +.PP +To destroy an event source object use +\fBsd_event_source_unref\fR(3), but note that the event source is only removed from the event loop when all references to the event source are dropped\&. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using +\fBsd_event_source_set_enabled\fR(3) +with +\fBSD_EVENT_OFF\fR\&. +.PP +If the second parameter of +\fBsd_event_add_time()\fR +is +\fBNULL\fR +no reference to the event source object is returned\&. In this case the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed\&. +.PP +If the +\fIhandler\fR +parameter to +\fBsd_event_add_time()\fR +is +\fBNULL\fR, and the event source fires, this will be considered a request to exit the event loop\&. In this case, the +\fIuserdata\fR +parameter, cast to an integer, is passed as the exit code parameter to +\fBsd_event_exit\fR(3)\&. +.PP +Use +\fBCLOCK_BOOTTIME_ALARM\fR +and +\fBCLOCK_REALTIME_ALARM\fR +to define event sources that may wake up the system from suspend\&. +.PP +In order to set up relative timers (that is, relative to the current time), retrieve the current time via +\fBsd_event_now\fR(3), add the desired timespan to it, and use the result as the +\fIusec\fR +parameter to +\fBsd_event_add_time()\fR\&. +.PP +In order to set up repetitive timers (that is, timers that are triggered in regular intervals), set up the timer normally, for the first invocation\&. Each time the event handler is invoked, update the timer\*(Aqs trigger time with +\fBsd_event_source_set_time\fR(3) +for the next timer iteration, and reenable the timer using +\fBsd_event_source_set_enabled()\fR\&. To calculate the next point in time to pass to +\fBsd_event_source_set_time()\fR, either use as base the +\fIusec\fR +parameter passed to the timer callback, or the timestamp returned by +\fBsd_event_now()\fR\&. In the former case timer events will be regular, while in the latter case the scheduling latency will keep accumulating on the timer\&. +.PP +\fBsd_event_source_get_time()\fR +retrieves the configured time value of an event source created previously with +\fBsd_event_add_time()\fR +or +\fBsd_event_add_time_relative()\fR\&. It takes the event source object and a pointer to a variable to store the time in, relative to the selected clock\*(Aqs epoch, in μs\&. The returned value is relative to the epoch, even if the event source was created with a relative time via +\fBsd_event_add_time_relative()\fR\&. +.PP +\fBsd_event_source_set_time()\fR +changes the time of an event source created previously with +\fBsd_event_add_time()\fR +or +\fBsd_event_add_time_relative()\fR\&. It takes the event source object and a time relative to the selected clock\*(Aqs epoch, in μs\&. +.PP +\fBsd_event_source_set_time_relative()\fR +is similar to +\fBsd_event_source_set_time()\fR, but takes a time relative to the current time of the event loop iteration, as returned by +\fBsd_event_now()\fR\&. +.PP +\fBsd_event_source_get_time_accuracy()\fR +retrieves the configured accuracy value of an event source created previously with +\fBsd_event_add_time()\fR\&. It takes the event source object and a pointer to a variable to store the accuracy in\&. The accuracy is specified in μs\&. +.PP +\fBsd_event_source_set_time_accuracy()\fR +changes the configured accuracy of a timer event source created previously with +\fBsd_event_add_time()\fR\&. It takes the event source object and accuracy, in μs\&. +.PP +\fBsd_event_source_get_time_clock()\fR +retrieves the configured clock of an event source created previously with +\fBsd_event_add_time()\fR\&. It takes the event source object and a pointer to a variable to store the clock identifier in\&. +.SH "RETURN VALUE" +.PP +On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&. +.SS "Errors" +.PP +Returned values may indicate the following problems: +.PP +\fB\-ENOMEM\fR +.RS 4 +Not enough memory to allocate an object\&. +.RE +.PP +\fB\-EINVAL\fR +.RS 4 +An invalid argument has been passed\&. +.RE +.PP +\fB\-ESTALE\fR +.RS 4 +The event loop is already terminated\&. +.RE +.PP +\fB\-ECHILD\fR +.RS 4 +The event loop has been created in a different process, library or module instance\&. +.RE +.PP +\fB\-EOPNOTSUPP\fR +.RS 4 +The selected clock is not supported by the event loop implementation\&. +.RE +.PP +\fB\-EDOM\fR +.RS 4 +The passed event source is not a timer event source\&. +.RE +.PP +\fB\-EOVERFLOW\fR +.RS 4 +The passed relative time is outside of the allowed range for time values (i\&.e\&. the specified value added to the current time is outside the 64 bit unsigned integer range)\&. +.sp +Added in version 247\&. +.RE +.SH "NOTES" +.PP +Functions described here are available as a shared library, which can be compiled against and linked to with the +\fBlibsystemd\fR\ \&\fBpkg-config\fR(1) +file\&. +.PP +The code described here uses +\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call +\fBsetenv\fR(3) +from a parallel thread\&. It is recommended to only do calls to +\fBsetenv()\fR +from an early phase of the program when no other threads have been started\&. +.SH "HISTORY" +.PP +\fBsd_event_add_time()\fR, +\fBsd_event_source_get_time()\fR, +\fBsd_event_source_set_time()\fR, +\fBsd_event_source_get_time_accuracy()\fR, +\fBsd_event_source_set_time_accuracy()\fR, and +\fBsd_event_source_get_time_clock()\fR +were added in version 213\&. +.PP +\fBsd_event_time_handler_t()\fR +was added in version 217\&. +.PP +\fBsd_event_add_time_relative()\fR +and +\fBsd_event_source_set_time_relative()\fR +were added in version 247\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsd-event\fR(3), +\fBsd_event_new\fR(3), +\fBsd_event_now\fR(3), +\fBsd_event_add_io\fR(3), +\fBsd_event_add_signal\fR(3), +\fBsd_event_add_child\fR(3), +\fBsd_event_add_inotify\fR(3), +\fBsd_event_add_defer\fR(3), +\fBsd_event_source_set_enabled\fR(3), +\fBsd_event_source_set_priority\fR(3), +\fBsd_event_source_set_userdata\fR(3), +\fBsd_event_source_set_description\fR(3), +\fBsd_event_source_set_floating\fR(3), +\fBclock_gettime\fR(2), +\fBtimerfd_create\fR(2), +\fBprctl\fR(2) |