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 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, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
21 * Authors: Colin Walters <walters@verbum.org>
26 /* To make bionic export pipe2() */
31 #include "glib-unix.h"
32 #include "gmain-internal.h"
38 * @title: UNIX-specific utilities and integration
39 * @short_description: pipes, signal handling
40 * @include: glib-unix.h
42 * Most of GLib is intended to be portable; in contrast, this set of
43 * functions is designed for programs which explicitly target UNIX,
44 * or are using it to build higher level abstractions which would be
45 * conditionally compiled if the platform matches G_OS_UNIX.
47 * To use these functions, you must explicitly include the
48 * "glib-unix.h" header.
51 G_DEFINE_QUARK (g-unix-error-quark, g_unix_error)
54 g_unix_set_error_from_errno (GError **error,
57 g_set_error_literal (error,
60 g_strerror (saved_errno));
67 * @fds: Array of two integers
68 * @flags: Bitfield of file descriptor flags, see "man 2 fcntl"
71 * Similar to the UNIX pipe() call, but on modern systems like Linux
72 * uses the pipe2() system call, which atomically creates a pipe with
73 * the configured flags. The only supported flag currently is
74 * <literal>FD_CLOEXEC</literal>. If for example you want to configure
75 * <literal>O_NONBLOCK</literal>, that must still be done separately with
78 * <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
79 * <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
80 * different on Linux/glibc.</note>
82 * Returns: %TRUE on success, %FALSE if not (and errno will be set).
87 g_unix_open_pipe (int *fds,
93 /* We only support FD_CLOEXEC */
94 g_return_val_if_fail ((flags & (FD_CLOEXEC)) == flags, FALSE);
99 if (flags & FD_CLOEXEC)
100 pipe2_flags |= O_CLOEXEC;
102 ecode = pipe2 (fds, pipe2_flags);
103 if (ecode == -1 && errno != ENOSYS)
104 return g_unix_set_error_from_errno (error, errno);
107 /* Fall through on -ENOSYS, we must be running on an old kernel */
112 return g_unix_set_error_from_errno (error, errno);
117 ecode = fcntl (fds[0], F_SETFD, flags);
120 int saved_errno = errno;
123 return g_unix_set_error_from_errno (error, saved_errno);
125 ecode = fcntl (fds[1], F_SETFD, flags);
128 int saved_errno = errno;
131 return g_unix_set_error_from_errno (error, saved_errno);
137 * g_unix_set_fd_nonblocking:
138 * @fd: A file descriptor
139 * @nonblock: If %TRUE, set the descriptor to be non-blocking
142 * Control the non-blocking state of the given file descriptor,
143 * according to @nonblock. On most systems this uses <literal>O_NONBLOCK</literal>, but
144 * on some older ones may use <literal>O_NDELAY</literal>.
146 * Returns: %TRUE if successful
151 g_unix_set_fd_nonblocking (gint fd,
157 fcntl_flags = fcntl (fd, F_GETFL);
159 if (fcntl_flags == -1)
160 return g_unix_set_error_from_errno (error, errno);
165 fcntl_flags |= O_NONBLOCK;
167 fcntl_flags |= O_NDELAY;
173 fcntl_flags &= ~O_NONBLOCK;
175 fcntl_flags &= ~O_NDELAY;
179 if (fcntl (fd, F_SETFL, fcntl_flags) == -1)
180 return g_unix_set_error_from_errno (error, errno);
183 return g_unix_set_error_from_errno (error, EINVAL);
188 * g_unix_signal_source_new:
189 * @signum: A signal number
191 * Create a #GSource that will be dispatched upon delivery of the UNIX
192 * signal @signum. In GLib versions before 2.36, only
193 * <literal>SIGHUP</literal>, <literal>SIGINT</literal>,
194 * <literal>SIGTERM</literal> can be monitored. In GLib 2.36,
195 * <literal>SIGUSR1</literal> and <literal>SIGUSR2</literal> were
198 * Note that unlike the UNIX default, all sources which have created a
199 * watch will be dispatched, regardless of which underlying thread
200 * invoked g_unix_signal_source_new().
202 * For example, an effective use of this function is to handle <literal>SIGTERM</literal>
203 * cleanly; flushing any outstanding files, and then calling
204 * g_main_loop_quit (). It is not safe to do any of this a regular
205 * UNIX signal handler; your handler may be invoked while malloc() or
206 * another library function is running, causing reentrancy if you
207 * attempt to use it from the handler. None of the GLib/GObject API
208 * is safe against this kind of reentrancy.
210 * The interaction of this source when combined with native UNIX
211 * functions like sigprocmask() is not defined.
213 * The source will not initially be associated with any #GMainContext
214 * and must be added to one with g_source_attach() before it will be
217 * Returns: A newly created #GSource
222 g_unix_signal_source_new (int signum)
224 g_return_val_if_fail (signum == SIGHUP || signum == SIGINT || signum == SIGTERM ||
225 signum == SIGUSR1 || signum == SIGUSR2, NULL);
227 return _g_main_create_unix_signal_watch (signum);
231 * g_unix_signal_add_full:
232 * @priority: the priority of the signal source. Typically this will be in
233 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
234 * @signum: Signal number
236 * @user_data: Data for @handler
237 * @notify: #GDestroyNotify for @handler
239 * A convenience function for g_unix_signal_source_new(), which
240 * attaches to the default #GMainContext. You can remove the watch
241 * using g_source_remove().
243 * Returns: An ID (greater than 0) for the event source
245 * Rename to: g_unix_signal_add
249 g_unix_signal_add_full (int priority,
253 GDestroyNotify notify)
258 source = g_unix_signal_source_new (signum);
260 if (priority != G_PRIORITY_DEFAULT)
261 g_source_set_priority (source, priority);
263 g_source_set_callback (source, handler, user_data, notify);
264 id = g_source_attach (source, NULL);
265 g_source_unref (source);
272 * @signum: Signal number
274 * @user_data: Data for @handler
276 * A convenience function for g_unix_signal_source_new(), which
277 * attaches to the default #GMainContext. You can remove the watch
278 * using g_source_remove().
280 * Returns: An ID (greater than 0) for the event source
285 g_unix_signal_add (int signum,
289 return g_unix_signal_add_full (G_PRIORITY_DEFAULT, signum, handler, user_data, NULL);
301 g_unix_fd_source_dispatch (GSource *source,
302 GSourceFunc callback,
305 GUnixFDSource *fd_source = (GUnixFDSource *) source;
306 GUnixFDSourceFunc func = (GUnixFDSourceFunc) callback;
310 g_warning ("GUnixFDSource dispatched without callback\n"
311 "You must call g_source_set_callback().");
315 return (* func) (fd_source->fd, g_source_query_unix_fd (source, fd_source->tag), user_data);
318 GSourceFuncs g_unix_fd_source_funcs = {
319 NULL, NULL, g_unix_fd_source_dispatch, NULL
323 * g_unix_fd_source_new:
324 * @fd: a file descriptor
325 * @condition: IO conditions to watch for on @fd
327 * Creates a #GSource to watch for a particular IO condition on a file
330 * The source will never close the fd -- you must do it yourself.
332 * Returns: the newly created #GSource
337 g_unix_fd_source_new (gint fd,
338 GIOCondition condition)
340 GUnixFDSource *fd_source;
343 source = g_source_new (&g_unix_fd_source_funcs, sizeof (GUnixFDSource));
344 fd_source = (GUnixFDSource *) source;
347 fd_source->tag = g_source_add_unix_fd (source, fd, condition);
353 * g_unix_fd_add_full:
354 * @priority: the priority of the source
355 * @fd: a file descriptor
356 * @condition: IO conditions to watch for on @fd
357 * @function: a #GUnixFDSourceFunc
358 * @user_data: data to pass to @function
359 * @notify: function to call when the idle is removed, or %NULL
361 * Sets a function to be called when the IO condition, as specified by
362 * @condition becomes true for @fd.
364 * This is the same as g_unix_fd_add(), except that it allows you to
365 * specify a non-default priority and a provide a #GDestroyNotify for
368 * Returns: the ID (greater than 0) of the event source
373 g_unix_fd_add_full (gint priority,
375 GIOCondition condition,
376 GUnixFDSourceFunc function,
378 GDestroyNotify notify)
383 g_return_val_if_fail (function != NULL, 0);
385 source = g_unix_fd_source_new (fd, condition);
387 if (priority != G_PRIORITY_DEFAULT)
388 g_source_set_priority (source, priority);
390 g_source_set_callback (source, (GSourceFunc) function, user_data, notify);
391 id = g_source_attach (source, NULL);
392 g_source_unref (source);
399 * @fd: a file descriptor
400 * @condition: IO conditions to watch for on @fd
401 * @function: a #GPollFDFunc
402 * @user_data: data to pass to @function
404 * Sets a function to be called when the IO condition, as specified by
405 * @condition becomes true for @fd.
407 * @function will be called when the specified IO condition becomes
408 * %TRUE. The function is expected to clear whatever event caused the
409 * IO condition to become true and return %TRUE in order to be notified
410 * when it happens again. If @function returns %FALSE then the watch
413 * The return value of this function can be passed to g_source_remove()
414 * to cancel the watch at any time that it exists.
416 * The source will never close the fd -- you must do it yourself.
418 * Returns: the ID (greater than 0) of the event source
423 g_unix_fd_add (gint fd,
424 GIOCondition condition,
425 GUnixFDSourceFunc function,
428 return g_unix_fd_add_full (G_PRIORITY_DEFAULT, fd, condition, function, user_data, NULL);