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