Debian Codegraph @

upstream/debian-unstable/man3/sd_event_source_set_enabled.3

raw
1 '\" t
2 .TH "SD_EVENT_SOURCE_SET_ENABLED" "3" "" "systemd 261~rc3" "sd_event_source_set_enabled"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_event_source_set_enabled, sd_event_source_get_enabled, SD_EVENT_ON, SD_EVENT_OFF, SD_EVENT_ONESHOT \- Enable or disable event sources
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 enum {
35 \fBSD_EVENT_OFF\fR = 0,
36 \fBSD_EVENT_ON\fR = 1,
37 \fBSD_EVENT_ONESHOT\fR = \-1,
38 };
39 .fi
40 .ft
41 .HP \w'int\ sd_event_source_set_enabled('u
42 .BI "int sd_event_source_set_enabled(sd_event_source\ *" "source" ", int\ " "enabled" ");"
43 .HP \w'int\ sd_event_source_get_enabled('u
44 .BI "int sd_event_source_get_enabled(sd_event_source\ *" "source" ", int\ *" "ret" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_event_source_set_enabled()\fR
48 may be used to enable or disable the event source object specified as
49 \fIsource\fR\&. The
50 \fIenabled\fR
51 parameter takes one of
52 \fBSD_EVENT_ON\fR
53 (to enable),
54 \fBSD_EVENT_OFF\fR
55 (to disable) or
56 \fBSD_EVENT_ONESHOT\fR\&. If invoked with
57 \fBSD_EVENT_ONESHOT\fR
58 the event source will be enabled but automatically reset to
59 \fBSD_EVENT_OFF\fR
60 after one dispatch\&. For
61 \fBSD_EVENT_OFF\fR, the event source
62 \fIsource\fR
63 may be
64 \fBNULL\fR, in which case the function does nothing\&. Otherwise,
65 \fIsource\fR
66 must be a valid pointer to an
67 sd_event_source
68 object\&.
69 .PP
70 Event sources that are disabled will not result in event loop wakeups and will not be dispatched, until they are enabled again\&.
71 .PP
72 \fBsd_event_source_get_enabled()\fR
73 may be used to query whether the event source object
74 \fIsource\fR
75 is currently enabled or not\&. If both the
76 \fIsource\fR
77 and the output parameter
78 \fIret\fR
79 are
80 \fBNULL\fR, this function returns false\&. Otherwise,
81 \fIsource\fR
82 must be a valid pointer to an
83 sd_event_source
84 object\&. If the output parameter
85 \fIret\fR
86 is not
87 \fBNULL\fR, it is set to the enablement state (one of
88 \fBSD_EVENT_ON\fR,
89 \fBSD_EVENT_OFF\fR,
90 \fBSD_EVENT_ONESHOT\fR)\&. The function also returns true if the event source is not disabled\&.
91 .PP
92 Event source objects are enabled when they are first created with calls such as
93 \fBsd_event_add_io\fR(3),
94 \fBsd_event_add_time\fR(3)\&. However, depending on the event source type they are enabled continuously (\fBSD_EVENT_ON\fR) or only for a single invocation of the event source handler (\fBSD_EVENT_ONESHOT\fR)\&. For details see the respective manual pages\&.
95 .PP
96 As event source objects stay active and may be dispatched as long as there is at least one reference to them, in many cases it is a good idea to combine a call to
97 \fBsd_event_source_unref\fR(3)
98 with a prior call to
99 \fBsd_event_source_set_enabled()\fR
100 with
101 \fBSD_EVENT_OFF\fR, to ensure the event source is not dispatched again until all other remaining references are dropped\&.
102 .SH "RETURN VALUE"
103 .PP
104 On success,
105 \fBsd_event_source_set_enabled()\fR
106 returns a non\-negative integer\&.
107 \fBsd_event_source_get_enabled()\fR
108 returns zero if the source is disabled (\fBSD_EVENT_OFF\fR) and a positive integer otherwise\&. On failure, they return a negative errno\-style error code\&.
109 .SS "Errors"
110 .PP
111 Returned errors may indicate the following problems:
112 .PP
113 \fB\-EINVAL\fR
114 .RS 4
115 \fIsource\fR
116 is not a valid pointer to an
117 sd_event_source
118 object\&.
119 .RE
120 .PP
121 \fB\-ENOMEM\fR
122 .RS 4
123 Not enough memory\&.
124 .RE
125 .PP
126 \fB\-ECHILD\fR
127 .RS 4
128 The event loop has been created in a different process, library or module instance\&.
129 .RE
130 .SH "NOTES"
131 .PP
132 Functions described here are available as a shared library, which can be compiled against and linked to with the
133 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
134 file\&.
135 .PP
136 The code described here uses
137 \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
138 \fBsetenv\fR(3)
139 from a parallel thread\&. It is recommended to only do calls to
140 \fBsetenv()\fR
141 from an early phase of the program when no other threads have been started\&.
142 .SH "HISTORY"
143 .PP
144 \fBsd_event_source_set_enabled()\fR
145 and
146 \fBsd_event_source_get_enabled()\fR
147 were added in version 229\&.
148 .SH "SEE ALSO"
149 .PP
150 \fBsd-event\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_add_defer\fR(3), \fBsd_event_source_unref\fR(3), \fBsd_event_source_set_ratelimit\fR(3)