glib (2.79.0)
1 /* glib-unix.h - Unix specific integration
2 * Copyright (C) 2011 Red Hat, Inc.
3 * Copyright 2023 Collabora Ltd.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20
21 #ifndef __G_UNIX_H__
22 #define __G_UNIX_H__
23
24 /* We need to include the UNIX headers needed to use the APIs below,
25 * but we also take this opportunity to include a wide selection of
26 * other UNIX headers. If one of the headers below is broken on some
27 * system, work around it here (or better, fix the system or tell
28 * people to use a better one).
29 */
30 #include <unistd.h>
31 #include <errno.h>
32 #include <sys/wait.h>
33 #include <stdlib.h>
34 #include <fcntl.h>
35
36 #include <glib.h>
37 #include <glib/gstdio.h>
38
39 #ifndef G_OS_UNIX
40 #error "This header may only be used on UNIX"
41 #endif
42
43 G_BEGIN_DECLS
44
45 /**
46 * G_UNIX_ERROR:
47 *
48 * Error domain for API in the g_unix_ namespace. Note that there is no
49 * exported enumeration mapping %errno. Instead, all functions ensure that
50 * %errno is relevant. The code for all %G_UNIX_ERROR is always 0, and the
51 * error message is always generated via g_strerror().
52 *
53 * It is expected that most code will not look at %errno from these APIs.
54 * Important cases where one would want to differentiate between errors are
55 * already covered by existing cross-platform GLib API, such as e.g. #GFile
56 * wrapping `ENOENT`. However, it is provided for completeness, at least.
57 */
58 #define G_UNIX_ERROR (g_unix_error_quark())
59
60 GLIB_AVAILABLE_IN_2_30
61 GQuark g_unix_error_quark (void);
62
63 GLIB_AVAILABLE_IN_2_30
64 gboolean g_unix_open_pipe (gint *fds,
65 gint flags,
66 GError **error);
67
68 GLIB_AVAILABLE_IN_2_30
69 gboolean g_unix_set_fd_nonblocking (gint fd,
70 gboolean nonblock,
71 GError **error);
72
73 GLIB_AVAILABLE_IN_2_30
74 GSource *g_unix_signal_source_new (gint signum);
75
76 GLIB_AVAILABLE_IN_2_30
77 guint g_unix_signal_add_full (gint priority,
78 gint signum,
79 GSourceFunc handler,
80 gpointer user_data,
81 GDestroyNotify notify);
82
83 GLIB_AVAILABLE_IN_2_30
84 guint g_unix_signal_add (gint signum,
85 GSourceFunc handler,
86 gpointer user_data);
87
88 /**
89 * GUnixFDSourceFunc:
90 * @fd: the fd that triggered the event
91 * @condition: the IO conditions reported on @fd
92 * @user_data: user data passed to g_unix_fd_add()
93 *
94 * The type of functions to be called when a UNIX fd watch source
95 * triggers.
96 *
97 * Returns: %FALSE if the source should be removed
98 **/
99 typedef gboolean (*GUnixFDSourceFunc) (gint fd,
100 GIOCondition condition,
101 gpointer user_data);
102
103 GLIB_AVAILABLE_IN_2_36
104 GSource *g_unix_fd_source_new (gint fd,
105 GIOCondition condition);
106
107 GLIB_AVAILABLE_IN_2_36
108 guint g_unix_fd_add_full (gint priority,
109 gint fd,
110 GIOCondition condition,
111 GUnixFDSourceFunc function,
112 gpointer user_data,
113 GDestroyNotify notify);
114
115 GLIB_AVAILABLE_IN_2_36
116 guint g_unix_fd_add (gint fd,
117 GIOCondition condition,
118 GUnixFDSourceFunc function,
119 gpointer user_data);
120
121 GLIB_AVAILABLE_IN_2_64
122 struct passwd *g_unix_get_passwd_entry (const gchar *user_name,
123 GError **error);
124
125 /**
126 * GUnixPipe:
127 * @fds: A pair of file descriptors, each negative if closed or not yet opened.
128 * The file descriptor with index %G_UNIX_PIPE_END_READ is readable.
129 * The file descriptor with index %G_UNIX_PIPE_END_WRITE is writable.
130 *
131 * A Unix pipe. The advantage of this type over `int[2]` is that it can
132 * be closed automatically when it goes out of scope, using `g_auto(GUnixPipe)`,
133 * on compilers that support that feature.
134 *
135 * Since: 2.80
136 */
137 GLIB_AVAILABLE_TYPE_IN_2_80
138 typedef struct {
139 int fds[2];
140 } GUnixPipe;
141
142 /**
143 * GUnixPipeEnd:
144 * @G_UNIX_PIPE_END_READ: The readable file descriptor 0
145 * @G_UNIX_PIPE_END_WRITE: The writable file descriptor 1
146 *
147 * Mnemonic constants for the ends of a Unix pipe.
148 *
149 * Since: 2.80
150 */
151 GLIB_AVAILABLE_TYPE_IN_2_80
152 typedef enum
153 {
154 G_UNIX_PIPE_END_READ = 0,
155 G_UNIX_PIPE_END_WRITE = 1
156 } GUnixPipeEnd;
157
158 /**
159 * G_UNIX_PIPE_INIT:
160 *
161 * Initializer for a #GUnixPipe that has not yet been opened.
162 * Both of its file descriptors are initialized to `-1` (invalid),
163 * the same as if they had been closed.
164 *
165 * Since: 2.80
166 */
167 #define G_UNIX_PIPE_INIT { { -1, -1 } } GLIB_AVAILABLE_MACRO_IN_2_80
168
169 /* Suppress "Not available before" warnings when declaring the
170 * implementations */
171 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
172
173 /**
174 * g_unix_pipe_open:
175 * @self: A pair of file descriptors
176 * @flags: Flags to pass to g_unix_open_pipe(), typically `FD_CLOEXEC`
177 * @error: Used to report an error on failure
178 *
179 * Open a pipe. This is the same as g_unix_open_pipe(), but uses the
180 * #GUnixPipe data structure.
181 *
182 * Returns: %TRUE on success
183 *
184 * Since: 2.80
185 */
186 GLIB_AVAILABLE_STATIC_INLINE_IN_2_80
187 static inline gboolean
188 g_unix_pipe_open (GUnixPipe *self,
189 int flags,
190 GError **error)
191 {
192 return g_unix_open_pipe (self->fds, flags, error);
193 }
194
195 /**
196 * g_unix_pipe_get:
197 * @self: A pair of file descriptors
198 * @end: One of the ends of the pipe
199 *
200 * Return one of the ends of the pipe. It remains owned by @self.
201 *
202 * This function is async-signal safe (see [`signal(7)`](man:signal(7)) and
203 * [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a
204 * signal handler or a #GSpawnChildSetupFunc.
205 *
206 * This function preserves the value of `errno`.
207 *
208 * Returns: a non-negative file descriptor owned by @self, which must not
209 * be closed by the caller, or a negative number if the corresponding
210 * end of the pipe was already closed or stolen
211 *
212 * Since: 2.80
213 */
214 GLIB_AVAILABLE_STATIC_INLINE_IN_2_80
215 static inline int
216 g_unix_pipe_get (GUnixPipe *self,
217 GUnixPipeEnd end)
218 {
219 return self->fds[end];
220 }
221
222 /**
223 * g_unix_pipe_steal:
224 * @self: A pair of file descriptors
225 * @end: One of the ends of the pipe
226 *
227 * Return one of the ends of the pipe. It becomes owned by the caller,
228 * and the file descriptor in the data structure is set to `-1`,
229 * similar to g_steal_fd().
230 *
231 * This function is async-signal safe (see [`signal(7)`](man:signal(7)) and
232 * [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a
233 * signal handler or a #GSpawnChildSetupFunc.
234 *
235 * This function preserves the value of `errno`.
236 *
237 * Returns: a non-negative file descriptor, which becomes owned by the
238 * caller and must be closed by the caller if required, or a negative
239 * number if the corresponding end of the pipe was already closed or stolen
240 *
241 * Since: 2.80
242 */
243 GLIB_AVAILABLE_STATIC_INLINE_IN_2_80
244 static inline int
245 g_unix_pipe_steal (GUnixPipe *self,
246 GUnixPipeEnd end)
247 {
248 return g_steal_fd (&self->fds[end]);
249 }
250
251 /**
252 * g_unix_pipe_close:
253 * @self: A pair of file descriptors
254 * @end: One of the ends of the pipe
255 * @error: Optionally used to report an error on failure
256 *
257 * Close one of the ends of the pipe and set the relevant member of @fds
258 * to `-1` before returning, equivalent to g_clear_fd().
259 *
260 * Like g_close(), if closing the file descriptor fails, the error is
261 * stored in both %errno and @error. If this function succeeds,
262 * %errno is undefined.
263 *
264 * This function is async-signal safe if @error is %NULL and the relevant
265 * member of @fds is either negative or a valid open file descriptor.
266 * This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc
267 * under those conditions.
268 * See [`signal(7)`](man:signal(7)) and
269 * [`signal-safety(7)`](man:signal-safety(7)) for more details.
270 *
271 * To close both file descriptors and ignore any errors, use
272 * g_unix_pipe_clear() instead.
273 *
274 * Returns: %TRUE on success
275 *
276 * Since: 2.80
277 */
278 GLIB_AVAILABLE_STATIC_INLINE_IN_2_80
279 static inline gboolean
280 g_unix_pipe_close (GUnixPipe *self,
281 GUnixPipeEnd end,
282 GError **error)
283 {
284 return g_clear_fd (&self->fds[end], error);
285 }
286
287 /**
288 * g_unix_pipe_clear:
289 * @self: a #GUnixPipe
290 *
291 * Close both ends of the pipe, unless they have already been closed or
292 * stolen. Any errors are ignored: use g_unix_pipe_close() or g_clear_fd()
293 * if error-handling is required.
294 *
295 * This function is async-signal safe if @error is %NULL and each member
296 * of @fds are either negative or a valid open file descriptor.
297 * As a result, it is safe to call this function or use `g_auto(GUnixPipe)`
298 * (on compilers that support it) in a signal handler or a
299 * #GSpawnChildSetupFunc, as long as those conditions are ensured to be true.
300 * See [`signal(7)`](man:signal(7)) and
301 * [`signal-safety(7)`](man:signal-safety(7)) for more details.
302 *
303 * This function preserves the value of `errno`.
304 *
305 * Since: 2.80
306 */
307 GLIB_AVAILABLE_STATIC_INLINE_IN_2_80
308 static inline void
309 g_unix_pipe_clear (GUnixPipe *self)
310 {
311 /* Don't overwrite thread-local errno if closing the fd fails */
312 int errsv = errno;
313
314 if (!g_unix_pipe_close (self, G_UNIX_PIPE_END_READ, NULL))
315 {
316 /* ignore */
317 }
318
319 if (!g_unix_pipe_close (self, G_UNIX_PIPE_END_WRITE, NULL))
320 {
321 /* ignore */
322 }
323
324 errno = errsv;
325 }
326
327 G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC (GUnixPipe, g_unix_pipe_clear)
328
329 G_GNUC_END_IGNORE_DEPRECATIONS
330
331 G_END_DECLS
332
333 #endif /* __G_UNIX_H__ */
Browse
Usage
Versions