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.
41 #include "gunixfdlist.h"
42 #include "gnetworking.h"
45 struct _GUnixFDListPrivate
51 G_DEFINE_TYPE_WITH_PRIVATE (GUnixFDList
, g_unix_fd_list
, G_TYPE_OBJECT
)
54 g_unix_fd_list_init (GUnixFDList
*list
)
56 list
->priv
= g_unix_fd_list_get_instance_private (list
);
60 g_unix_fd_list_finalize (GObject
*object
)
62 GUnixFDList
*list
= G_UNIX_FD_LIST (object
);
65 for (i
= 0; i
< list
->priv
->nfd
; i
++)
66 close (list
->priv
->fds
[i
]);
67 g_free (list
->priv
->fds
);
69 G_OBJECT_CLASS (g_unix_fd_list_parent_class
)
74 g_unix_fd_list_class_init (GUnixFDListClass
*class)
76 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
78 object_class
->finalize
= g_unix_fd_list_finalize
;
82 dup_close_on_exec_fd (gint fd
,
88 #ifdef F_DUPFD_CLOEXEC
90 new_fd
= fcntl (fd
, F_DUPFD_CLOEXEC
, 0l);
91 while (new_fd
< 0 && (errno
== EINTR
));
96 /* if that didn't work (new libc/old kernel?), try it the other way. */
101 while (new_fd
< 0 && (errno
== EINTR
));
105 int saved_errno
= errno
;
107 g_set_error (error
, G_IO_ERROR
,
108 g_io_error_from_errno (saved_errno
),
109 "dup: %s", g_strerror (saved_errno
));
116 s
= fcntl (new_fd
, F_GETFD
);
119 s
= fcntl (new_fd
, F_SETFD
, (long) (s
| FD_CLOEXEC
));
121 while (s
< 0 && (errno
== EINTR
));
125 int saved_errno
= errno
;
127 g_set_error (error
, G_IO_ERROR
,
128 g_io_error_from_errno (saved_errno
),
129 "fcntl: %s", g_strerror (saved_errno
));
139 * g_unix_fd_list_new:
141 * Creates a new #GUnixFDList containing no file descriptors.
143 * Returns: a new #GUnixFDList
148 g_unix_fd_list_new (void)
150 return g_object_new (G_TYPE_UNIX_FD_LIST
, NULL
);
154 * g_unix_fd_list_new_from_array:
155 * @fds: (array length=n_fds): the initial list of file descriptors
156 * @n_fds: the length of #fds, or -1
158 * Creates a new #GUnixFDList containing the file descriptors given in
159 * @fds. The file descriptors become the property of the new list and
160 * may no longer be used by the caller. The array itself is owned by
163 * Each file descriptor in the array should be set to close-on-exec.
165 * If @n_fds is -1 then @fds must be terminated with -1.
167 * Returns: a new #GUnixFDList
172 g_unix_fd_list_new_from_array (const gint
*fds
,
177 g_return_val_if_fail (fds
!= NULL
|| n_fds
== 0, NULL
);
180 for (n_fds
= 0; fds
[n_fds
] != -1; n_fds
++);
182 list
= g_object_new (G_TYPE_UNIX_FD_LIST
, NULL
);
183 list
->priv
->fds
= g_new (gint
, n_fds
+ 1);
184 list
->priv
->nfd
= n_fds
;
186 memcpy (list
->priv
->fds
, fds
, sizeof (gint
) * n_fds
);
187 list
->priv
->fds
[n_fds
] = -1;
193 * g_unix_fd_list_steal_fds:
194 * @list: a #GUnixFDList
195 * @length: (out) (allow-none): pointer to the length of the returned
198 * Returns the array of file descriptors that is contained in this
201 * After this call, the descriptors are no longer contained in
202 * @list. Further calls will return an empty list (unless more
203 * descriptors have been added).
205 * The return result of this function must be freed with g_free().
206 * The caller is also responsible for closing all of the file
207 * descriptors. The file descriptors in the array are set to
210 * If @length is non-%NULL then it is set to the number of file
211 * descriptors in the returned array. The returned array is also
212 * terminated with -1.
214 * This function never returns %NULL. In case there are no file
215 * descriptors contained in @list, an empty array is returned.
217 * Returns: (array length=length) (transfer full): an array of file
223 g_unix_fd_list_steal_fds (GUnixFDList
*list
,
228 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list
), NULL
);
230 /* will be true for fresh object or if we were just called */
231 if (list
->priv
->fds
== NULL
)
233 list
->priv
->fds
= g_new (gint
, 1);
234 list
->priv
->fds
[0] = -1;
239 *length
= list
->priv
->nfd
;
240 result
= list
->priv
->fds
;
242 list
->priv
->fds
= NULL
;
249 * g_unix_fd_list_peek_fds:
250 * @list: a #GUnixFDList
251 * @length: (out) (allow-none): pointer to the length of the returned
254 * Returns the array of file descriptors that is contained in this
257 * After this call, the descriptors remain the property of @list. The
258 * caller must not close them and must not free the array. The array is
259 * valid only until @list is changed in any way.
261 * If @length is non-%NULL then it is set to the number of file
262 * descriptors in the returned array. The returned array is also
263 * terminated with -1.
265 * This function never returns %NULL. In case there are no file
266 * descriptors contained in @list, an empty array is returned.
268 * Returns: (array length=length) (transfer none): an array of file
274 g_unix_fd_list_peek_fds (GUnixFDList
*list
,
277 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list
), NULL
);
279 /* will be true for fresh object or if steal() was just called */
280 if (list
->priv
->fds
== NULL
)
282 list
->priv
->fds
= g_new (gint
, 1);
283 list
->priv
->fds
[0] = -1;
288 *length
= list
->priv
->nfd
;
290 return list
->priv
->fds
;
294 * g_unix_fd_list_append:
295 * @list: a #GUnixFDList
296 * @fd: a valid open file descriptor
297 * @error: a #GError pointer
299 * Adds a file descriptor to @list.
301 * The file descriptor is duplicated using dup(). You keep your copy
302 * of the descriptor and the copy contained in @list will be closed
303 * when @list is finalized.
305 * A possible cause of failure is exceeding the per-process or
306 * system-wide file descriptor limit.
308 * The index of the file descriptor in the list is returned. If you use
309 * this index with g_unix_fd_list_get() then you will receive back a
310 * duplicated copy of the same file descriptor.
312 * Returns: the index of the appended fd in case of success, else -1
313 * (and @error is set)
318 g_unix_fd_list_append (GUnixFDList
*list
,
324 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list
), -1);
325 g_return_val_if_fail (fd
>= 0, -1);
326 g_return_val_if_fail (error
== NULL
|| *error
== NULL
, -1);
328 if ((new_fd
= dup_close_on_exec_fd (fd
, error
)) < 0)
331 list
->priv
->fds
= g_realloc (list
->priv
->fds
,
333 (list
->priv
->nfd
+ 2));
334 list
->priv
->fds
[list
->priv
->nfd
++] = new_fd
;
335 list
->priv
->fds
[list
->priv
->nfd
] = -1;
337 return list
->priv
->nfd
- 1;
341 * g_unix_fd_list_get:
342 * @list: a #GUnixFDList
343 * @index_: the index into the list
344 * @error: a #GError pointer
346 * Gets a file descriptor out of @list.
348 * @index_ specifies the index of the file descriptor to get. It is a
349 * programmer error for @index_ to be out of range; see
350 * g_unix_fd_list_get_length().
352 * The file descriptor is duplicated using dup() and set as
353 * close-on-exec before being returned. You must call close() on it
356 * A possible cause of failure is exceeding the per-process or
357 * system-wide file descriptor limit.
359 * Returns: the file descriptor, or -1 in case of error
364 g_unix_fd_list_get (GUnixFDList
*list
,
368 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list
), -1);
369 g_return_val_if_fail (index_
< list
->priv
->nfd
, -1);
370 g_return_val_if_fail (error
== NULL
|| *error
== NULL
, -1);
372 return dup_close_on_exec_fd (list
->priv
->fds
[index_
], error
);
376 * g_unix_fd_list_get_length:
377 * @list: a #GUnixFDList
379 * Gets the length of @list (ie: the number of file descriptors
382 * Returns: the length of @list
387 g_unix_fd_list_get_length (GUnixFDList
*list
)
389 g_return_val_if_fail (G_IS_UNIX_FD_LIST (list
), 0);
391 return list
->priv
->nfd
;