## Unix Unix — Unix socket |

## Synopsis

    #include <gnet.h>

                        GUnixSocket;
    GUnixSocket*        gnet_unix_socket_new                (const gchar *path);
    GUnixSocket*        gnet_unix_socket_new_abstract       (const gchar *path);
    void                gnet_unix_socket_delete             (GUnixSocket *socket);
    void                gnet_unix_socket_ref                (GUnixSocket *socket);
    void                gnet_unix_socket_unref              (GUnixSocket *socket);
    GIOChannel*         gnet_unix_socket_get_io_channel     (GUnixSocket *socket);
    gchar*              gnet_unix_socket_get_path           (const GUnixSocket *socket);
    GUnixSocket*        gnet_unix_socket_server_new         (const gchar *path);
    GUnixSocket*        gnet_unix_socket_server_new_abstract
                                                            (const gchar *path);
    GUnixSocket*        gnet_unix_socket_server_accept      (const GUnixSocket *socket);
    GUnixSocket*        gnet_unix_socket_server_accept_nonblock
                                                            (const GUnixSocket *socket);

## Description

The Unix module provides support for Unix sockets. Unix sockets are used to communicate between processes. Unix sockets are for Unix operating systems only and are not supported in Windows. GNet's Unix sockets are stream-based (like TCP), not datagram-based (like UDP). Unix socket addresses are file names, like "/tmp/my_unix_socket".

To connect to a existing Unix socket, call `gnet_unix_socket_new()`. To create a new Unix socket other processes will connect to, call `gnet_unix_socket_server_new()`.

The functions in this module are similar to those in the TCP module. See the documentation on TCP sockets for more information.

## Details

### GUnixSocket

    typedef struct _GUnixSocket GUnixSocket;

A GUnixSocket structure represents a Unix socket. The implementation is hidden.

### gnet_unix_socket_new ()

    GUnixSocket*        gnet_unix_socket_new                (const gchar *path);

Creates a GUnixSocket and connects to `path`. This function will block to connect. Use this constructor to create a GUnixSocket for a client.

`path` : | path
Returns : | a new GUnixSocket; NULL on failure.

### gnet_unix_socket_new_abstract ()

    GUnixSocket*        gnet_unix_socket_new_abstract       (const gchar *path);

Creates a GUnixSocket and connects to `path` in the abstract unix socket domain. This function will block to connect. Use this constructor to create a GUnixSocket for a client.

If the abstract unix sockets are not available on the platform in use, this function will behave like `gnet_unix_socket_new()`.

`path` : | path
Returns : | a new GUnixSocket, or NULL on failure.

Since 2.0.8

### gnet_unix_socket_delete ()

    void                gnet_unix_socket_delete             (GUnixSocket *socket);

Deletes a GUnixSocket.

`socket` : | a GUnixSocket

### gnet_unix_socket_ref ()

    void                gnet_unix_socket_ref                (GUnixSocket *socket);

Adds a reference to a GUnixSocket.

`socket` : | a GUnixSocket

### gnet_unix_socket_unref ()

    void                gnet_unix_socket_unref              (GUnixSocket *socket);

Removes a reference from a GUnixSocket. A GUnixSocket is deleted when the reference count reaches 0.

`socket` : | a GUnixSocket

### gnet_unix_socket_get_io_channel ()

    GIOChannel*         gnet_unix_socket_get_io_channel     (GUnixSocket *socket);

Gets the GIOChannel of a GUnixSocket.

For a client socket, the GIOChannel represents the data stream. Use it like you would any other GIOChannel.

For a server socket, however, the GIOChannel represents the listening socket. When it's readable, there's a connection waiting to be accepted.

Every GUnixSocket has one and only one GIOChannel. If you ref the channel, then you must unref it eventually. Do not close the channel. The channel is closed by GNet when the socket is deleted.

`socket` : | a GUnixSocket
Returns : | a GIOChannel.

### gnet_unix_socket_get_path ()

    gchar*              gnet_unix_socket_get_path           (const GUnixSocket *socket);

Gets the path of a GUnixSocket.

`socket` : | a GUnixSocket
Returns : | the path.

### gnet_unix_socket_server_new ()

    GUnixSocket*        gnet_unix_socket_server_new         (const gchar *path);

Creates a GUnixSocket bound to `path`. Use this constructor to create a GUnixSocket for a server.

`path` : | path
Returns : | a new GUnixSocket; NULL on error.

### gnet_unix_socket_server_new_abstract ()

    GUnixSocket*        gnet_unix_socket_server_new_abstract
                                                            (const gchar *path);

Creates a GUnixSocket bound to `path` in the abstract unix socket domain. Use this constructor to create a GUnixSocket for a server.

If the abstract unix sockets are not available on the platform in use, this function will behave the same as `gnet_unix_socket_server_new()`.

`path` : | path
Returns : | a new GUnixSocket, or NULL on error.

Since 2.0.8

### gnet_unix_socket_server_accept ()

    GUnixSocket*        gnet_unix_socket_server_accept      (const GUnixSocket *socket);

Accepts a connection from a GUnixSocket. The socket must have been created using `gnet_unix_socket_server_new()`. This function will block. Even if the socket's GIOChannel is readable, the function may still block.

`socket` : | a GUnixSocket
Returns : | a new GUnixSocket representing a new connection; NULL on error.

### gnet_unix_socket_server_accept_nonblock ()

    GUnixSocket*        gnet_unix_socket_server_accept_nonblock
                                                            (const GUnixSocket *socket);

Accepts a connection from a GUnixSocket without blocking. The socket must have been created using `gnet_unix_socket_server_new()`.

Note that if the socket's GIOChannel is readable, then there is PROBABLY a new connection. It is possible for the connection to close by the time this function is called, so it may return NULL.

`socket` : | a GUnixSocket
Returns : | a new GUnixSocket representing a new connection; NULL otherwise.