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