GUnixSocketAddress

GUnixSocketAddress — UNIX GSocketAddress

Synopsis

#include <gio/gunixsocketaddress.h>

struct              GUnixSocketAddress;
enum                GUnixSocketAddressType;
GSocketAddress *    g_unix_socket_address_new           (const gchar *path);
GSocketAddress *    g_unix_socket_address_new_abstract  (const gchar *path,
                                                         gint path_len);
GSocketAddress *    g_unix_socket_address_new_with_type (const gchar *path,
                                                         gint path_len,
                                                         GUnixSocketAddressType type);
gboolean            g_unix_socket_address_get_is_abstract
                                                        (GUnixSocketAddress *address);
GUnixSocketAddressType  g_unix_socket_address_get_address_type
                                                        (GUnixSocketAddress *address);
const char *        g_unix_socket_address_get_path      (GUnixSocketAddress *address);
gsize               g_unix_socket_address_get_path_len  (GUnixSocketAddress *address);
gboolean            g_unix_socket_address_abstract_names_supported
                                                        (void);

Object Hierarchy

  GObject
   +----GSocketAddress
         +----GUnixSocketAddress
  GEnum
   +----GUnixSocketAddressType

Implemented Interfaces

GUnixSocketAddress implements GSocketConnectable.

Properties

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

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.

Note that <gio/gunixsocketaddress.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.

Details

struct GUnixSocketAddress

struct GUnixSocketAddress;

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


enum GUnixSocketAddressType

typedef enum {
  G_UNIX_SOCKET_ADDRESS_INVALID,
  G_UNIX_SOCKET_ADDRESS_ANONYMOUS,
  G_UNIX_SOCKET_ADDRESS_PATH,
  G_UNIX_SOCKET_ADDRESS_ABSTRACT,
  G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
} 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.

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


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().

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);

Warning

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.

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 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.

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);

Warning

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.

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.

address :

a GInetSocketAddress

Returns :

a GUnixSocketAddressType

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.

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().

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

Property Details

The "abstract" property

  "abstract"                 gboolean              : Read / Write / Construct Only

Warning

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.

Whether or not this is an abstract address

Default value: FALSE


The "address-type" property

  "address-type"             GUnixSocketAddressType  : Read / Write / Construct Only

The type of UNIX socket address.

Default value: G_UNIX_SOCKET_ADDRESS_PATH


The "path" property

  "path"                     gchar*                : Read / Write / Construct Only

UNIX socket path.

Default value: NULL


The "path-as-array" property

  "path-as-array"            GByteArray*           : Read / Write / Construct Only

UNIX socket path, as byte array.