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.1 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, see <http://www.gnu.org/licenses/>.
  18  *
  19  * Authors: Colin Walters <walters@verbum.org>
  20  */
  21
  22 #include "config.h"
  23
  24 /* To make bionic export pipe2() */
  25 #ifndef _GNU_SOURCE
  26 #define _GNU_SOURCE 1
  27 #endif
  28
  29 #include "glib-unix.h"
  30 #include "gmain-internal.h"
  31
  32 #include <string.h>
  33
  34 /**
  35  * SECTION:gunix
  36  * @title: UNIX-specific utilities and integration
  37  * @short_description: pipes, signal handling
  38  * @include: glib-unix.h
  39  *
  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.
  44  *
  45  * To use these functions, you must explicitly include the
  46  * "glib-unix.h" header.
  47  */
  48
  49 G_DEFINE_QUARK (g-unix-error-quark, g_unix_error)
  50
  51 static gboolean
  52 g_unix_set_error_from_errno (GError **error,
  53                              gint     saved_errno)
  54 {
  55   g_set_error_literal (error,
  56                        G_UNIX_ERROR,
  57                        0,
  58                        g_strerror (saved_errno));
  59   errno = saved_errno;
  60   return FALSE;
  61 }
  62
  63 /**
  64  * g_unix_open_pipe:
  65  * @fds: Array of two integers
  66  * @flags: Bitfield of file descriptor flags, as for fcntl()
  67  * @error: a #GError
  68  *
  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().
  74  *
  75  * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
  76  * for fcntl(); these are different on Linux/glibc.
  77  *
  78  * Returns: %TRUE on success, %FALSE if not (and errno will be set).
  79  *
  80  * Since: 2.30
  81  */
  82 gboolean
  83 g_unix_open_pipe (int     *fds,
  84                   int      flags,
  85                   GError **error)
  86 {
  87   int ecode;
  88
  89   /* We only support FD_CLOEXEC */
  90   g_return_val_if_fail ((flags & (FD_CLOEXEC)) == flags, FALSE);
  91
  92 #ifdef HAVE_PIPE2
  93   {
  94     int pipe2_flags = 0;
  95     if (flags & FD_CLOEXEC)
  96       pipe2_flags |= O_CLOEXEC;
  97     /* Atomic */
  98     ecode = pipe2 (fds, pipe2_flags);
  99     if (ecode == -1 && errno != ENOSYS)
 100       return g_unix_set_error_from_errno (error, errno);
 101     else if (ecode == 0)
 102       return TRUE;
 103     /* Fall through on -ENOSYS, we must be running on an old kernel */
 104   }
 105 #endif
 106   ecode = pipe (fds);
 107   if (ecode == -1)
 108     return g_unix_set_error_from_errno (error, errno);
 109
 110   if (flags == 0)
 111     return TRUE;
 112
 113   ecode = fcntl (fds[0], F_SETFD, flags);
 114   if (ecode == -1)
 115     {
 116       int saved_errno = errno;
 117       close (fds[0]);
 118       close (fds[1]);
 119       return g_unix_set_error_from_errno (error, saved_errno);
 120     }
 121   ecode = fcntl (fds[1], F_SETFD, flags);
 122   if (ecode == -1)
 123     {
 124       int saved_errno = errno;
 125       close (fds[0]);
 126       close (fds[1]);
 127       return g_unix_set_error_from_errno (error, saved_errno);
 128     }
 129   return TRUE;
 130 }
 131
 132 /**
 133  * g_unix_set_fd_nonblocking:
 134  * @fd: A file descriptor
 135  * @nonblock: If %TRUE, set the descriptor to be non-blocking
 136  * @error: a #GError
 137  *
 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.
 141  *
 142  * Returns: %TRUE if successful
 143  *
 144  * Since: 2.30
 145  */
 146 gboolean
 147 g_unix_set_fd_nonblocking (gint       fd,
 148                            gboolean   nonblock,
 149                            GError   **error)
 150 {
 151 #ifdef F_GETFL
 152   glong fcntl_flags;
 153   fcntl_flags = fcntl (fd, F_GETFL);
 154
 155   if (fcntl_flags == -1)
 156     return g_unix_set_error_from_errno (error, errno);
 157
 158   if (nonblock)
 159     {
 160 #ifdef O_NONBLOCK
 161       fcntl_flags |= O_NONBLOCK;
 162 #else
 163       fcntl_flags |= O_NDELAY;
 164 #endif
 165     }
 166   else
 167     {
 168 #ifdef O_NONBLOCK
 169       fcntl_flags &= ~O_NONBLOCK;
 170 #else
 171       fcntl_flags &= ~O_NDELAY;
 172 #endif
 173     }
 174
 175   if (fcntl (fd, F_SETFL, fcntl_flags) == -1)
 176     return g_unix_set_error_from_errno (error, errno);
 177   return TRUE;
 178 #else
 179   return g_unix_set_error_from_errno (error, EINVAL);
 180 #endif
 181 }
 182
 183 /**
 184  * g_unix_signal_source_new:
 185  * @signum: A signal number
 186  *
 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.
 191  *
 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().
 195  *
 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.
 203  *
 204  * The interaction of this source when combined with native UNIX
 205  * functions like sigprocmask() is not defined.
 206  *
 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
 209  * executed.
 210  *
 211  * Returns: A newly created #GSource
 212  *
 213  * Since: 2.30
 214  */
 215 GSource *
 216 g_unix_signal_source_new (int signum)
 217 {
 218   g_return_val_if_fail (signum == SIGHUP || signum == SIGINT || signum == SIGTERM ||
 219                         signum == SIGUSR1 || signum == SIGUSR2 || signum == SIGWINCH,
 220                         NULL);
 221
 222   return _g_main_create_unix_signal_watch (signum);
 223 }
 224
 225 /**
 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
 230  * @handler: Callback
 231  * @user_data: Data for @handler
 232  * @notify: #GDestroyNotify for @handler
 233  *
 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().
 237  *
 238  * Returns: An ID (greater than 0) for the event source
 239  *
 240  * Since: 2.30
 241  */
 242 guint
 243 g_unix_signal_add_full (int            priority,
 244                         int            signum,
 245                         GSourceFunc    handler,
 246                         gpointer       user_data,
 247                         GDestroyNotify notify)
 248 {
 249   guint id;
 250   GSource *source;
 251
 252   source = g_unix_signal_source_new (signum);
 253
 254   if (priority != G_PRIORITY_DEFAULT)
 255     g_source_set_priority (source, priority);
 256
 257   g_source_set_callback (source, handler, user_data, notify);
 258   id = g_source_attach (source, NULL);
 259   g_source_unref (source);
 260
 261   return id;
 262 }
 263
 264 /**
 265  * g_unix_signal_add:
 266  * @signum: Signal number
 267  * @handler: Callback
 268  * @user_data: Data for @handler
 269  *
 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().
 273  *
 274  * Returns: An ID (greater than 0) for the event source
 275  *
 276  * Since: 2.30
 277  */
 278 guint
 279 g_unix_signal_add (int         signum,
 280                    GSourceFunc handler,
 281                    gpointer    user_data)
 282 {
 283   return g_unix_signal_add_full (G_PRIORITY_DEFAULT, signum, handler, user_data, NULL);
 284 }
 285
 286 typedef struct
 287 {
 288   GSource source;
 289
 290   gint     fd;
 291   gpointer tag;
 292 } GUnixFDSource;
 293
 294 static gboolean
 295 g_unix_fd_source_dispatch (GSource     *source,
 296                            GSourceFunc  callback,
 297                            gpointer     user_data)
 298 {
 299   GUnixFDSource *fd_source = (GUnixFDSource *) source;
 300   GUnixFDSourceFunc func = (GUnixFDSourceFunc) callback;
 301
 302   if (!callback)
 303     {
 304       g_warning ("GUnixFDSource dispatched without callback. "
 305                  "You must call g_source_set_callback().");
 306       return FALSE;
 307     }
 308
 309   return (* func) (fd_source->fd, g_source_query_unix_fd (source, fd_source->tag), user_data);
 310 }
 311
 312 GSourceFuncs g_unix_fd_source_funcs = {
 313   NULL, NULL, g_unix_fd_source_dispatch, NULL
 314 };
 315
 316 /**
 317  * g_unix_fd_source_new:
 318  * @fd: a file descriptor
 319  * @condition: IO conditions to watch for on @fd
 320  *
 321  * Creates a #GSource to watch for a particular IO condition on a file
 322  * descriptor.
 323  *
 324  * The source will never close the fd -- you must do it yourself.
 325  *
 326  * Returns: the newly created #GSource
 327  *
 328  * Since: 2.36
 329  **/
 330 GSource *
 331 g_unix_fd_source_new (gint         fd,
 332                       GIOCondition condition)
 333 {
 334   GUnixFDSource *fd_source;
 335   GSource *source;
 336
 337   source = g_source_new (&g_unix_fd_source_funcs, sizeof (GUnixFDSource));
 338   fd_source = (GUnixFDSource *) source;
 339
 340   fd_source->fd = fd;
 341   fd_source->tag = g_source_add_unix_fd (source, fd, condition);
 342
 343   return source;
 344 }
 345
 346 /**
 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
 354  *
 355  * Sets a function to be called when the IO condition, as specified by
 356  * @condition becomes true for @fd.
 357  *
 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
 360  * @user_data.
 361  *
 362  * Returns: the ID (greater than 0) of the event source
 363  *
 364  * Since: 2.36
 365  **/
 366 guint
 367 g_unix_fd_add_full (gint              priority,
 368                     gint              fd,
 369                     GIOCondition      condition,
 370                     GUnixFDSourceFunc function,
 371                     gpointer          user_data,
 372                     GDestroyNotify    notify)
 373 {
 374   GSource *source;
 375   guint id;
 376
 377   g_return_val_if_fail (function != NULL, 0);
 378
 379   source = g_unix_fd_source_new (fd, condition);
 380
 381   if (priority != G_PRIORITY_DEFAULT)
 382     g_source_set_priority (source, priority);
 383
 384   g_source_set_callback (source, (GSourceFunc) function, user_data, notify);
 385   id = g_source_attach (source, NULL);
 386   g_source_unref (source);
 387
 388   return id;
 389 }
 390
 391 /**
 392  * g_unix_fd_add:
 393  * @fd: a file descriptor
 394  * @condition: IO conditions to watch for on @fd
 395  * @function: a #GUnixFDSourceFunc
 396  * @user_data: data to pass to @function
 397  *
 398  * Sets a function to be called when the IO condition, as specified by
 399  * @condition becomes true for @fd.
 400  *
 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
 405  * will be cancelled.
 406  *
 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.
 409  *
 410  * The source will never close the fd -- you must do it yourself.
 411  *
 412  * Returns: the ID (greater than 0) of the event source
 413  *
 414  * Since: 2.36
 415  **/
 416 guint
 417 g_unix_fd_add (gint              fd,
 418                GIOCondition      condition,
 419                GUnixFDSourceFunc function,
 420                gpointer          user_data)
 421 {
 422   return g_unix_fd_add_full (G_PRIORITY_DEFAULT, fd, condition, function, user_data, NULL);
 423 }