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:gunixfdmessage
17 * @title: GUnixFDMessage
18 * @short_description: A GSocketControlMessage containing a GUnixFDList
19 * @include: gio/gunixfdmessage.h
20 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
22 * This #GSocketControlMessage contains a #GUnixFDList.
23 * It may be sent using g_socket_send_message() and received using
24 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
25 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
26 * between processes by the kernel.
28 * For an easier way to send and receive file descriptors over
29 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
30 * g_unix_connection_receive_fd().
32 * Note that <filename><gio/gunixfdmessage.h></filename> belongs to
33 * the UNIX-specific GIO interfaces, thus you have to use the
34 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
39 #include <sys/types.h>
40 #include <sys/socket.h>
46 #include "gunixfdmessage.h"
47 #include "gunixfdlist.h"
52 G_DEFINE_TYPE (GUnixFDMessage, g_unix_fd_message,
53 G_TYPE_SOCKET_CONTROL_MESSAGE);
55 struct _GUnixFDMessagePrivate
61 g_unix_fd_message_get_size (GSocketControlMessage *message)
63 GUnixFDMessage *fd_message = G_UNIX_FD_MESSAGE (message);
65 return g_unix_fd_list_get_length (fd_message->priv->list) * sizeof (gint);
69 g_unix_fd_message_get_level (GSocketControlMessage *message)
75 g_unix_fd_message_get_msg_type (GSocketControlMessage *message)
80 static GSocketControlMessage *
81 g_unix_fd_message_deserialize (int level,
86 GSocketControlMessage *message;
91 if (level != SOL_SOCKET ||
97 g_warning ("Kernel returned non-integral number of fds");
102 n = size / sizeof (gint);
104 /* Note we probably handled this in gsocket.c already if we're on
105 * Linux and have MSG_CMSG_CLOEXEC, but this code remains as a fallback
106 * in case the kernel is too old for MSG_CMSG_CLOEXEC.
108 for (i = 0; i < n; i++)
111 s = fcntl (fds[i], F_SETFD, FD_CLOEXEC);
112 while (s < 0 && errno == EINTR);
116 g_warning ("Error setting close-on-exec flag on incoming fd: %s",
122 list = g_unix_fd_list_new_from_array (fds, n);
123 message = g_unix_fd_message_new_with_fd_list (list);
124 g_object_unref (list);
130 g_unix_fd_message_serialize (GSocketControlMessage *message,
133 GUnixFDMessage *fd_message = G_UNIX_FD_MESSAGE (message);
137 fds = g_unix_fd_list_peek_fds (fd_message->priv->list, &n_fds);
138 memcpy (data, fds, sizeof (gint) * n_fds);
142 g_unix_fd_message_set_property (GObject *object, guint prop_id,
143 const GValue *value, GParamSpec *pspec)
145 GUnixFDMessage *message = G_UNIX_FD_MESSAGE (object);
147 g_assert (message->priv->list == NULL);
148 g_assert_cmpint (prop_id, ==, 1);
150 message->priv->list = g_value_dup_object (value);
152 if (message->priv->list == NULL)
153 message->priv->list = g_unix_fd_list_new ();
157 * g_unix_fd_message_get_fd_list:
158 * @message: a #GUnixFDMessage
160 * Gets the #GUnixFDList contained in @message. This function does not
161 * return a reference to the caller, but the returned list is valid for
162 * the lifetime of @message.
164 * Returns: (transfer none): the #GUnixFDList from @message
169 g_unix_fd_message_get_fd_list (GUnixFDMessage *message)
171 return message->priv->list;
175 g_unix_fd_message_get_property (GObject *object, guint prop_id,
176 GValue *value, GParamSpec *pspec)
178 GUnixFDMessage *message = G_UNIX_FD_MESSAGE (object);
180 g_assert_cmpint (prop_id, ==, 1);
182 g_value_set_object (value, g_unix_fd_message_get_fd_list (message));
186 g_unix_fd_message_init (GUnixFDMessage *message)
188 message->priv = G_TYPE_INSTANCE_GET_PRIVATE (message,
189 G_TYPE_UNIX_FD_MESSAGE,
190 GUnixFDMessagePrivate);
194 g_unix_fd_message_finalize (GObject *object)
196 GUnixFDMessage *message = G_UNIX_FD_MESSAGE (object);
198 g_object_unref (message->priv->list);
200 G_OBJECT_CLASS (g_unix_fd_message_parent_class)
205 g_unix_fd_message_class_init (GUnixFDMessageClass *class)
207 GSocketControlMessageClass *scm_class = G_SOCKET_CONTROL_MESSAGE_CLASS (class);
208 GObjectClass *object_class = G_OBJECT_CLASS (class);
210 g_type_class_add_private (class, sizeof (GUnixFDMessagePrivate));
211 scm_class->get_size = g_unix_fd_message_get_size;
212 scm_class->get_level = g_unix_fd_message_get_level;
213 scm_class->get_type = g_unix_fd_message_get_msg_type;
214 scm_class->serialize = g_unix_fd_message_serialize;
215 scm_class->deserialize = g_unix_fd_message_deserialize;
216 object_class->finalize = g_unix_fd_message_finalize;
217 object_class->set_property = g_unix_fd_message_set_property;
218 object_class->get_property = g_unix_fd_message_get_property;
220 g_object_class_install_property (object_class, 1,
221 g_param_spec_object ("fd-list", "file descriptor list",
222 "The GUnixFDList object to send with the message",
223 G_TYPE_UNIX_FD_LIST, G_PARAM_STATIC_STRINGS |
224 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
228 * g_unix_fd_message_new:
230 * Creates a new #GUnixFDMessage containing an empty file descriptor
233 * Returns: a new #GUnixFDMessage
237 GSocketControlMessage *
238 g_unix_fd_message_new (void)
240 return g_object_new (G_TYPE_UNIX_FD_MESSAGE, NULL);
244 * g_unix_fd_message_new_with_fd_list:
245 * @fd_list: a #GUnixFDList
247 * Creates a new #GUnixFDMessage containing @list.
249 * Returns: a new #GUnixFDMessage
253 GSocketControlMessage *
254 g_unix_fd_message_new_with_fd_list (GUnixFDList *fd_list)
256 return g_object_new (G_TYPE_UNIX_FD_MESSAGE,
262 * g_unix_fd_message_steal_fds:
263 * @message: a #GUnixFDMessage
264 * @length: (out) (allow-none): pointer to the length of the returned
267 * Returns the array of file descriptors that is contained in this
270 * After this call, the descriptors are no longer contained in
271 * @message. Further calls will return an empty list (unless more
272 * descriptors have been added).
274 * The return result of this function must be freed with g_free().
275 * The caller is also responsible for closing all of the file
278 * If @length is non-%NULL then it is set to the number of file
279 * descriptors in the returned array. The returned array is also
280 * terminated with -1.
282 * This function never returns %NULL. In case there are no file
283 * descriptors contained in @message, an empty array is returned.
285 * Returns: (array length=length) (transfer full): an array of file
291 g_unix_fd_message_steal_fds (GUnixFDMessage *message,
294 g_return_val_if_fail (G_UNIX_FD_MESSAGE (message), NULL);
296 return g_unix_fd_list_steal_fds (message->priv->list, length);
300 * g_unix_fd_message_append_fd:
301 * @message: a #GUnixFDMessage
302 * @fd: a valid open file descriptor
303 * @error: a #GError pointer
305 * Adds a file descriptor to @message.
307 * The file descriptor is duplicated using dup(). You keep your copy
308 * of the descriptor and the copy contained in @message will be closed
309 * when @message is finalized.
311 * A possible cause of failure is exceeding the per-process or
312 * system-wide file descriptor limit.
314 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
319 g_unix_fd_message_append_fd (GUnixFDMessage *message,
323 g_return_val_if_fail (G_UNIX_FD_MESSAGE (message), FALSE);
325 return g_unix_fd_list_append (message->priv->list, fd, error) >= 0;