GUnixConnection

GUnixConnection — A UNIX domain GSocketConnection

Types and Values

Object Hierarchy

    GObject
    ╰── GIOStream
        ╰── GSocketConnection
            ╰── GUnixConnection

Includes

#include <gio/gunixconnection.h>

Description

This is the subclass of GSocketConnection that is created for UNIX domain sockets.

It contains functions to do some of the UNIX socket specific functionality like passing file descriptors.

Note that <gio/gunixconnection.h> belongs to the UNIX-specific GIO interfaces, thus you have to use the gio-unix-2.0.pc pkg-config file when using it.

Functions

g_unix_connection_receive_fd ()

gint
g_unix_connection_receive_fd (GUnixConnection *connection,
                              GCancellable *cancellable,
                              GError **error);

Receives a file descriptor from the sending end of the connection. The sending end has to call g_unix_connection_send_fd() for this to work.

As well as reading the fd this also reads a single byte from the stream, as this is required for fd passing to work on some implementations.

Parameters

connection

a GUnixConnection

 

cancellable

optional GCancellable object, NULL to ignore.

[nullable]

error

GError for error reporting, or NULL to ignore.

[nullable]

Returns

a file descriptor on success, -1 on error.

Since: 2.22


g_unix_connection_send_fd ()

gboolean
g_unix_connection_send_fd (GUnixConnection *connection,
                           gint fd,
                           GCancellable *cancellable,
                           GError **error);

Passes a file descriptor to the receiving side of the connection. The receiving end has to call g_unix_connection_receive_fd() to accept the file descriptor.

As well as sending the fd this also writes a single byte to the stream, as this is required for fd passing to work on some implementations.

Parameters

connection

a GUnixConnection

 

fd

a file descriptor

 

cancellable

optional GCancellable object, NULL to ignore.

[nullable]

error

GError for error reporting, or NULL to ignore.

[nullable]

Returns

a TRUE on success, NULL on error.

Since: 2.22


g_unix_connection_receive_credentials ()

GCredentials *
g_unix_connection_receive_credentials (GUnixConnection *connection,
                                       GCancellable *cancellable,
                                       GError **error);

Receives credentials from the sending end of the connection. The sending end has to call g_unix_connection_send_credentials() (or similar) for this to work.

As well as reading the credentials this also reads (and discards) a single byte from the stream, as this is required for credentials passing to work on some implementations.

This method can be expected to be available on the following platforms:

  • Linux since GLib 2.26

  • FreeBSD since GLib 2.26

  • GNU/kFreeBSD since GLib 2.36

  • Solaris, Illumos and OpenSolaris since GLib 2.40

  • GNU/Hurd since GLib 2.40

Other ways to exchange credentials with a foreign peer includes the GUnixCredentialsMessage type and g_socket_get_credentials() function.

Parameters

connection

A GUnixConnection.

 

cancellable

A GCancellable or NULL.

[nullable]

error

Return location for error or NULL.

 

Returns

Received credentials on success (free with g_object_unref()), NULL if error is set.

[transfer full]

Since: 2.26


g_unix_connection_receive_credentials_async ()

void
g_unix_connection_receive_credentials_async
                               (GUnixConnection *connection,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously receive credentials.

For more details, see g_unix_connection_receive_credentials() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_unix_connection_receive_credentials_finish() to get the result of the operation.

Parameters

connection

A GUnixConnection.

 

cancellable

optional GCancellable object, NULL to ignore.

[nullable]

callback

a GAsyncReadyCallback to call when the request is satisfied.

[scope async]

user_data

the data to pass to callback function.

[closure]

Since: 2.32


g_unix_connection_receive_credentials_finish ()

GCredentials *
g_unix_connection_receive_credentials_finish
                               (GUnixConnection *connection,
                                GAsyncResult *result,
                                GError **error);

Finishes an asynchronous receive credentials operation started with g_unix_connection_receive_credentials_async().

Parameters

connection

A GUnixConnection.

 

result

a GAsyncResult.

 

error

a GError, or NULL

 

Returns

a GCredentials, or NULL on error. Free the returned object with g_object_unref().

[transfer full]

Since: 2.32


g_unix_connection_send_credentials ()

gboolean
g_unix_connection_send_credentials (GUnixConnection *connection,
                                    GCancellable *cancellable,
                                    GError **error);

Passes the credentials of the current user the receiving side of the connection. The receiving end has to call g_unix_connection_receive_credentials() (or similar) to accept the credentials.

As well as sending the credentials this also writes a single NUL byte to the stream, as this is required for credentials passing to work on some implementations.

This method can be expected to be available on the following platforms:

  • Linux since GLib 2.26

  • FreeBSD since GLib 2.26

  • GNU/kFreeBSD since GLib 2.36

  • Solaris, Illumos and OpenSolaris since GLib 2.40

  • GNU/Hurd since GLib 2.40

Other ways to exchange credentials with a foreign peer includes the GUnixCredentialsMessage type and g_socket_get_credentials() function.

Parameters

connection

A GUnixConnection.

 

cancellable

A GCancellable or NULL.

[nullable]

error

Return location for error or NULL.

 

Returns

TRUE on success, FALSE if error is set.

Since: 2.26


g_unix_connection_send_credentials_async ()

void
g_unix_connection_send_credentials_async
                               (GUnixConnection *connection,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously send credentials.

For more details, see g_unix_connection_send_credentials() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_unix_connection_send_credentials_finish() to get the result of the operation.

Parameters

connection

A GUnixConnection.

 

cancellable

optional GCancellable object, NULL to ignore.

[nullable]

callback

a GAsyncReadyCallback to call when the request is satisfied.

[scope async]

user_data

the data to pass to callback function.

[closure]

Since: 2.32


g_unix_connection_send_credentials_finish ()

gboolean
g_unix_connection_send_credentials_finish
                               (GUnixConnection *connection,
                                GAsyncResult *result,
                                GError **error);

Finishes an asynchronous send credentials operation started with g_unix_connection_send_credentials_async().

Parameters

connection

A GUnixConnection.

 

result

a GAsyncResult.

 

error

a GError, or NULL

 

Returns

TRUE if the operation was successful, otherwise FALSE.

Since: 2.32

Types and Values

struct GUnixConnection

struct GUnixConnection;

GUnixConnection is an opaque data structure and can only be accessed using the following functions.

See Also

GSocketConnection.