gio/gunixfdlist.c

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