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.