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>
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.
36 #include <sys/types.h>
37 #include <sys/socket.h>
43 #include "gunixfdlist.h"
48 G_DEFINE_TYPE (GUnixFDList
, g_unix_fd_list
, G_TYPE_OBJECT
)
50 struct _GUnixFDListPrivate
57 g_unix_fd_list_init (GUnixFDList
*list
)
59 list
->priv
= G_TYPE_INSTANCE_GET_PRIVATE (list
,
65 g_unix_fd_list_finalize (GObject
*object
)
67 GUnixFDList
*list
= G_UNIX_FD_LIST (object
);
70 for (i
= 0; i
< list
->priv
->nfd
; i
++)
71 close (list
->priv
->fds
[i
]);
72 g_free (list
->priv
->fds
);
74 G_OBJECT_CLASS (g_unix_fd_list_parent_class
)
79 g_unix_fd_list_class_init (GUnixFDListClass
*class)
81 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
83 g_type_class_add_private (class, sizeof (GUnixFDListPrivate
));
84 object_class
->finalize
= g_unix_fd_list_finalize
;
88 dup_close_on_exec_fd (gint fd
,
94 #ifdef F_DUPFD_CLOEXEC
96 new_fd
= fcntl (fd
, F_DUPFD_CLOEXEC
, 0l);
97 while (new_fd
< 0 && (errno
== EINTR
));
102 /* if that didn't work (new libc/old kernel?), try it the other way. */
107 while (new_fd
< 0 && (errno
== EINTR
));
111 int saved_errno
= errno
;
113 g_set_error (error
, G_IO_ERROR
,
114 g_io_error_from_errno (saved_errno
),
115 "dup: %s", g_strerror (saved_errno
));
122 s
= fcntl (new_fd
, F_GETFD
);
125 s
= fcntl (new_fd
, F_SETFD
, (long) (s
| FD_CLOEXEC
));
127 while (s
< 0 && (errno
== EINTR
));
131 int saved_errno
= errno
;
133 g_set_error (error
, G_IO_ERROR
,
134 g_io_error_from_errno (saved_errno
),
135 "fcntl: %s", g_strerror (saved_errno
));
145 * g_unix_fd_list_new:
147 * Creates a new #GUnixFDList containing no file descriptors.
149 * Returns: a new #GUnixFDList
154 g_unix_fd_list_new (void)
156 return g_object_new (G_TYPE_UNIX_FD_LIST
, NULL
);
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
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
169 * Each file descriptor in the array should be set to close-on-exec.
171 * If @n_fds is -1 then @fds must be terminated with -1.
173 * Returns: a new #GUnixFDList
178 g_unix_fd_list_new_from_array (const gint
*fds
,
183 g_return_val_if_fail (fds
!= NULL
|| n_fds
== 0, NULL
);
186 for (n_fds
= 0; fds
[n_fds
] != -1; n_fds
++);
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
;
192 memcpy (list
->priv
->fds
, fds
, sizeof (gint
) * n_fds
);
193 list
->priv
->fds
[n_fds
] = -1;
199 * g_unix_fd_list_steal_fds:
200 * @list: a #GUnixFDList
201 * @length: (out) (allow-none): pointer to the length of the returned
204 * Returns the array of file descriptors that is contained in this
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).
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
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.
220 * This function never returns %NULL. In case there are no file
221 * descriptors contained in @list, an empty array is returned.
223 * Returns: (array length=length) (transfer full): an array of file
229 g_unix_fd_list_steal_fds (GUnixFDList
*list
,
234 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list
), NULL
);
236 /* will be true for fresh object or if we were just called */
237 if (list
->priv
->fds
== NULL
)
239 list
->priv
->fds
= g_new (gint
, 1);
240 list
->priv
->fds
[0] = -1;
245 *length
= list
->priv
->nfd
;
246 result
= list
->priv
->fds
;
248 list
->priv
->fds
= NULL
;
255 * g_unix_fd_list_peek_fds:
256 * @list: a #GUnixFDList
257 * @length: (out) (allow-none): pointer to the length of the returned
260 * Returns the array of file descriptors that is contained in this
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.
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.
271 * This function never returns %NULL. In case there are no file
272 * descriptors contained in @list, an empty array is returned.
274 * Returns: (array length=length) (transfer none): an array of file
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
;