gio/gunixfdlist.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2009 Codethink Limited
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU Lesser General Public License as published
   7  * by the Free Software Foundation; either version 2 of the licence or (at
   8  * your option) any later version.
   9  *
  10  * See the included COPYING file for more information.
  11  *
  12  * Authors: Ryan Lortie <desrt@desrt.ca>
  13  */
  14
  15 /**
  16  * SECTION:gunixfdlist
  17  * @title: GUnixFDList
  18  * @short_description: An object containing a set of UNIX file descriptors
  19  * @include: gio/gunixfdlist.h
  20  * @see_also: #GUnixFDMessage
  21  *
  22  * A #GUnixFDList contains a list of file descriptors.  It owns the file
  23  * descriptors that it contains, closing them when finalized.
  24  *
  25  * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
  26  * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
  27  * and received using g_socket_receive_message().
  28  *
  29  * Note that <filename>&lt;gio/gunixfdlist.h&gt;</filename> belongs to
  30  * the UNIX-specific GIO interfaces, thus you have to use the
  31  * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
  32  */
  33
  34 #include "config.h"
  35
  36 #include <unistd.h>
  37 #include <fcntl.h>
  38 #include <string.h>
  39 #include <errno.h>
  40
  41 #include "gunixfdlist.h"
  42 #include "gnetworking.h"
  43 #include "gioerror.h"
  44
  45 struct _GUnixFDListPrivate
  46 {
  47   gint *fds;
  48   gint nfd;
  49 };
  50
  51 G_DEFINE_TYPE_WITH_PRIVATE (GUnixFDList, g_unix_fd_list, G_TYPE_OBJECT)
  52
  53 static void
  54 g_unix_fd_list_init (GUnixFDList *list)
  55 {
  56   list->priv = g_unix_fd_list_get_instance_private (list);
  57 }
  58
  59 static void
  60 g_unix_fd_list_finalize (GObject *object)
  61 {
  62   GUnixFDList *list = G_UNIX_FD_LIST (object);
  63   gint i;
  64
  65   for (i = 0; i < list->priv->nfd; i++)
  66     close (list->priv->fds[i]);
  67   g_free (list->priv->fds);
  68
  69   G_OBJECT_CLASS (g_unix_fd_list_parent_class)
  70     ->finalize (object);
  71 }
  72
  73 static void
  74 g_unix_fd_list_class_init (GUnixFDListClass *class)
  75 {
  76   GObjectClass *object_class = G_OBJECT_CLASS (class);
  77
  78   object_class->finalize = g_unix_fd_list_finalize;
  79 }
  80
  81 static int
  82 dup_close_on_exec_fd (gint     fd,
  83                       GError **error)
  84 {
  85   gint new_fd;
  86   gint s;
  87
  88 #ifdef F_DUPFD_CLOEXEC
  89   do
  90     new_fd = fcntl (fd, F_DUPFD_CLOEXEC, 0l);
  91   while (new_fd < 0 && (errno == EINTR));
  92
  93   if (new_fd >= 0)
  94     return new_fd;
  95
  96   /* if that didn't work (new libc/old kernel?), try it the other way. */
  97 #endif
  98
  99   do
 100     new_fd = dup (fd);
 101   while (new_fd < 0 && (errno == EINTR));
 102
 103   if (new_fd < 0)
 104     {
 105       int saved_errno = errno;
 106
 107       g_set_error (error, G_IO_ERROR,
 108                    g_io_error_from_errno (saved_errno),
 109                    "dup: %s", g_strerror (saved_errno));
 110
 111       return -1;
 112     }
 113
 114   do
 115     {
 116       s = fcntl (new_fd, F_GETFD);
 117
 118       if (s >= 0)
 119         s = fcntl (new_fd, F_SETFD, (long) (s | FD_CLOEXEC));
 120     }
 121   while (s < 0 && (errno == EINTR));
 122
 123   if (s < 0)
 124     {
 125       int saved_errno = errno;
 126
 127       g_set_error (error, G_IO_ERROR,
 128                    g_io_error_from_errno (saved_errno),
 129                    "fcntl: %s", g_strerror (saved_errno));
 130       close (new_fd);
 131
 132       return -1;
 133     }
 134
 135   return new_fd;
 136 }
 137
 138 /**
 139  * g_unix_fd_list_new:
 140  *
 141  * Creates a new #GUnixFDList containing no file descriptors.
 142  *
 143  * Returns: a new #GUnixFDList
 144  *
 145  * Since: 2.24
 146  **/
 147 GUnixFDList *
 148 g_unix_fd_list_new (void)
 149 {
 150   return g_object_new (G_TYPE_UNIX_FD_LIST, NULL);
 151 }
 152
 153 /**
 154  * g_unix_fd_list_new_from_array:
 155  * @fds: (array length=n_fds): the initial list of file descriptors
 156  * @n_fds: the length of #fds, or -1
 157  *
 158  * Creates a new #GUnixFDList containing the file descriptors given in
 159  * @fds.  The file descriptors become the property of the new list and
 160  * may no longer be used by the caller.  The array itself is owned by
 161  * the caller.
 162  *
 163  * Each file descriptor in the array should be set to close-on-exec.
 164  *
 165  * If @n_fds is -1 then @fds must be terminated with -1.
 166  *
 167  * Returns: a new #GUnixFDList
 168  *
 169  * Since: 2.24
 170  **/
 171 GUnixFDList *
 172 g_unix_fd_list_new_from_array (const gint *fds,
 173                                gint        n_fds)
 174 {
 175   GUnixFDList *list;
 176
 177   g_return_val_if_fail (fds != NULL || n_fds == 0, NULL);
 178
 179   if (n_fds == -1)
 180     for (n_fds = 0; fds[n_fds] != -1; n_fds++);
 181
 182   list = g_object_new (G_TYPE_UNIX_FD_LIST, NULL);
 183   list->priv->fds = g_new (gint, n_fds + 1);
 184   list->priv->nfd = n_fds;
 185
 186   memcpy (list->priv->fds, fds, sizeof (gint) * n_fds);
 187   list->priv->fds[n_fds] = -1;
 188
 189   return list;
 190 }
 191
 192 /**
 193  * g_unix_fd_list_steal_fds:
 194  * @list: a #GUnixFDList
 195  * @length: (out) (allow-none): pointer to the length of the returned
 196  *     array, or %NULL
 197  *
 198  * Returns the array of file descriptors that is contained in this
 199  * object.
 200  *
 201  * After this call, the descriptors are no longer contained in
 202  * @list. Further calls will return an empty list (unless more
 203  * descriptors have been added).
 204  *
 205  * The return result of this function must be freed with g_free().
 206  * The caller is also responsible for closing all of the file
 207  * descriptors.  The file descriptors in the array are set to
 208  * close-on-exec.
 209  *
 210  * If @length is non-%NULL then it is set to the number of file
 211  * descriptors in the returned array. The returned array is also
 212  * terminated with -1.
 213  *
 214  * This function never returns %NULL. In case there are no file
 215  * descriptors contained in @list, an empty array is returned.
 216  *
 217  * Returns: (array length=length) (transfer full): an array of file
 218  *     descriptors
 219  *
 220  * Since: 2.24
 221  */
 222 gint *
 223 g_unix_fd_list_steal_fds (GUnixFDList *list,
 224                           gint        *length)
 225 {
 226   gint *result;
 227
 228   g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), NULL);
 229
 230   /* will be true for fresh object or if we were just called */
 231   if (list->priv->fds == NULL)
 232     {
 233       list->priv->fds = g_new (gint, 1);
 234       list->priv->fds[0] = -1;
 235       list->priv->nfd = 0;
 236     }
 237
 238   if (length)
 239     *length = list->priv->nfd;
 240   result = list->priv->fds;
 241
 242   list->priv->fds = NULL;
 243   list->priv->nfd = 0;
 244
 245   return result;
 246 }
 247
 248 /**
 249  * g_unix_fd_list_peek_fds:
 250  * @list: a #GUnixFDList
 251  * @length: (out) (allow-none): pointer to the length of the returned
 252  *     array, or %NULL
 253  *
 254  * Returns the array of file descriptors that is contained in this
 255  * object.
 256  *
 257  * After this call, the descriptors remain the property of @list.  The
 258  * caller must not close them and must not free the array.  The array is
 259  * valid only until @list is changed in any way.
 260  *
 261  * If @length is non-%NULL then it is set to the number of file
 262  * descriptors in the returned array. The returned array is also
 263  * terminated with -1.
 264  *
 265  * This function never returns %NULL. In case there are no file
 266  * descriptors contained in @list, an empty array is returned.
 267  *
 268  * Returns: (array length=length) (transfer none): an array of file
 269  *     descriptors
 270  *
 271  * Since: 2.24
 272  */
 273 const gint *
 274 g_unix_fd_list_peek_fds (GUnixFDList *list,
 275                          gint        *length)
 276 {
 277   g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), NULL);
 278
 279   /* will be true for fresh object or if steal() was just called */
 280   if (list->priv->fds == NULL)
 281     {
 282       list->priv->fds = g_new (gint, 1);
 283       list->priv->fds[0] = -1;
 284       list->priv->nfd = 0;
 285     }
 286
 287   if (length)
 288     *length = list->priv->nfd;
 289
 290   return list->priv->fds;
 291 }
 292
 293 /**
 294  * g_unix_fd_list_append:
 295  * @list: a #GUnixFDList
 296  * @fd: a valid open file descriptor
 297  * @error: a #GError pointer
 298  *
 299  * Adds a file descriptor to @list.
 300  *
 301  * The file descriptor is duplicated using dup(). You keep your copy
 302  * of the descriptor and the copy contained in @list will be closed
 303  * when @list is finalized.
 304  *
 305  * A possible cause of failure is exceeding the per-process or
 306  * system-wide file descriptor limit.
 307  *
 308  * The index of the file descriptor in the list is returned.  If you use
 309  * this index with g_unix_fd_list_get() then you will receive back a
 310  * duplicated copy of the same file descriptor.
 311  *
 312  * Returns: the index of the appended fd in case of success, else -1
 313  *          (and @error is set)
 314  *
 315  * Since: 2.24
 316  */
 317 gint
 318 g_unix_fd_list_append (GUnixFDList  *list,
 319                        gint          fd,
 320                        GError      **error)
 321 {
 322   gint new_fd;
 323
 324   g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), -1);
 325   g_return_val_if_fail (fd >= 0, -1);
 326   g_return_val_if_fail (error == NULL || *error == NULL, -1);
 327
 328   if ((new_fd = dup_close_on_exec_fd (fd, error)) < 0)
 329     return -1;
 330
 331   list->priv->fds = g_realloc (list->priv->fds,
 332                                   sizeof (gint) *
 333                                    (list->priv->nfd + 2));
 334   list->priv->fds[list->priv->nfd++] = new_fd;
 335   list->priv->fds[list->priv->nfd] = -1;
 336
 337   return list->priv->nfd - 1;
 338 }
 339
 340 /**
 341  * g_unix_fd_list_get:
 342  * @list: a #GUnixFDList
 343  * @index_: the index into the list
 344  * @error: a #GError pointer
 345  *
 346  * Gets a file descriptor out of @list.
 347  *
 348  * @index_ specifies the index of the file descriptor to get.  It is a
 349  * programmer error for @index_ to be out of range; see
 350  * g_unix_fd_list_get_length().
 351  *
 352  * The file descriptor is duplicated using dup() and set as
 353  * close-on-exec before being returned.  You must call close() on it
 354  * when you are done.
 355  *
 356  * A possible cause of failure is exceeding the per-process or
 357  * system-wide file descriptor limit.
 358  *
 359  * Returns: the file descriptor, or -1 in case of error
 360  *
 361  * Since: 2.24
 362  **/
 363 gint
 364 g_unix_fd_list_get (GUnixFDList  *list,
 365                     gint          index_,
 366                     GError      **error)
 367 {
 368   g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), -1);
 369   g_return_val_if_fail (index_ < list->priv->nfd, -1);
 370   g_return_val_if_fail (error == NULL || *error == NULL, -1);
 371
 372   return dup_close_on_exec_fd (list->priv->fds[index_], error);
 373 }
 374
 375 /**
 376  * g_unix_fd_list_get_length:
 377  * @list: a #GUnixFDList
 378  *
 379  * Gets the length of @list (ie: the number of file descriptors
 380  * contained within).
 381  *
 382  * Returns: the length of @list
 383  *
 384  * Since: 2.24
 385  **/
 386 gint
 387 g_unix_fd_list_get_length (GUnixFDList *list)
 388 {
 389   g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), 0);
 390
 391   return list->priv->nfd;
 392 }