'\" t .TH "SD_EVENT_ADD_DEFER" "3" "" "systemd 247" "sd_event_add_defer" .\" ----------------------------------------------------------------- .\" * 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_defer, sd_event_add_post, sd_event_add_exit, sd_event_handler_t \- Add static event sources to an event loop .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .sp .ft B .nf typedef struct sd_event_source sd_event_source; .fi .ft .HP \w'typedef\ int\ (*sd_event_handler_t)('u .BI "typedef int (*sd_event_handler_t)(sd_event_source\ *" "s" ", void\ *" "userdata" ");" .HP \w'int\ sd_event_add_defer('u .BI "int sd_event_add_defer(sd_event\ *" "event" ", sd_event_source\ **" "source" ", sd_event_handler_t\ " "handler" ", void\ *" "userdata" ");" .HP \w'int\ sd_event_add_post('u .BI "int sd_event_add_post(sd_event\ *" "event" ", sd_event_source\ **" "source" ", sd_event_handler_t\ " "handler" ", void\ *" "userdata" ");" .HP \w'int\ sd_event_add_exit('u .BI "int sd_event_add_exit(sd_event\ *" "event" ", sd_event_source\ **" "source" ", sd_event_handler_t\ " "handler" ", void\ *" "userdata" ");" .SH "DESCRIPTION" .PP These three functions add new static event sources 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 event sources are enabled statically and will "fire" when the event loop is run and the conditions described below are met\&. The handler function will be passed the \fIuserdata\fR pointer, which may be chosen freely by the caller\&. .PP \fBsd_event_add_defer()\fR adds a new event source that will be dispatched instantly, before the event loop goes to sleep again and waits for new events\&. By default, the handler will be called once (\fBSD_EVENT_ONESHOT\fR)\&. Note that if the event source is set to \fBSD_EVENT_ON\fR the event loop will never go to sleep again, but continuously call the handler, possibly interleaved with other event sources\&. .PP \fBsd_event_add_post()\fR adds a new event source that is run before the event loop will sleep and wait for new events, but only after at least one other non\-post event source was dispatched\&. By default, the source is enabled permanently (\fBSD_EVENT_ON\fR)\&. Note that this event source type will still allow the event loop to go to sleep again, even if set to \fBSD_EVENT_ON\fR, as long as no other event source is ever triggered\&. .PP \fBsd_event_add_exit()\fR adds a new event source that will be dispatched when the event loop is terminated with \fBsd_event_exit\fR(3)\&. .PP The \fBsd_event_source_set_enabled\fR(3) function may be used to enable the event source permanently (\fBSD_EVENT_ON\fR) or to make it fire just once (\fBSD_EVENT_ONESHOT\fR)\&. .PP If the handler function returns a negative error code, it will be disabled after the invocation, even if the \fBSD_EVENT_ON\fR mode was requested before\&. .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 when there\*(Aqs still a reference to it kept, consider setting the event source to \fBSD_EVENT_OFF\fR with \fBsd_event_source_set_enabled\fR(3)\&. .PP If the second parameter of these functions is passed as \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_defer()\fR or \fBsd_event_add_post()\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)\&. Similar functionality is not available for \fBsd_event_add_exit()\fR, as these types of event sources are only dispatched when exiting anyway\&. .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 errors 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\&. .RE .SH "NOTES" .PP These APIs are implemented as a shared library, which can be compiled and linked to with the \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) file\&. .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_time\fR(3), \fBsd_event_add_signal\fR(3), \fBsd_event_add_child\fR(3), \fBsd_event_add_inotify\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), \fBsd_event_exit\fR(3)