Struct socket2::Socket [] [src]

pub struct Socket { /* fields omitted */ }

Newtype, owned, wrapper around a system socket.

This type simply wraps an instance of a file descriptor (c_int) on Unix and an instance of SOCKET on Windows. This is the main type exported by this crate and is intended to mirror the raw semantics of sockets on platforms as closely as possible. Almost all methods correspond to precisely one libc or OS API call which is essentially just a "Rustic translation" of what's below.

Examples

use std::net::SocketAddr;
use socket2::{Socket, Domain, Type, SockAddr};

// create a TCP listener bound to two addresses
let socket = Socket::new(Domain::ipv4(), Type::stream(), None).unwrap();

socket.bind(&"127.0.0.1:12345".parse::<SocketAddr>().unwrap().into()).unwrap();
socket.bind(&"127.0.0.1:12346".parse::<SocketAddr>().unwrap().into()).unwrap();
socket.listen(128).unwrap();

let listener = socket.into_tcp_listener();
// ...

Methods

impl Socket
[src]

[src]

Creates a new socket ready to be configured.

This function corresponds to socket(2) and simply creates a new socket, no other configuration is done and further functions must be invoked to configure this socket.

[src]

Creates a pair of sockets which are connected to each other.

This function corresponds to socketpair(2).

This function is only available on Unix when the pair feature is enabled.

[src]

Consumes this Socket, converting it to a TcpStream.

[src]

Consumes this Socket, converting it to a TcpListener.

[src]

Consumes this Socket, converting it to a UdpSocket.

[src]

Consumes this Socket, converting it into a UnixStream.

This function is only available on Unix when the unix feature is enabled.

[src]

Consumes this Socket, converting it into a UnixListener.

This function is only available on Unix when the unix feature is enabled.

[src]

Consumes this Socket, converting it into a UnixDatagram.

This function is only available on Unix when the unix feature is enabled.

[src]

Initiate a connection on this socket to the specified address.

This function directly corresponds to the connect(2) function on Windows and Unix.

An error will be returned if listen or connect has already been called on this builder.

[src]

Initiate a connection on this socket to the specified address, only only waiting for a certain period of time for the connection to be established.

Unlike many other methods on Socket, this does not correspond to a single C function. It sets the socket to nonblocking mode, connects via connect(2), and then waits for the connection to complete with poll(2) on Unix and select on Windows. When the connection is complete, the socket is set back to blocking mode. On Unix, this will loop over EINTR errors.

Warnings

The nonblocking state of the socket is overridden by this function - it will be returned in blocking mode on success, and in an indeterminate state on failure.

If the connection request times out, it may still be processing in the background - a second call to connect or connect_timeout may fail.

[src]

Binds this socket to the specified address.

This function directly corresponds to the bind(2) function on Windows and Unix.

[src]

Mark a socket as ready to accept incoming connection requests using accept()

This function directly corresponds to the listen(2) function on Windows and Unix.

An error will be returned if listen or connect has already been called on this builder.

[src]

Accept a new incoming connection from this listener.

This function will block the calling thread until a new connection is established. When established, the corresponding Socket and the remote peer's address will be returned.

[src]

Returns the socket address of the local half of this TCP connection.

[src]

Returns the socket address of the remote peer of this TCP connection.

[src]

Creates a new independently owned handle to the underlying socket.

The returned TcpStream is a reference to the same stream that this object references. Both handles will read and write the same stream of data, and options set on one stream will be propagated to the other stream.

[src]

Get the value of the SO_ERROR option on this socket.

This will retrieve the stored error in the underlying socket, clearing the field in the process. This can be useful for checking errors between calls.

[src]

Moves this TCP stream into or out of nonblocking mode.

On Unix this corresponds to calling fcntl, and on Windows this corresponds to calling ioctlsocket.

[src]

Shuts down the read, write, or both halves of this connection.

This function will cause all pending and future I/O on the specified portions to return immediately with an appropriate value.

[src]

Receives data on the socket from the remote address to which it is connected.

The connect method will connect this socket to a remote address. This method will fail if the socket is not connected.

[src]

Receives data on the socket from the remote adress to which it is connected, without removing that data from the queue. On success, returns the number of bytes peeked.

Successive calls return the same data. This is accomplished by passing MSG_PEEK as a flag to the underlying recv system call.

[src]

Receives data from the socket. On success, returns the number of bytes read and the address from whence the data came.

[src]

Receives data from the socket, without removing it from the queue.

Successive calls return the same data. This is accomplished by passing MSG_PEEK as a flag to the underlying recvfrom system call.

On success, returns the number of bytes peeked and the address from whence the data came.

[src]

Sends data on the socket to a connected peer.

This is typically used on TCP sockets or datagram sockets which have been connected.

On success returns the number of bytes that were sent.

[src]

Sends data on the socket to the given address. On success, returns the number of bytes written.

This is typically used on UDP or datagram-oriented sockets. On success returns the number of bytes that were sent.

[src]

Gets the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

[src]

Sets the value for the IP_TTL option on this socket.

This value sets the time-to-live field that is used in every packet sent from this socket.

