X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_event_add_signal.xml;h=4c19ada016330238776ddc62741a58823af3babd;hp=2344fb3c0228021a7da12dcb469454042475d7db;hb=734744fddd783fec7b19215b24c12e95c00c1e67;hpb=3144ebcad37422dd85220915d37e7e9eea36564a diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 2344fb3c0..4c19ada01 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -1,27 +1,27 @@ - + - + sd_event_add_signal @@ -45,13 +45,24 @@ along with systemd; If not, see . sd_event_add_signal sd_event_source_get_signal + sd_event_signal_handler_t - Add a signal event source to an event loop + Add a UNIX process signal event source to an event + loop - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_signal_handler_t) + sd_event_source *s + const struct signalfd_siginfo *si + void *userdata + int sd_event_add_signal @@ -62,13 +73,6 @@ along with systemd; If not, see . void *userdata - - typedef int (*sd_event_signal_handler_t) - sd_event_source *s - const struct signalfd_siginfo *si - void *userdata - - int sd_event_source_get_signal sd_event_source *source @@ -80,43 +84,62 @@ along with systemd; If not, see . Description - sd_event_add_signal() adds a new signal - event source to an event loop object. The event loop is specified - in event, the event source is returned in - the source parameter. The - signal parameter specifies the signal to be handled - (see - signal7). - The handler must reference a function to - call when the signal is delivered or be NULL. - The handler function will be passed the - userdata pointer, which may be chosen + sd_event_add_signal() adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the event parameter, + and the event source object is returned in the + source parameter. The + signal parameter specifies the numeric + signal to be handled (see signal7). + The handler parameter must reference a + function to call when the signal is received or be + NULL. The handler function will be passed + the userdata pointer, which may be chosen freely by the caller. The handler also receives a pointer to a - const struct signalfd_siginfo containing - the information about the received signal. See - signalfd2 - for futher information. + signalfd_siginfo structure containing + information about the received signal. See signalfd2 + for further information. Only a single handler may be installed for a specific - signal. The signal will be unblocked, and must be - blocked when the function is called. If the handler is not - specified (handler is + signal. The signal will be unblocked by this call, and must be + blocked before this function is called in all threads (using + sigprocmask2). If + the handler is not specified (handler is NULL), a default handler which causes the - program to exit will be used. By default, the handler is enabled - permanently (SD_EVENT_ON), but this may be - changed with + program to exit cleanly will be used. + + By default, the event source is enabled permanently + (SD_EVENT_ON), but this may be changed with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - SD_EVENT_ON mode is set. + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. - sd_event_source_get_signal() retrieves - the configured signal number of a signal event source created - previously with sd_event_add_signal(). It - takes the event source object as the source + To destroy an event source object use + sd_event_source_unref3, + 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 + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_signal() is + NULL 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. + + sd_event_source_get_signal() returns + the configured signal number of an event source created previously + with sd_event_add_signal(). It takes the + event source object as the source parameter. - @@ -124,7 +147,7 @@ along with systemd; If not, see . On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. + code. @@ -134,52 +157,46 @@ along with systemd; If not, see . - -ENOMEM + -ENOMEM Not enough memory to allocate an object. - -EINVAL + -EINVAL An invalid argument has been passed. - - -EBUSY + -EBUSY - An handler is already installed for this + A handler is already installed for this signal or the signal was not blocked previously. - - -ESTALE + -ESTALE The event loop is already terminated. - - -ECHILD + -ECHILD The event loop has been created in a different process. + + + + -EDOM + The passed event source is not a signal event source. - - Notes - - sd_event_add_signal() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -188,8 +205,16 @@ along with systemd; If not, see . systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_time3, - sd_event_source_set_enabled3 + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_description3, + sd_event_source_set_userdata3, + signal7, + signalfd2