1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 2011 Red Hat, Inc.
4 * glib-unix.c: UNIX specific API wrappers and convenience functions
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * Authors: Colin Walters <walters@verbum.org>
24 /* To make bionic export pipe2() */
29 #include "glib-unix.h"
30 #include "gmain-internal.h"
36 * @title: UNIX-specific utilities and integration
37 * @short_description: pipes, signal handling
38 * @include: glib-unix.h
40 * Most of GLib is intended to be portable; in contrast, this set of
41 * functions is designed for programs which explicitly target UNIX,
42 * or are using it to build higher level abstractions which would be
43 * conditionally compiled if the platform matches G_OS_UNIX.
45 * To use these functions, you must explicitly include the
46 * "glib-unix.h" header.
49 G_DEFINE_QUARK (g
-unix
-error
-quark
, g_unix_error
)
52 g_unix_set_error_from_errno (GError
**error
,
55 g_set_error_literal (error
,
58 g_strerror (saved_errno
));
65 * @fds: Array of two integers
66 * @flags: Bitfield of file descriptor flags, as for fcntl()
69 * Similar to the UNIX pipe() call, but on modern systems like Linux
70 * uses the pipe2() system call, which atomically creates a pipe with
71 * the configured flags. The only supported flag currently is
72 * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
73 * must still be done separately with fcntl().
75 * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
76 * for fcntl(); these are different on Linux/glibc.
78 * Returns: %TRUE on success, %FALSE if not (and errno will be set).
83 g_unix_open_pipe (int *fds
,
89 /* We only support FD_CLOEXEC */
90 g_return_val_if_fail ((flags
& (FD_CLOEXEC
)) == flags
, FALSE
);
95 if (flags
& FD_CLOEXEC
)
96 pipe2_flags
|= O_CLOEXEC
;
98 ecode
= pipe2 (fds
, pipe2_flags
);
99 if (ecode
== -1 && errno
!= ENOSYS
)
100 return g_unix_set_error_from_errno (error
, errno
);
103 /* Fall through on -ENOSYS, we must be running on an old kernel */
108 return g_unix_set_error_from_errno (error
, errno
);
113 ecode
= fcntl (fds
[0], F_SETFD
, flags
);
116 int saved_errno
= errno
;
119 return g_unix_set_error_from_errno (error
, saved_errno
);
121 ecode
= fcntl (fds
[1], F_SETFD
, flags
);
124 int saved_errno
= errno
;
127 return g_unix_set_error_from_errno (error
, saved_errno
);
133 * g_unix_set_fd_nonblocking:
134 * @fd: A file descriptor
135 * @nonblock: If %TRUE, set the descriptor to be non-blocking
138 * Control the non-blocking state of the given file descriptor,
139 * according to @nonblock. On most systems this uses %O_NONBLOCK, but
140 * on some older ones may use %O_NDELAY.
142 * Returns: %TRUE if successful
147 g_unix_set_fd_nonblocking (gint fd
,
153 fcntl_flags
= fcntl (fd
, F_GETFL
);
155 if (fcntl_flags
== -1)
156 return g_unix_set_error_from_errno (error
, errno
);
161 fcntl_flags
|= O_NONBLOCK
;
163 fcntl_flags
|= O_NDELAY
;
169 fcntl_flags
&= ~O_NONBLOCK
;
171 fcntl_flags
&= ~O_NDELAY
;
175 if (fcntl (fd
, F_SETFL
, fcntl_flags
) == -1)
176 return g_unix_set_error_from_errno (error
, errno
);
179 return g_unix_set_error_from_errno (error
, EINVAL
);
184 * g_unix_signal_source_new:
185 * @signum: A signal number
187 * Create a #GSource that will be dispatched upon delivery of the UNIX
188 * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
189 * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2`
190 * were added. In GLib 2.54, `SIGWINCH` was added.
192 * Note that unlike the UNIX default, all sources which have created a
193 * watch will be dispatched, regardless of which underlying thread
194 * invoked g_unix_signal_source_new().
196 * For example, an effective use of this function is to handle `SIGTERM`
197 * cleanly; flushing any outstanding files, and then calling
198 * g_main_loop_quit (). It is not safe to do any of this a regular
199 * UNIX signal handler; your handler may be invoked while malloc() or
200 * another library function is running, causing reentrancy if you
201 * attempt to use it from the handler. None of the GLib/GObject API
202 * is safe against this kind of reentrancy.
204 * The interaction of this source when combined with native UNIX
205 * functions like sigprocmask() is not defined.
207 * The source will not initially be associated with any #GMainContext
208 * and must be added to one with g_source_attach() before it will be
211 * Returns: A newly created #GSource
216 g_unix_signal_source_new (int signum
)
218 g_return_val_if_fail (signum
== SIGHUP
|| signum
== SIGINT
|| signum
== SIGTERM
||
219 signum
== SIGUSR1
|| signum
== SIGUSR2
|| signum
== SIGWINCH
,
222 return _g_main_create_unix_signal_watch (signum
);
226 * g_unix_signal_add_full: (rename-to g_unix_signal_add)
227 * @priority: the priority of the signal source. Typically this will be in
228 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
229 * @signum: Signal number
231 * @user_data: Data for @handler
232 * @notify: #GDestroyNotify for @handler
234 * A convenience function for g_unix_signal_source_new(), which
235 * attaches to the default #GMainContext. You can remove the watch
236 * using g_source_remove().
238 * Returns: An ID (greater than 0) for the event source
243 g_unix_signal_add_full (int priority
,
247 GDestroyNotify notify
)
252 source
= g_unix_signal_source_new (signum
);
254 if (priority
!= G_PRIORITY_DEFAULT
)
255 g_source_set_priority (source
, priority
);
257 g_source_set_callback (source
, handler
, user_data
, notify
);
258 id
= g_source_attach (source
, NULL
);
259 g_source_unref (source
);
266 * @signum: Signal number
268 * @user_data: Data for @handler
270 * A convenience function for g_unix_signal_source_new(), which
271 * attaches to the default #GMainContext. You can remove the watch
272 * using g_source_remove().
274 * Returns: An ID (greater than 0) for the event source
279 g_unix_signal_add (int signum
,
283 return g_unix_signal_add_full (G_PRIORITY_DEFAULT
, signum
, handler
, user_data
, NULL
);
295 g_unix_fd_source_dispatch (GSource
*source
,
296 GSourceFunc callback
,
299 GUnixFDSource
*fd_source
= (GUnixFDSource
*) source
;
300 GUnixFDSourceFunc func
= (GUnixFDSourceFunc
) callback
;
304 g_warning ("GUnixFDSource dispatched without callback\n"
305 "You must call g_source_set_callback().");
309 return (* func
) (fd_source
->fd
, g_source_query_unix_fd (source
, fd_source
->tag
), user_data
);
312 GSourceFuncs g_unix_fd_source_funcs
= {
313 NULL
, NULL
, g_unix_fd_source_dispatch
, NULL
317 * g_unix_fd_source_new:
318 * @fd: a file descriptor
319 * @condition: IO conditions to watch for on @fd
321 * Creates a #GSource to watch for a particular IO condition on a file
324 * The source will never close the fd -- you must do it yourself.
326 * Returns: the newly created #GSource
331 g_unix_fd_source_new (gint fd
,
332 GIOCondition condition
)
334 GUnixFDSource
*fd_source
;
337 source
= g_source_new (&g_unix_fd_source_funcs
, sizeof (GUnixFDSource
));
338 fd_source
= (GUnixFDSource
*) source
;
341 fd_source
->tag
= g_source_add_unix_fd (source
, fd
, condition
);
347 * g_unix_fd_add_full:
348 * @priority: the priority of the source
349 * @fd: a file descriptor
350 * @condition: IO conditions to watch for on @fd
351 * @function: a #GUnixFDSourceFunc
352 * @user_data: data to pass to @function
353 * @notify: function to call when the idle is removed, or %NULL
355 * Sets a function to be called when the IO condition, as specified by
356 * @condition becomes true for @fd.
358 * This is the same as g_unix_fd_add(), except that it allows you to
359 * specify a non-default priority and a provide a #GDestroyNotify for
362 * Returns: the ID (greater than 0) of the event source
367 g_unix_fd_add_full (gint priority
,
369 GIOCondition condition
,
370 GUnixFDSourceFunc function
,
372 GDestroyNotify notify
)
377 g_return_val_if_fail (function
!= NULL
, 0);
379 source
= g_unix_fd_source_new (fd
, condition
);
381 if (priority
!= G_PRIORITY_DEFAULT
)
382 g_source_set_priority (source
, priority
);
384 g_source_set_callback (source
, (GSourceFunc
) function
, user_data
, notify
);
385 id
= g_source_attach (source
, NULL
);
386 g_source_unref (source
);
393 * @fd: a file descriptor
394 * @condition: IO conditions to watch for on @fd
395 * @function: a #GPollFDFunc
396 * @user_data: data to pass to @function
398 * Sets a function to be called when the IO condition, as specified by
399 * @condition becomes true for @fd.
401 * @function will be called when the specified IO condition becomes
402 * %TRUE. The function is expected to clear whatever event caused the
403 * IO condition to become true and return %TRUE in order to be notified
404 * when it happens again. If @function returns %FALSE then the watch
407 * The return value of this function can be passed to g_source_remove()
408 * to cancel the watch at any time that it exists.
410 * The source will never close the fd -- you must do it yourself.
412 * Returns: the ID (greater than 0) of the event source
417 g_unix_fd_add (gint fd
,
418 GIOCondition condition
,
419 GUnixFDSourceFunc function
,
422 return g_unix_fd_add_full (G_PRIORITY_DEFAULT
, fd
, condition
, function
, user_data
, NULL
);