[src]

Gets the value of the IPV6_UNICAST_HOPS option for this socket.

Specifies the hop limit for ipv6 unicast packets

[src]

Sets the value for the IPV6_UNICAST_HOPS option on this socket.

Specifies the hop limit for ipv6 unicast packets

[src]

Gets the value of the IPV6_V6ONLY option for this socket.

For more information about this option, see set_only_v6.

[src]

Sets the value for the IPV6_V6ONLY option on this socket.

If this is set to true then the socket is restricted to sending and receiving IPv6 packets only. In this case two IPv4 and IPv6 applications can bind the same port at the same time.

If this is set to false then the socket can be used to send and receive packets from an IPv4-mapped IPv6 address.

[src]

Returns the read timeout of this socket.

If the timeout is None, then read calls will block indefinitely.

[src]

Sets the read timeout to the timeout specified.

If the value specified is None, then read calls will block indefinitely. It is an error to pass the zero Duration to this method.

[src]

Returns the write timeout of this socket.

If the timeout is None, then write calls will block indefinitely.

[src]

Sets the write timeout to the timeout specified.

If the value specified is None, then write calls will block indefinitely. It is an error to pass the zero Duration to this method.

[src]

Gets the value of the TCP_NODELAY option on this socket.

For more information about this option, see set_nodelay.

[src]

Sets the value of the TCP_NODELAY option on this socket.

If set, this option disables the Nagle algorithm. This means that segments are always sent as soon as possible, even if there is only a small amount of data. When not set, data is buffered until there is a sufficient amount to send out, thereby avoiding the frequent sending of small packets.

[src]

Sets the value of the SO_BROADCAST option for this socket.

When enabled, this socket is allowed to send packets to a broadcast address.

[src]

Gets the value of the SO_BROADCAST option for this socket.

For more information about this option, see set_broadcast.

[src]

Gets the value of the IP_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v4.

[src]

Sets the value of the IP_MULTICAST_LOOP option for this socket.

If enabled, multicast packets will be looped back to the local socket. Note that this may not have any affect on IPv6 sockets.

[src]

Gets the value of the IP_MULTICAST_TTL option for this socket.

For more information about this option, see set_multicast_ttl_v4.

[src]

Sets the value of the IP_MULTICAST_TTL option for this socket.

Indicates the time-to-live value of outgoing multicast packets for this socket. The default value is 1 which means that multicast packets don't leave the local network unless explicitly requested.

Note that this may not have any affect on IPv6 sockets.

[src]

Gets the value of the IPV6_MULTICAST_HOPS option for this socket

For more information about this option, see set_multicast_hops_v6.

[src]

Sets the value of the IPV6_MULTICAST_HOPS option for this socket

Indicates the number of "routers" multicast packets will transit for this socket. The default value is 1 which means that multicast packets don't leave the local network unless explicitly requested.

[src]

Gets the value of the IP_MULTICAST_IF option for this socket.

For more information about this option, see set_multicast_if_v4.

Returns the interface to use for routing multicast packets.

[src]

Sets the value of the IP_MULTICAST_IF option for this socket.

Specifies the interface to use for routing multicast packets.

[src]

Gets the value of the IPV6_MULTICAST_IF option for this socket.

For more information about this option, see set_multicast_if_v6.

Returns the interface to use for routing multicast packets.

[src]

Sets the value of the IPV6_MULTICAST_IF option for this socket.

Specifies the interface to use for routing multicast packets. Unlike ipv4, this is generally required in ipv6 contexts where network routing prefixes may overlap.

[src]

Gets the value of the IPV6_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v6.

[src]

Sets the value of the IPV6_MULTICAST_LOOP option for this socket.

Controls whether this socket sees the multicast packets it sends itself. Note that this may not have any affect on IPv4 sockets.

[src]

Executes an operation of the IP_ADD_MEMBERSHIP type.

This function specifies a new multicast group for this socket to join. The address must be a valid multicast address, and interface is the address of the local interface with which the system should join the multicast group. If it's equal to INADDR_ANY then an appropriate interface is chosen by the system.

[src]

Executes an operation of the IPV6_ADD_MEMBERSHIP type.

This function specifies a new multicast group for this socket to join. The address must be a valid multicast address, and interface is the index of the interface to join/leave (or 0 to indicate any interface).

[src]

Executes an operation of the IP_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v4.

[src]

Executes an operation of the IPV6_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v6.

[src]

Reads the linger duration for this socket by getting the SO_LINGER option

[src]

Sets the linger duration of this socket by setting the SO_LINGER option

[src]

Check the SO_REUSEADDR option on this socket.

[src]

Set value for the SO_REUSEADDR option on this socket.

This indicates that futher calls to bind may allow reuse of local addresses. For IPv4 sockets this means that a socket may bind even when there's a socket already listening on this port.

[src]

Gets the value of the SO_RCVBUF option on this socket.

For more information about this option, see set_recv_buffer_size.

[src]

Sets the value of the SO_RCVBUF option on this socket.

Changes the size of the operating system's receive buffer associated with the socket.

[src]

