GUnixSocketAddress

GUnixSocketAddress — UNIX GSocketAddress

Functions

Properties

gboolean abstract Read / Write / Construct Only
GUnixSocketAddressType address-type Read / Write / Construct Only
char * path Read / Write / Construct Only
GByteArray * path-as-array Read / Write / Construct Only

Types and Values

Object Hierarchy

    GEnum
    ╰── GUnixSocketAddressType
    GObject
    ╰── GSocketAddress
        ╰── GUnixSocketAddress

Implemented Interfaces

GUnixSocketAddress implements GSocketConnectable.

Includes

#include <gio/gunixsocketaddress.h>

Description

Support for UNIX-domain (also known as local) sockets.

UNIX domain sockets are generally visible in the filesystem. However, some systems support abstract socket names which are not visible in the filesystem and not affected by the filesystem permissions, visibility, etc. Currently this is only supported under Linux. If you attempt to use abstract sockets on other systems, function calls may return G_IO_ERROR_NOT_SUPPORTED errors. You can use g_unix_socket_address_abstract_names_supported() to see if abstract names are supported.

Since GLib 2.72, GUnixSocketAddress is available on all platforms. It requires underlying system support (such as Windows 10 with AF_UNIX) at run time.

Before GLib 2.72, <gio/gunixsocketaddress.h> belonged to the UNIX-specific GIO interfaces, thus you had to use the gio-unix-2.0.pc pkg-config file when using it. This is no longer necessary since GLib 2.72.

Functions

g_unix_socket_address_new ()

GSocketAddress *
g_unix_socket_address_new (const gchar *path);

Creates a new GUnixSocketAddress for path .

To create abstract socket addresses, on systems that support that, use g_unix_socket_address_new_abstract().

Parameters

path

the socket path

 

Returns

a new GUnixSocketAddress

Since: 2.22


g_unix_socket_address_new_abstract ()

GSocketAddress *
g_unix_socket_address_new_abstract (const gchar *path,
                                    gint path_len);

g_unix_socket_address_new_abstract is deprecated and should not be used in newly-written code.

Use g_unix_socket_address_new_with_type().

Creates a new G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED GUnixSocketAddress for path .

Parameters

path

the abstract name.

[array length=path_len][element-type gchar]

path_len

the length of path , or -1

 

Returns

a new GUnixSocketAddress


g_unix_socket_address_new_with_type ()

GSocketAddress *
g_unix_socket_address_new_with_type (const gchar *path,
                                     gint path_len,
                                     GUnixSocketAddressType type);

Creates a new GUnixSocketAddress of type type with name path .

If type is G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to calling g_unix_socket_address_new().

If type is G_UNIX_SOCKET_ADDRESS_ANONYMOUS, path and path_len will be ignored.

If path_type is G_UNIX_SOCKET_ADDRESS_ABSTRACT, then path_len bytes of path will be copied to the socket's path, and only those bytes will be considered part of the name. (If path_len is -1, then path is assumed to be NUL-terminated.) For example, if path was "test", then calling g_socket_address_get_native_size() on the returned socket would return 7 (2 bytes of overhead, 1 byte for the abstract-socket indicator byte, and 4 bytes for the name "test").

If path_type is G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then path_len bytes of path will be copied to the socket's path, the rest of the path will be padded with 0 bytes, and the entire zero-padded buffer will be considered the name. (As above, if path_len is -1, then path is assumed to be NUL-terminated.) In this case, g_socket_address_get_native_size() will always return the full size of a struct sockaddr_un, although g_unix_socket_address_get_path_len() will still return just the length of path .

G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, when connecting to a server created by another process, you must use the appropriate type corresponding to how that process created its listening socket.

Parameters

path

the name.

[array length=path_len][element-type gchar]

path_len

the length of path , or -1

 

type

a GUnixSocketAddressType

 

Returns

a new GUnixSocketAddress

Since: 2.26


