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