Gets the value of the SO_SNDBUF option on this socket.

For more information about this option, see set_send_buffer.

[src]

Sets the value of the SO_SNDBUF option on this socket.

Changes the size of the operating system's send buffer associated with the socket.

[src]

Returns whether keepalive messages are enabled on this socket, and if so the duration of time between them.

For more information about this option, see set_keepalive.

[src]

Sets whether keepalive messages are enabled to be sent on this socket.

On Unix, this option will set the SO_KEEPALIVE as well as the TCP_KEEPALIVE or TCP_KEEPIDLE option (depending on your platform). On Windows, this will set the SIO_KEEPALIVE_VALS option.

If None is specified then keepalive messages are disabled, otherwise the duration specified will be the time to remain idle before sending a TCP keepalive probe.

Some platforms specify this value in seconds, so sub-second specifications may be omitted.

[src]

Check the value of the SO_REUSEPORT option on this socket.

This function is only available on Unix when the reuseport feature is enabled.

[src]

Set value for the SO_REUSEPORT option on this socket.

This indicates that futher calls to bind may allow reuse of local addresses. For IPv4 sockets this means that a socket may bind even when there's a socket already listening on this port.

This function is only available on Unix when the reuseport feature is enabled.

Trait Implementations

impl Read for Socket
[src]

[src]

Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more

[src]

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory. Read more

1.0.0
[src]

Read all bytes until EOF in this source, placing them into buf. Read more

1.0.0
[src]

Read all bytes until EOF in this source, appending them to buf. Read more

1.6.0
[src]

Read the exact number of bytes required to fill buf. Read more

1.0.0
[src]

Creates a "by reference" adaptor for this instance of Read. Read more

1.0.0
[src]

Transforms this Read instance to an [Iterator] over its bytes. Read more

[src]

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s. Read more

1.0.0
[src]

Creates an adaptor which will chain this stream with another. Read more

1.0.0
[src]

Creates an adaptor which will read at most limit bytes from it. Read more

impl<'a> Read for &'a Socket
[src]

[src]

Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more

[src]

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory. Read more

1.0.0
[src]

Read all bytes until EOF in this source, placing them into buf. Read more

1.0.0
[src]

Read all bytes until EOF in this source, appending them to buf. Read more

1.6.0
[src]

Read the exact number of bytes required to fill buf. Read more

1.0.0
[src]

Creates a "by reference" adaptor for this instance of Read. Read more

1.0.0
[src]

Transforms this Read instance to an [Iterator] over its bytes. Read more

[src]

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s. Read more

1.0.0
[src]

Creates an adaptor which will chain this stream with another. Read more

1.0.0
[src]

Creates an adaptor which will read at most limit bytes from it. Read more

impl Write for Socket
[src]

[src]

Write a buffer into this object, returning how many bytes were written. Read more

[src]

Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more

1.0.0
[src]

Attempts to write an entire buffer into this write. Read more

1.0.0
[src]

Writes a formatted string into this writer, returning any error encountered. Read more

1.0.0
[src]

Creates a "by reference" adaptor for this instance of Write. Read more

impl<'a> Write for &'a Socket
[src]

[src]

Write a buffer into this object, returning how many bytes were written. Read more

[src]

Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more

1.0.0
[src]

Attempts to write an entire buffer into this write. Read more

1.0.0
[src]

Writes a formatted string into this writer, returning any error encountered. Read more

1.0.0
[src]

Creates a "by reference" adaptor for this instance of Write. Read more

impl Debug for Socket
[src]

[src]

Formats the value using the given formatter. Read more

impl From<TcpStream> for Socket
[src]

Important traits for Socket
[src]

Performs the conversion.

impl From<TcpListener> for Socket
[src]

Important traits for Socket
[src]

Performs the conversion.

impl From<UdpSocket> for Socket
[src]

Important traits for Socket
[src]

Performs the conversion.

impl From<UnixStream> for Socket
[src]

Important traits for Socket
[src]

Performs the conversion.

impl From<UnixListener> for Socket
[src]

Important traits for Socket
[src]

Performs the conversion.

impl From<UnixDatagram> for Socket
[src]

Important traits for Socket
[src]

Performs the conversion.

impl From<Socket> for TcpStream
[src]

[src]

Performs the conversion.

impl From<Socket> for TcpListener
[src]

[src]

Performs the conversion.

impl From<Socket> for UdpSocket
[src]

[src]

Performs the conversion.

impl From<Socket> for UnixStream
[src]

[src]

Performs the conversion.

impl From<Socket> for UnixListener
[src]

[src]

Performs the conversion.

impl From<Socket> for UnixDatagram
[src]

[src]

Performs the conversion.

impl AsRawFd for Socket
[src]

[src]

Extracts the raw file descriptor. Read more

impl IntoRawFd for Socket
[src]

[src]

Consumes this object, returning the raw underlying file descriptor. Read more

impl FromRawFd for Socket
[src]

Important traits for Socket
[src]

Constructs a new instance of Self from the given raw file descriptor. Read more

Auto Trait Implementations

impl Send for Socket

impl Sync for Socket