Struct Socket

pub struct Socket { /* private fields */ }

A GSocket is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows.

GSocket is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to use it directly, but rather through classes like SocketClient, SocketService and SocketConnection. However there may be cases where direct use of GSocket is useful.

GSocket implements the Initable interface, so if it is manually constructed by e.g. glib::Object::new() you must call InitableExt::init() and check the results before using the object. This is done automatically in new() and from_fd(), so these functions can return NULL.

Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that would block return immediately with a G_IO_ERROR_WOULD_BLOCK error. To know when a call would successfully run you can call SocketExt::condition_check(), or SocketExt::condition_wait(). You can also use Gio::Socket::create_source() and attach it to a [type@GLib.MainContext] to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and blocking mode is emulated in GSocket.

When working in non-blocking mode applications should always be able to handle getting a G_IO_ERROR_WOULD_BLOCK error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns G_IO_ERROR_WOULD_BLOCK.

GSockets can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is specified or received in each I/O operation.

All socket file descriptors are set to be close-on-exec.

Note that creating a GSocket causes the signal SIGPIPE to be ignored for the remainder of the program. If you are writing a command-line utility that uses GSocket, you may need to take into account the fact that your program will not automatically be killed if it tries to write to stdout after it has been closed.

Like most other APIs in GLib, GSocket is not inherently thread safe. To use a GSocket concurrently from multiple threads, you must implement your own locking.

Nagle’s algorithm

Since GLib 2.80, GSocket will automatically set the TCP_NODELAY option on all G_SOCKET_TYPE_STREAM sockets. This disables Nagle’s algorithm as it typically does more harm than good on modern networks.

If your application needs Nagle’s algorithm enabled, call SocketExt::set_option() after constructing a GSocket to enable it: ⚠️ The following code is in c ⚠️

socket = g_socket_new (…, G_SOCKET_TYPE_STREAM, …);
if (socket != NULL)
  {
    g_socket_set_option (socket, IPPROTO_TCP, TCP_NODELAY, FALSE, &local_error);
    // handle error if needed
  }

Properties

blocking

Whether I/O on this socket is blocking.

Readable | Writeable

broadcast

Whether the socket should allow sending to broadcast addresses.

Readable | Writeable

family

The socket’s address family.

Readable | Writeable | Construct Only

fd

The socket’s file descriptor.

Readable | Writeable | Construct Only

keepalive

Whether to keep the connection alive by sending periodic pings.

Readable | Writeable

listen-backlog

The number of outstanding connections in the listen queue.

Readable | Writeable

local-address

The local address the socket is bound to.

Readable

multicast-loopback

Whether outgoing multicast packets loop back to the local host.

Readable | Writeable

multicast-ttl

Time-to-live out outgoing multicast packets

Readable | Writeable

protocol

The ID of the protocol to use, or -1 for unknown.

Readable | Writeable | Construct Only

remote-address

The remote address the socket is connected to.

Readable

timeout

The timeout in seconds on socket I/O

Readable | Writeable

ttl

Time-to-live for outgoing unicast packets

Readable | Writeable

type

The socket’s type.

Readable | Writeable | Construct Only

Implements

SocketExt, [trait@glib::ObjectExt], DatagramBasedExt, InitableExt, SocketExtManual, DatagramBasedExtManual

GLib type: GObject with reference counted clone semantics.

Implementations

impl Socket

pub unsafe fn from_fd(fd: impl IntoRawFd) -> Result<Socket, Error>

Available on Unix only.

Creates a new #GSocket from a native file descriptor or winsock SOCKET handle.

This reads all the settings from the file descriptor so that all properties should work. Note that the file descriptor will be set to non-blocking mode, independent on the blocking mode of the #GSocket.

On success, the returned #GSocket takes ownership of @fd. On failure, the caller must close @fd themselves.

Since GLib 2.46, it is no longer a fatal error to call this on a non-socket descriptor. Instead, a GError will be set with code IOErrorEnum::Failed

fd

a native socket file descriptor.

Returns

a #GSocket or None on error. Free the returned object with g_object_unref().

impl Socket

pub const NONE: Option<&'static Socket> = None

pub fn new( family: SocketFamily, type_: SocketType, protocol: SocketProtocol, ) -> Result<Socket, Error>

Creates a new #GSocket with the defined family, type and protocol. If @protocol is 0 (SocketProtocol::Default) the default protocol type for the family and type is used.

The @protocol is a family and type specific int that specifies what kind of protocol to use. #GSocketProtocol lists several common ones. Many families only support one protocol, and use 0 for this, others support several and using 0 means to use the default protocol for the family and type.

The protocol id is passed directly to the operating system, so you can use protocols not listed in #GSocketProtocol if you know the protocol number used for it.

family

the socket family to use, e.g. SocketFamily::Ipv4.

type_

the socket type to use.

protocol

the id of the protocol to use, or 0 for default.

Returns

a #GSocket or None on error. Free the returned object with g_object_unref().

Trait Implementations

impl AsRawFd for Socket

Available on Unix only.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Clone for Socket

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Socket

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for Socket

type ParamSpec = ParamSpecObject

type SetValue = Socket

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Socket>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Socket

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Socket

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for Socket

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Socket

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Socket

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Socket

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Socket

impl IsA<DatagramBased> for Socket

impl IsA<Initable> for Socket