glib/glib-unix.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 2011 Red Hat, Inc.
   3  *
   4  * glib-unix.c: UNIX specific API wrappers and convenience functions
   5  *
   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.
  10  *
  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.
  15  *
  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.
  20  *
  21  * Authors: Colin Walters <walters@verbum.org>
  22  */
  23
  24 #include "config.h"
  25
  26 #include "glib-unix.h"
  27 #include "gmain-internal.h"
  28
  29 #include <string.h>
  30
  31 /**
  32  * SECTION:gunix
  33  * @title: UNIX-specific utilities and integration
  34  * @short_description: pipes, signal handling
  35  * @include: glib-unix.h
  36  *
  37  * Most of GLib is intended to be portable; in constrast, this set of
  38  * functions is designed for programs which explicitly target UNIX, or
  39  * are using it to build higher level abstractions which would be
  40  * conditionally compiled if the platform matches G_OS_UNIX.
  41  *
  42  * To use these functions, you must explicitly include the
  43  * "glib-unix.h" header.
  44  */
  45
  46 GQuark
  47 g_unix_error_quark (void)
  48 {
  49   return g_quark_from_static_string ("g-unix-error-quark");
  50 }
  51
  52 static gboolean
  53 g_unix_set_error_from_errno (GError **error)
  54 {
  55   int saved_errno = errno;
  56   g_set_error_literal (error,
  57                        G_UNIX_ERROR,
  58                        0,
  59                        g_strerror (errno));
  60   errno = saved_errno;
  61   return FALSE;
  62 }
  63
  64 static gboolean
  65 g_unix_set_error_from_errno_saved (GError **error,
  66                                     int      saved_errno)
  67 {
  68   g_set_error_literal (error,
  69                        G_UNIX_ERROR,
  70                        0,
  71                        g_strerror (saved_errno));
  72   errno = saved_errno;
  73   return FALSE;
  74 }
  75
  76 /**
  77  * g_unix_open_pipe:
  78  * @fds: Array of two integers
  79  * @flags: Bitfield of file descriptor flags, see "man 2 fcntl"
  80  * @error: a #GError
  81  *
  82  * Similar to the UNIX pipe() call, but on modern systems like Linux
  83  * uses the pipe2() system call, which atomically creates a pipe with
  84  * the configured flags.  The only supported flag currently is
  85  * %FD_CLOEXEC.  If for example you want to configure %O_NONBLOCK,
  86  * that must still be done separately with fcntl().
  87  *
  88  * <note>This function does *not* take %O_CLOEXEC, it takes
  89  * %FD_CLOEXEC as if for fcntl(); these are different on
  90  * Linux/glibc.</note>
  91  *
  92  * Returns: %TRUE on success, %FALSE if not (and errno will be set).
  93  *
  94  * Since: 2.30
  95  */
  96 gboolean
  97 g_unix_open_pipe (int     *fds,
  98                   int      flags,
  99                   GError **error)
 100 {
 101   int ecode;
 102
 103   /* We only support FD_CLOEXEC */
 104   g_return_val_if_fail ((flags & (FD_CLOEXEC)) == flags, FALSE);
 105
 106 #ifdef HAVE_PIPE2
 107   {
 108     int pipe2_flags = 0;
 109     if (flags & FD_CLOEXEC)
 110       pipe2_flags |= O_CLOEXEC;
 111     /* Atomic */
 112     ecode = pipe2 (fds, pipe2_flags);
 113     if (ecode == -1 && errno != ENOSYS)
 114       return g_unix_set_error_from_errno (error);
 115     else if (ecode == 0)
 116       return TRUE;
 117     /* Fall through on -ENOSYS, we must be running on an old kernel */
 118   }
 119 #endif
 120   ecode = pipe (fds);
 121   if (ecode == -1)
 122     return g_unix_set_error_from_errno (error);
 123   ecode = fcntl (fds[0], flags);
 124   if (ecode == -1)
 125     {
 126       int saved_errno = errno;
 127       close (fds[0]);
 128       return g_unix_set_error_from_errno_saved (error, saved_errno);
 129     }
 130   ecode = fcntl (fds[0], flags);
 131   if (ecode == -1)
 132     {
 133       int saved_errno = errno;
 134       close (fds[0]);
 135       close (fds[1]);
 136       return g_unix_set_error_from_errno_saved (error, saved_errno);
 137     }
 138   return TRUE;
 139 }
 140
 141 /**
 142  * g_unix_set_fd_nonblocking:
 143  * @fd: A file descriptor
 144  * @nonblock: If %TRUE, set the descriptor to be non-blocking
 145  * @error: a #GError
 146  *
 147  * Control the non-blocking state of the given file descriptor,
 148  * according to @nonblock.  On most systems this uses %O_NONBLOCK, but
 149  * on some older ones may use %O_NDELAY.
 150  *
 151  * Returns: %TRUE if successful
 152  *
 153  * Since: 2.30
 154  */
 155 gboolean
 156 g_unix_set_fd_nonblocking (gint       fd,
 157                            gboolean   nonblock,
 158                            GError   **error)
 159 {
 160 #ifdef F_GETFL
 161   glong fcntl_flags;
 162   fcntl_flags = fcntl (fd, F_GETFL);
 163
 164   if (fcntl_flags == -1)
 165     return g_unix_set_error_from_errno (error);
 166
 167   if (nonblock)
 168     {
 169 #ifdef O_NONBLOCK
 170       fcntl_flags |= O_NONBLOCK;
 171 #else
 172       fcntl_flags |= O_NDELAY;
 173 #endif
 174     }
 175   else
 176     {
 177 #ifdef O_NONBLOCK
 178       fcntl_flags &= ~O_NONBLOCK;
 179 #else
 180       fcntl_flags &= ~O_NDELAY;
 181 #endif
 182     }
 183
 184   if (fcntl (fd, F_SETFL, fcntl_flags) == -1)
 185     return g_unix_set_error_from_errno (error);
 186   return TRUE;
 187 #else
 188   return g_unix_set_error_from_errno_saved (error, EINVAL);
 189 #endif
 190 }
 191
 192
 193 /**
 194  * g_unix_signal_source_new:
 195  * @signum: A signal number
 196  *
 197  * Create a #GSource that will be dispatched upon delivery of the UNIX
 198  * signal @signum.  Currently only %SIGHUP, %SIGINT, and %SIGTERM can
 199  * be monitored.  Note that unlike the UNIX default, all sources which
 200  * have created a watch will be dispatched, regardless of which
 201  * underlying thread invoked g_unix_signal_create_watch().
 202  *
 203  * For example, an effective use of this function is to handle SIGTERM
 204  * cleanly; flushing any outstanding files, and then calling
 205  * g_main_loop_quit ().  It is not safe to do any of this a regular
 206  * UNIX signal handler; your handler may be invoked while malloc() or
 207  * another library function is running, causing reentrancy if you
 208  * attempt to use it from the handler.  None of the GLib/GObject API
 209  * is safe against this kind of reentrancy.
 210  *
 211  * The interaction of this source when combined with native UNIX
 212  * functions like sigprocmask() is not defined.
 213  *
 214  * <note>For reliable behavior, if your program links to gthread
 215  * (either directly or indirectly via GObject, GIO, or a higher level
 216  * library), you should ensure g_thread_init() is called before using
 217  * this function.  For example, if your program uses GObject, call
 218  * g_type_init().</note>
 219  *
 220  * The source will not initially be associated with any #GMainContext
 221  * and must be added to one with g_source_attach() before it will be
 222  * executed.
 223  *
 224  * Returns: A newly created #GSource
 225  *
 226  * Since: 2.30
 227  */
 228 GSource *
 229 g_unix_signal_source_new (int signum)
 230 {
 231   g_return_val_if_fail (signum == SIGHUP || signum == SIGINT || signum == SIGTERM, NULL);
 232
 233   return _g_main_create_unix_signal_watch (signum);
 234 }
 235
 236 /**
 237  * g_unix_signal_add_watch_full:
 238  * @signum: Signal number
 239  * @priority: the priority of the signal source. Typically this will be in
 240  *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
 241  * @handler: Callback
 242  * @user_data: Data for @handler
 243  * @notify: #GDestroyNotify for @handler
 244  *
 245  * A convenience function for g_unix_signal_source_new(), which
 246  * attaches to the default #GMainContext.  You can remove the watch
 247  * using g_source_remove().
 248  *
 249  * Returns: An ID (greater than 0) for the event source
 250  *
 251  * Since: 2.30
 252  */
 253 guint
 254 g_unix_signal_add_watch_full (int            signum,
 255                               int            priority,
 256                               GSourceFunc    handler,
 257                               gpointer       user_data,
 258                               GDestroyNotify notify)
 259 {
 260   guint id;
 261   GSource *source;
 262
 263   source = g_unix_signal_source_new (signum);
 264
 265   if (priority != G_PRIORITY_DEFAULT)
 266     g_source_set_priority (source, priority);
 267
 268   g_source_set_callback (source, handler, user_data, notify);
 269   id = g_source_attach (source, NULL);
 270   g_source_unref (source);
 271
 272   return id;
 273 }