g_unix_socket_address_get_is_abstract ()

gboolean
g_unix_socket_address_get_is_abstract (GUnixSocketAddress *address);

g_unix_socket_address_get_is_abstract is deprecated and should not be used in newly-written code.

Use g_unix_socket_address_get_address_type()

Tests if address is abstract.

Parameters

address

a GInetSocketAddress

 

Returns

TRUE if the address is abstract, FALSE otherwise

Since: 2.22


g_unix_socket_address_get_address_type ()

GUnixSocketAddressType
g_unix_socket_address_get_address_type
                               (GUnixSocketAddress *address);

Gets address 's type.

Parameters

address

a GInetSocketAddress

 

Since: 2.26


g_unix_socket_address_get_path ()

const char *
g_unix_socket_address_get_path (GUnixSocketAddress *address);

Gets address 's path, or for abstract sockets the "name".

Guaranteed to be zero-terminated, but an abstract socket may contain embedded zeros, and thus you should use g_unix_socket_address_get_path_len() to get the true length of this string.

Parameters

address

a GInetSocketAddress

 

Returns

the path for address

Since: 2.22


g_unix_socket_address_get_path_len ()

gsize
g_unix_socket_address_get_path_len (GUnixSocketAddress *address);

Gets the length of address 's path.

For details, see g_unix_socket_address_get_path().

Parameters

address

a GInetSocketAddress

 

Returns

the length of the path

Since: 2.22


g_unix_socket_address_abstract_names_supported ()

gboolean
g_unix_socket_address_abstract_names_supported
                               (void);

Checks if abstract UNIX domain socket names are supported.

Returns

TRUE if supported, FALSE otherwise

Since: 2.22

Types and Values

struct GUnixSocketAddress

struct GUnixSocketAddress;

A UNIX-domain (local) socket address, corresponding to a struct sockaddr_un.


enum GUnixSocketAddressType

The type of name used by a GUnixSocketAddress. G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain socket bound to a filesystem path. G_UNIX_SOCKET_ADDRESS_ANONYMOUS indicates a socket not bound to any name (eg, a client-side socket, or a socket created with socketpair()).

For abstract sockets, there are two incompatible ways of naming them; the man pages suggest using the entire struct sockaddr_un as the name, padding the unused parts of the sun_path field with zeroes; this corresponds to G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs instead just use a portion of sun_path, and pass an appropriate smaller length to bind() or connect(). This is G_UNIX_SOCKET_ADDRESS_ABSTRACT.

Members

G_UNIX_SOCKET_ADDRESS_INVALID

invalid

 

G_UNIX_SOCKET_ADDRESS_ANONYMOUS

anonymous

 

G_UNIX_SOCKET_ADDRESS_PATH

a filesystem path

 

G_UNIX_SOCKET_ADDRESS_ABSTRACT

an abstract name

 

G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED

an abstract name, 0-padded to the full length of a unix socket name

 

Since: 2.26

Property Details

The “abstract” property

  “abstract”                 gboolean

Whether or not this is an abstract address

GUnixSocketAddress:abstract is deprecated and should not be used in newly-written code.

Use “address-type”, which distinguishes between zero-padded and non-zero-padded abstract addresses.

Owner: GUnixSocketAddress

Flags: Read / Write / Construct Only

Default value: FALSE


The “address-type” property

  “address-type”             GUnixSocketAddressType

The type of UNIX socket address.

Owner: GUnixSocketAddress

Flags: Read / Write / Construct Only

Default value: G_UNIX_SOCKET_ADDRESS_PATH


The “path” property

  “path”                     char *

UNIX socket path.

Owner: GUnixSocketAddress

Flags: Read / Write / Construct Only

Default value: NULL


The “path-as-array” property

  “path-as-array”            GByteArray *

UNIX socket path, as byte array.

Owner: GUnixSocketAddress

Flags: Read / Write / Construct Only