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 #include "glib-unix.h"
27 #include "gmain-internal.h"
33 * @title: UNIX-specific utilities and integration
34 * @short_description: pipes, signal handling
35 * @include: glib-unix.h
37 * Most of GLib is intended to be portable; in contrast, this set of
38 * functions is designed for programs which explicitly target UNIX,
39 * or are using it to build higher level abstractions which would be
40 * conditionally compiled if the platform matches G_OS_UNIX.
42 * To use these functions, you must explicitly include the
43 * "glib-unix.h" header.
47 g_unix_error_quark (void)
49 return g_quark_from_static_string ("g-unix-error-quark");
53 g_unix_set_error_from_errno (GError
**error
,
56 g_set_error_literal (error
,
59 g_strerror (saved_errno
));
66 * @fds: Array of two integers
67 * @flags: Bitfield of file descriptor flags, see "man 2 fcntl"
70 * Similar to the UNIX pipe() call, but on modern systems like Linux
71 * uses the pipe2() system call, which atomically creates a pipe with
72 * the configured flags. The only supported flag currently is
73 * <literal>FD_CLOEXEC</literal>. If for example you want to configure
74 * <literal>O_NONBLOCK</literal>, that must still be done separately with
77 * <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
78 * <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
79 * different on Linux/glibc.</note>
81 * Returns: %TRUE on success, %FALSE if not (and errno will be set).
86 g_unix_open_pipe (int *fds
,
92 /* We only support FD_CLOEXEC */
93 g_return_val_if_fail ((flags
& (FD_CLOEXEC
)) == flags
, FALSE
);
98 if (flags
& FD_CLOEXEC
)
99 pipe2_flags
|= O_CLOEXEC
;
101 ecode
= pipe2 (fds
, pipe2_flags
);
102 if (ecode
== -1 && errno
!= ENOSYS
)
103 return g_unix_set_error_from_errno (error
, errno
);
106 /* Fall through on -ENOSYS, we must be running on an old kernel */
111 return g_unix_set_error_from_errno (error
, errno
);
112 ecode
= fcntl (fds
[0], flags
);
115 int saved_errno
= errno
;
118 return g_unix_set_error_from_errno (error
, saved_errno
);
120 ecode
= fcntl (fds
[1], flags
);
123 int saved_errno
= errno
;
126 return g_unix_set_error_from_errno (error
, saved_errno
);
132 * g_unix_set_fd_nonblocking:
133 * @fd: A file descriptor
134 * @nonblock: If %TRUE, set the descriptor to be non-blocking
137 * Control the non-blocking state of the given file descriptor,
138 * according to @nonblock. On most systems this uses <literal>O_NONBLOCK</literal>, but
139 * on some older ones may use <literal>O_NDELAY</literal>.
141 * Returns: %TRUE if successful
146 g_unix_set_fd_nonblocking (gint fd
,
152 fcntl_flags
= fcntl (fd
, F_GETFL
);
154 if (fcntl_flags
== -1)
155 return g_unix_set_error_from_errno (error
, errno
);
160 fcntl_flags
|= O_NONBLOCK
;
162 fcntl_flags
|= O_NDELAY
;
168 fcntl_flags
&= ~O_NONBLOCK
;
170 fcntl_flags
&= ~O_NDELAY
;
174 if (fcntl (fd
, F_SETFL
, fcntl_flags
) == -1)
175 return g_unix_set_error_from_errno (error
, errno
);
178 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. Currently only <literal>SIGHUP</literal>,
189 * <literal>SIGINT</literal>, and <literal>SIGTERM</literal> can
190 * be monitored. Note that unlike the UNIX default, all sources which
191 * have created a watch will be dispatched, regardless of which
192 * underlying thread invoked g_unix_signal_source_new().
194 * For example, an effective use of this function is to handle <literal>SIGTERM</literal>
195 * cleanly; flushing any outstanding files, and then calling
196 * g_main_loop_quit (). It is not safe to do any of this a regular
197 * UNIX signal handler; your handler may be invoked while malloc() or
198 * another library function is running, causing reentrancy if you
199 * attempt to use it from the handler. None of the GLib/GObject API
200 * is safe against this kind of reentrancy.
202 * The interaction of this source when combined with native UNIX
203 * functions like sigprocmask() is not defined.
205 * The source will not initially be associated with any #GMainContext
206 * and must be added to one with g_source_attach() before it will be
209 * Returns: A newly created #GSource
214 g_unix_signal_source_new (int signum
)
216 g_return_val_if_fail (signum
== SIGHUP
|| signum
== SIGINT
|| signum
== SIGTERM
, NULL
);
218 return _g_main_create_unix_signal_watch (signum
);
222 * g_unix_signal_add_full:
223 * @priority: the priority of the signal source. Typically this will be in
224 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
225 * @signum: Signal number
227 * @user_data: Data for @handler
228 * @notify: #GDestroyNotify for @handler
230 * A convenience function for g_unix_signal_source_new(), which
231 * attaches to the default #GMainContext. You can remove the watch
232 * using g_source_remove().
234 * Returns: An ID (greater than 0) for the event source
239 g_unix_signal_add_full (int priority
,
243 GDestroyNotify notify
)
248 source
= g_unix_signal_source_new (signum
);
250 if (priority
!= G_PRIORITY_DEFAULT
)
251 g_source_set_priority (source
, priority
);
253 g_source_set_callback (source
, handler
, user_data
, notify
);
254 id
= g_source_attach (source
, NULL
);
255 g_source_unref (source
);
262 * @signum: Signal number
264 * @user_data: Data for @handler
266 * A convenience function for g_unix_signal_source_new(), which
267 * attaches to the default #GMainContext. You can remove the watch
268 * using g_source_remove().
270 * Returns: An ID (greater than 0) for the event source
275 g_unix_signal_add (int signum
,
279 return g_unix_signal_add_full (G_PRIORITY_DEFAULT
, signum
, handler
, user_data
, NULL
);