1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2009 Codethink Limited
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
10 * See the included COPYING file for more information.
12 * Authors: Ryan Lortie <desrt@desrt.ca>
17 #include "gunixconnection.h"
18 #include "gnetworking.h"
20 #include "gsocketcontrolmessage.h"
21 #include "gunixcredentialsmessage.h"
22 #include "gunixfdmessage.h"
30 * SECTION:gunixconnection
31 * @title: GUnixConnection
32 * @short_description: A UNIX domain GSocketConnection
33 * @include: gio/gunixconnection.h
34 * @see_also: #GSocketConnection.
36 * This is the subclass of #GSocketConnection that is created
37 * for UNIX domain sockets.
39 * It contains functions to do some of the UNIX socket specific
40 * functionality like passing file descriptors.
42 * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
43 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
44 * pkg-config file when using it.
52 * #GUnixConnection is an opaque data structure and can only be accessed
53 * using the following functions.
56 G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection,
57 G_TYPE_SOCKET_CONNECTION,
58 g_socket_connection_factory_register_type (g_define_type_id,
61 G_SOCKET_PROTOCOL_DEFAULT);
65 * g_unix_connection_send_fd:
66 * @connection: a #GUnixConnection
67 * @fd: a file descriptor
68 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
69 * @error: (nullable): #GError for error reporting, or %NULL to ignore.
71 * Passes a file descriptor to the receiving side of the
72 * connection. The receiving end has to call g_unix_connection_receive_fd()
73 * to accept the file descriptor.
75 * As well as sending the fd this also writes a single byte to the
76 * stream, as this is required for fd passing to work on some
79 * Returns: a %TRUE on success, %NULL on error.
84 g_unix_connection_send_fd (GUnixConnection *connection,
86 GCancellable *cancellable,
89 GSocketControlMessage *scm;
92 g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), FALSE);
93 g_return_val_if_fail (fd >= 0, FALSE);
95 scm = g_unix_fd_message_new ();
97 if (!g_unix_fd_message_append_fd (G_UNIX_FD_MESSAGE (scm), fd, error))
103 g_object_get (connection, "socket", &socket, NULL);
104 if (g_socket_send_message (socket, NULL, NULL, 0, &scm, 1, 0, cancellable, error) != 1)
105 /* XXX could it 'fail' with zero? */
107 g_object_unref (socket);
108 g_object_unref (scm);
113 g_object_unref (socket);
114 g_object_unref (scm);
120 * g_unix_connection_receive_fd:
121 * @connection: a #GUnixConnection
122 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
123 * @error: (nullable): #GError for error reporting, or %NULL to ignore
125 * Receives a file descriptor from the sending end of the connection.
126 * The sending end has to call g_unix_connection_send_fd() for this
129 * As well as reading the fd this also reads a single byte from the
130 * stream, as this is required for fd passing to work on some
133 * Returns: a file descriptor on success, -1 on error.
138 g_unix_connection_receive_fd (GUnixConnection *connection,
139 GCancellable *cancellable,
142 GSocketControlMessage **scms;
143 gint *fds, nfd, fd, nscm;
144 GUnixFDMessage *fdmsg;
147 g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), -1);
149 g_object_get (connection, "socket", &socket, NULL);
150 if (g_socket_receive_message (socket, NULL, NULL, 0,
151 &scms, &nscm, NULL, cancellable, error) != 1)
152 /* XXX it _could_ 'fail' with zero. */
154 g_object_unref (socket);
159 g_object_unref (socket);
165 g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
166 ngettext("Expecting 1 control message, got %d",
167 "Expecting 1 control message, got %d",
171 for (i = 0; i < nscm; i++)
172 g_object_unref (scms[i]);
179 if (!G_IS_UNIX_FD_MESSAGE (scms[0]))
181 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
182 _("Unexpected type of ancillary data"));
183 g_object_unref (scms[0]);
189 fdmsg = G_UNIX_FD_MESSAGE (scms[0]);
192 fds = g_unix_fd_message_steal_fds (fdmsg, &nfd);
193 g_object_unref (fdmsg);
199 g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
200 ngettext("Expecting one fd, but got %d\n",
201 "Expecting one fd, but got %d\n",
205 for (i = 0; i < nfd; i++)
218 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
219 _("Received invalid fd"));
227 g_unix_connection_init (GUnixConnection *connection)
232 g_unix_connection_class_init (GUnixConnectionClass *class)
236 /* TODO: Other stuff we might want to add are:
237 void g_unix_connection_send_fd_async (GUnixConnection *connection,
241 GAsyncReadyCallback callback,
243 gboolean g_unix_connection_send_fd_finish (GUnixConnection *connection,
246 gboolean g_unix_connection_send_fds (GUnixConnection *connection,
250 void g_unix_connection_send_fds_async (GUnixConnection *connection,
254 GAsyncReadyCallback callback,
256 gboolean g_unix_connection_send_fds_finish (GUnixConnection *connection,
259 void g_unix_connection_receive_fd_async (GUnixConnection *connection,
261 GAsyncReadyCallback callback,
263 gint g_unix_connection_receive_fd_finish (GUnixConnection *connection,
267 gboolean g_unix_connection_send_fake_credentials (GUnixConnection *connection,
272 void g_unix_connection_send_fake_credentials_async (GUnixConnection *connection,
277 GAsyncReadyCallback callback,
279 gboolean g_unix_connection_send_fake_credentials_finish (GUnixConnection *connection,
282 gboolean g_unix_connection_create_pair (GUnixConnection **one,
283 GUnixConnection **two,
289 * g_unix_connection_send_credentials:
290 * @connection: A #GUnixConnection.
291 * @cancellable: (nullable): A #GCancellable or %NULL.
292 * @error: Return location for error or %NULL.
294 * Passes the credentials of the current user the receiving side
295 * of the connection. The receiving end has to call
296 * g_unix_connection_receive_credentials() (or similar) to accept the
299 * As well as sending the credentials this also writes a single NUL
300 * byte to the stream, as this is required for credentials passing to
301 * work on some implementations.
303 * This method can be expected to be available on the following platforms:
305 * - Linux since GLib 2.26
306 * - FreeBSD since GLib 2.26
307 * - GNU/kFreeBSD since GLib 2.36
308 * - Solaris, Illumos and OpenSolaris since GLib 2.40
309 * - GNU/Hurd since GLib 2.40
311 * Other ways to exchange credentials with a foreign peer includes the
312 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
314 * Returns: %TRUE on success, %FALSE if @error is set.
319 g_unix_connection_send_credentials (GUnixConnection *connection,
320 GCancellable *cancellable,
323 GCredentials *credentials;
324 GSocketControlMessage *scm;
327 GOutputVector vector;
328 guchar nul_byte[1] = {'\0'};
331 g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), FALSE);
332 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
336 credentials = g_credentials_new ();
338 vector.buffer = &nul_byte;
341 if (g_unix_credentials_message_is_supported ())
343 scm = g_unix_credentials_message_new_with_credentials (credentials);
352 g_object_get (connection, "socket", &socket, NULL);
353 if (g_socket_send_message (socket,
363 g_prefix_error (error, _("Error sending credentials: "));
370 g_object_unref (socket);
372 g_object_unref (scm);
373 g_object_unref (credentials);
378 send_credentials_async_thread (GTask *task,
379 gpointer source_object,
381 GCancellable *cancellable)
383 GError *error = NULL;
385 if (g_unix_connection_send_credentials (G_UNIX_CONNECTION (source_object),
388 g_task_return_boolean (task, TRUE);
390 g_task_return_error (task, error);
391 g_object_unref (task);
395 * g_unix_connection_send_credentials_async:
396 * @connection: A #GUnixConnection.
397 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
398 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
399 * @user_data: (closure): the data to pass to callback function
401 * Asynchronously send credentials.
403 * For more details, see g_unix_connection_send_credentials() which is
404 * the synchronous version of this call.
406 * When the operation is finished, @callback will be called. You can then call
407 * g_unix_connection_send_credentials_finish() to get the result of the operation.
412 g_unix_connection_send_credentials_async (GUnixConnection *connection,
413 GCancellable *cancellable,
414 GAsyncReadyCallback callback,
419 task = g_task_new (connection, cancellable, callback, user_data);
420 g_task_set_source_tag (task, g_unix_connection_send_credentials_async);
421 g_task_run_in_thread (task, send_credentials_async_thread);
425 * g_unix_connection_send_credentials_finish:
426 * @connection: A #GUnixConnection.
427 * @result: a #GAsyncResult.
428 * @error: a #GError, or %NULL
430 * Finishes an asynchronous send credentials operation started with
431 * g_unix_connection_send_credentials_async().
433 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
438 g_unix_connection_send_credentials_finish (GUnixConnection *connection,
439 GAsyncResult *result,
442 g_return_val_if_fail (g_task_is_valid (result, connection), FALSE);
444 return g_task_propagate_boolean (G_TASK (result), error);
448 * g_unix_connection_receive_credentials:
449 * @connection: A #GUnixConnection.
450 * @cancellable: (nullable): A #GCancellable or %NULL.
451 * @error: Return location for error or %NULL.
453 * Receives credentials from the sending end of the connection. The
454 * sending end has to call g_unix_connection_send_credentials() (or
455 * similar) for this to work.
457 * As well as reading the credentials this also reads (and discards) a
458 * single byte from the stream, as this is required for credentials
459 * passing to work on some implementations.
461 * This method can be expected to be available on the following platforms:
463 * - Linux since GLib 2.26
464 * - FreeBSD since GLib 2.26
465 * - GNU/kFreeBSD since GLib 2.36
466 * - Solaris, Illumos and OpenSolaris since GLib 2.40
467 * - GNU/Hurd since GLib 2.40
469 * Other ways to exchange credentials with a foreign peer includes the
470 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
472 * Returns: (transfer full): Received credentials on success (free with
473 * g_object_unref()), %NULL if @error is set.
478 g_unix_connection_receive_credentials (GUnixConnection *connection,
479 GCancellable *cancellable,
483 GSocketControlMessage **scms;
487 gssize num_bytes_read;
489 gboolean turn_off_so_passcreds;
492 g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), NULL);
493 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
498 g_object_get (connection, "socket", &socket, NULL);
500 /* On Linux, we need to turn on SO_PASSCRED if it isn't enabled
501 * already. We also need to turn it off when we're done. See
502 * #617483 for more discussion.
508 turn_off_so_passcreds = FALSE;
510 if (!g_socket_get_option (socket,
519 g_io_error_from_errno (errsv),
520 _("Error checking if SO_PASSCRED is enabled for socket: %s"),
526 if (!g_socket_set_option (socket,
535 g_io_error_from_errno (errsv),
536 _("Error enabling SO_PASSCRED: %s"),
540 turn_off_so_passcreds = TRUE;
545 g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE);
546 num_bytes_read = g_socket_receive_message (socket,
547 NULL, /* GSocketAddress **address */
555 if (num_bytes_read != 1)
557 /* Handle situation where g_socket_receive_message() returns
558 * 0 bytes and not setting @error
560 if (num_bytes_read == 0 && error != NULL && *error == NULL)
562 g_set_error_literal (error,
565 _("Expecting to read a single byte for receiving credentials but read zero bytes"));
570 if (g_unix_credentials_message_is_supported () &&
571 /* Fall back on get_credentials if the other side didn't send the credentials */
579 ngettext("Expecting 1 control message, got %d",
580 "Expecting 1 control message, got %d",
586 if (!G_IS_UNIX_CREDENTIALS_MESSAGE (scms[0]))
588 g_set_error_literal (error,
591 _("Unexpected type of ancillary data"));
595 ret = g_unix_credentials_message_get_credentials (G_UNIX_CREDENTIALS_MESSAGE (scms[0]));
605 _("Not expecting control message, but got %d"),
611 ret = g_socket_get_credentials (socket, error);
618 if (turn_off_so_passcreds)
620 if (!g_socket_set_option (socket,
629 g_io_error_from_errno (errsv),
630 _("Error while disabling SO_PASSCRED: %s"),
639 for (n = 0; n < nscm; n++)
640 g_object_unref (scms[n]);
643 g_object_unref (socket);
648 receive_credentials_async_thread (GTask *task,
649 gpointer source_object,
651 GCancellable *cancellable)
654 GError *error = NULL;
656 creds = g_unix_connection_receive_credentials (G_UNIX_CONNECTION (source_object),
660 g_task_return_pointer (task, creds, g_object_unref);
662 g_task_return_error (task, error);
663 g_object_unref (task);
667 * g_unix_connection_receive_credentials_async:
668 * @connection: A #GUnixConnection.
669 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
670 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
671 * @user_data: (closure): the data to pass to callback function
673 * Asynchronously receive credentials.
675 * For more details, see g_unix_connection_receive_credentials() which is
676 * the synchronous version of this call.
678 * When the operation is finished, @callback will be called. You can then call
679 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
684 g_unix_connection_receive_credentials_async (GUnixConnection *connection,
685 GCancellable *cancellable,
686 GAsyncReadyCallback callback,
691 task = g_task_new (connection, cancellable, callback, user_data);
692 g_task_set_source_tag (task, g_unix_connection_receive_credentials_async);
693 g_task_run_in_thread (task, receive_credentials_async_thread);
697 * g_unix_connection_receive_credentials_finish:
698 * @connection: A #GUnixConnection.
699 * @result: a #GAsyncResult.
700 * @error: a #GError, or %NULL
702 * Finishes an asynchronous receive credentials operation started with
703 * g_unix_connection_receive_credentials_async().
705 * Returns: (transfer full): a #GCredentials, or %NULL on error.
706 * Free the returned object with g_object_unref().
711 g_unix_connection_receive_credentials_finish (GUnixConnection *connection,
712 GAsyncResult *result,
715 g_return_val_if_fail (g_task_is_valid (result, connection), NULL);
717 return g_task_propagate_pointer (G_TASK (result), error);