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