1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2009 Codethink Limited
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.
10 * See the included COPYING file for more information.
12 * Authors: Ryan Lortie <desrt@desrt.ca>
16 * SECTION: gunixfdlist
18 * @short_description: An object containing a set of UNIX file descriptors
19 * @include: gio/gunixfdlist.h
20 * @see_also: #GUnixFDMessage
22 * A #GUnixFDList contains a list of file descriptors. It owns the file
23 * descriptors that it contains, closing them when finalized.
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().
29 * Note that <filename><gio/gunixfdlist.h></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.
34 #define _GNU_SOURCE /* for F_DUPFD_CLOEXEC */
38 #include <sys/types.h>
39 #include <sys/socket.h>
45 #include "gunixfdlist.h"
51 G_DEFINE_TYPE (GUnixFDList, g_unix_fd_list, G_TYPE_OBJECT)
53 struct _GUnixFDListPrivate
60 g_unix_fd_list_init (GUnixFDList *list)
62 list->priv = G_TYPE_INSTANCE_GET_PRIVATE (list,
68 g_unix_fd_list_finalize (GObject *object)
70 GUnixFDList *list = G_UNIX_FD_LIST (object);
73 for (i = 0; i < list->priv->nfd; i++)
74 close (list->priv->fds[i]);
75 g_free (list->priv->fds);
77 G_OBJECT_CLASS (g_unix_fd_list_parent_class)
82 g_unix_fd_list_class_init (GUnixFDListClass *class)
84 GObjectClass *object_class = G_OBJECT_CLASS (class);
86 g_type_class_add_private (class, sizeof (GUnixFDListPrivate));
87 object_class->finalize = g_unix_fd_list_finalize;
91 dup_close_on_exec_fd (gint fd,
97 #ifdef F_DUPFD_CLOEXEC
99 new_fd = fcntl (fd, F_DUPFD_CLOEXEC, 0l);
100 while (new_fd < 0 && (errno == EINTR));
105 /* if that didn't work (new libc/old kernel?), try it the other way. */
110 while (new_fd < 0 && (errno == EINTR));
114 int saved_errno = errno;
116 g_set_error (error, G_IO_ERROR,
117 g_io_error_from_errno (saved_errno),
118 "dup: %s", g_strerror (saved_errno));
126 s = fcntl (new_fd, F_GETFD);
129 s = fcntl (new_fd, F_SETFD, (long) (s | FD_CLOEXEC));
131 while (s < 0 && (errno == EINTR));
135 int saved_errno = errno;
137 g_set_error (error, G_IO_ERROR,
138 g_io_error_from_errno (saved_errno),
139 "fcntl: %s", g_strerror (saved_errno));
149 * g_unix_fd_list_new:
151 * Creates a new #GUnixFDList containing no file descriptors.
153 * Returns: a new #GUnixFDList
158 g_unix_fd_list_new (void)
160 return g_object_new (G_TYPE_UNIX_FD_LIST, NULL);
164 * g_unix_fd_list_new_from_array:
165 * @fds: the initial list of file descriptors
166 * @n_fds: the length of #fds, or -1
168 * Creates a new #GUnixFDList containing the file descriptors given in
169 * @fds. The file descriptors become the property of the new list and
170 * may no longer be used by the caller. The array itself is owned by
173 * Each file descriptor in the array should be set to close-on-exec.
175 * If @n_fds is -1 then @fds must be terminated with -1.
177 * Returns: a new #GUnixFDList
182 g_unix_fd_list_new_from_array (const gint *fds,
187 g_return_val_if_fail (fds != NULL || n_fds == 0, NULL);
190 for (n_fds = 0; fds[n_fds] != -1; n_fds++);
192 list = g_object_new (G_TYPE_UNIX_FD_LIST, NULL);
193 list->priv->fds = g_new (gint, n_fds + 1);
194 list->priv->nfd = n_fds;
196 memcpy (list->priv->fds, fds, sizeof (gint) * n_fds);
197 list->priv->fds[n_fds] = -1;
203 * g_unix_fd_list_steal_fds:
204 * @list: a #GUnixFDList
205 * @length: pointer to the length of the returned array, or %NULL
207 * Returns the array of file descriptors that is contained in this
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).
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
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.
223 * This function never returns %NULL. In case there are no file
224 * descriptors contained in @list, an empty array is returned.
226 * Returns: an array of file descriptors
231 g_unix_fd_list_steal_fds (GUnixFDList *list,
236 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), NULL);
238 /* will be true for fresh object or if we were just called */
239 if (list->priv->fds == NULL)
241 list->priv->fds = g_new (gint, 1);
242 list->priv->fds[0] = -1;
247 *length = list->priv->nfd;
248 result = list->priv->fds;
250 list->priv->fds = NULL;
257 * g_unix_fd_list_peek_fds:
258 * @list: a #GUnixFDList
259 * @length: pointer to the length of the returned array, or %NULL
261 * Returns the array of file descriptors that is contained in this
264 * After this call, the descriptors remain the property of @list. The
265 * caller must not close them and must not free the array. The array is
266 * valid only until @list is changed in any way.
268 * If @length is non-%NULL then it is set to the number of file
269 * descriptors in the returned array. The returned array is also
270 * terminated with -1.
272 * This function never returns %NULL. In case there are no file
273 * descriptors contained in @list, an empty array is returned.
275 * Returns: an array of file descriptors
280 g_unix_fd_list_peek_fds (GUnixFDList *list,
283 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), NULL);
285 /* will be true for fresh object or if steal() was just called */
286 if (list->priv->fds == NULL)
288 list->priv->fds = g_new (gint, 1);
289 list->priv->fds[0] = -1;
294 *length = list->priv->nfd;
296 return list->priv->fds;
300 * g_unix_fd_list_append:
301 * @list: a #GUnixFDList
302 * @fd: a valid open file descriptor
303 * @error: a #GError pointer
305 * Adds a file descriptor to @list.
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.
311 * A possible cause of failure is exceeding the per-process or
312 * system-wide file descriptor limit.
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.
318 * Returns: the index of the appended fd in case of success, else -1
319 * (and @error is set)
324 g_unix_fd_list_append (GUnixFDList *list,
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);
334 if ((new_fd = dup_close_on_exec_fd (fd, error)) < 0)
337 list->priv->fds = g_realloc (list->priv->fds,
339 (list->priv->nfd + 2));
340 list->priv->fds[list->priv->nfd++] = new_fd;
341 list->priv->fds[list->priv->nfd] = -1;
343 return list->priv->nfd - 1;
347 * g_unix_fd_list_get:
348 * @list: a #GUnixFDList
349 * @index_: the index into the list
350 * @error: a #GError pointer
352 * Gets a file descriptor out of @list.
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().
358 * The file descriptor is duplicated using dup() and set as
359 * close-on-exec before being returned. You must call close() on it
362 * A possible cause of failure is exceeding the per-process or
363 * system-wide file descriptor limit.
365 * Returns: the file descriptor, or -1 in case of error
370 g_unix_fd_list_get (GUnixFDList *list,
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);
378 return dup_close_on_exec_fd (list->priv->fds[index_], error);
382 * g_unix_fd_list_get_length:
383 * @list: a #GUnixFDList
385 * Gets the length of @list (ie: the number of file descriptors
388 * Returns: the length of @list
393 g_unix_fd_list_get_length (GUnixFDList *list)
395 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list), 0);
397 return list->priv->nfd;
400 #define __G_UNIX_FD_LIST_C__
401 #include "gioaliasdef.c"