std::net::UdpSocket - Rust
Description: API documentation for the Rust `UdpSocket` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, UdpSocket

# Struct std::net::UdpSocket 1.0.0 [−] [src]

    pub struct UdpSocket(_);

A User Datagram Protocol socket.

This is an implementation of a bound UDP socket. This supports both IPv4 and IPv6 addresses, and there is no corresponding notion of a server because UDP is a datagram protocol.

# Examples

    use std::net::UdpSocket;

    {
        let mut socket = UdpSocket::bind("127.0.0.1:34254")?;

        // read from the socket
        let mut buf = [0; 10];
        let (amt, src) = socket.recv_from(&mut buf)?;

        // send a reply to the socket we received data from
        let buf = &mut buf[..amt];
        buf.reverse();
        socket.send_to(buf, &src)?;
    } // the socket is closed hereRun

## Methods

### `impl UdpSocket`
[src]

#### `fn bind<A: ToSocketAddrs>(addr: A) -> Result<UdpSocket>`

Creates a UDP socket from the given address.

The address type can be any implementor of `ToSocketAddrs` trait. See its documentation for concrete examples.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");Run

#### `fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>`

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

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    let mut buf = [0; 10];
    let (number_of_bytes, src_addr) = socket.recv_from(&mut buf)
                                            .expect("Didn't receive data");Run

#### `fn send_to<A: ToSocketAddrs>(&self, buf: &[u8], addr: A) -> Result<usize>`

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

Address type can be any implementor of `ToSocketAddrs` trait. See its documentation for concrete examples.

This will return an error when the IP version of the local socket does not match that returned from `ToSocketAddrs`.

See https://github.com/rust-lang/rust/issues/34202 for more details.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.send_to(&[0; 10], "127.0.0.1:4242").expect("couldn't send data");Run

#### `fn local_addr(&self) -> Result<SocketAddr>`

Returns the socket address that this socket was created from.

# Examples

    use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, UdpSocket};

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    assert_eq!(socket.local_addr().unwrap(),
               SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 34254)));Run

#### `fn try_clone(&self) -> Result<UdpSocket>`

Creates a new independently owned handle to the underlying socket.

The returned `UdpSocket` is a reference to the same socket that this object references. Both handles will read and write the same port, and options set on one socket will be propagated to the other.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    let socket_clone = socket.try_clone().expect("couldn't clone the socket");Run

#### `fn set_read_timeout(&self, dur: Option<Duration>) -> Result<()>`
1.4.0

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.

# Note

Platforms may return a different error code whenever a read times out as a result of setting this option. For example Unix typically returns an error of the kind `WouldBlock`, but Windows may return `TimedOut`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_read_timeout(None).expect("set_read_timeout call failed");Run

#### `fn set_write_timeout(&self, dur: Option<Duration>) -> Result<()>`
1.4.0

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.

# Note

Platforms may return a different error code whenever a write times out as a result of setting this option. For example Unix typically returns an error of the kind `WouldBlock`, but Windows may return `TimedOut`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_write_timeout(None).expect("set_write_timeout call failed");Run

#### `fn read_timeout(&self) -> Result<Option<Duration>>`
1.4.0

Returns the read timeout of this socket.

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

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_read_timeout(None).expect("set_read_timeout call failed");
    assert_eq!(socket.read_timeout().unwrap(), None);Run

#### `fn write_timeout(&self) -> Result<Option<Duration>>`
1.4.0

Returns the write timeout of this socket.

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

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_write_timeout(None).expect("set_write_timeout call failed");
    assert_eq!(socket.write_timeout().unwrap(), None);Run

#### `fn set_broadcast(&self, broadcast: bool) -> Result<()>`
1.9.0

Sets the value of the `SO_BROADCAST` option for this socket.

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

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_broadcast(false).expect("set_broadcast call failed");Run

#### `fn broadcast(&self) -> Result<bool>`
1.9.0

Gets the value of the `SO_BROADCAST` option for this socket.

For more information about this option, see `set_broadcast`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_broadcast(false).expect("set_broadcast call failed");
    assert_eq!(socket.broadcast().unwrap(), false);Run

#### `fn set_multicast_loop_v4(&self, multicast_loop_v4: bool) -> Result<()>`
1.9.0

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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_multicast_loop_v4(false).expect("set_multicast_loop_v4 call failed");Run

#### `fn multicast_loop_v4(&self) -> Result<bool>`
1.9.0

Gets the value of the `IP_MULTICAST_LOOP` option for this socket.

For more information about this option, see `set_multicast_loop_v4`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_multicast_loop_v4(false).expect("set_multicast_loop_v4 call failed");
    assert_eq!(socket.multicast_loop_v4().unwrap(), false);Run

#### `fn set_multicast_ttl_v4(&self, multicast_ttl_v4: u32) -> Result<()>`
1.9.0

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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_multicast_ttl_v4(42).expect("set_multicast_ttl_v4 call failed");Run

#### `fn multicast_ttl_v4(&self) -> Result<u32>`
1.9.0

Gets the value of the `IP_MULTICAST_TTL` option for this socket.

For more information about this option, see `set_multicast_ttl_v4`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_multicast_ttl_v4(42).expect("set_multicast_ttl_v4 call failed");
    assert_eq!(socket.multicast_ttl_v4().unwrap(), 42);Run

#### `fn set_multicast_loop_v6(&self, multicast_loop_v6: bool) -> Result<()>`
1.9.0

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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_multicast_loop_v6(false).expect("set_multicast_loop_v6 call failed");Run

#### `fn multicast_loop_v6(&self) -> Result<bool>`
1.9.0

Gets the value of the `IPV6_MULTICAST_LOOP` option for this socket.

For more information about this option, see `set_multicast_loop_v6`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_multicast_loop_v6(false).expect("set_multicast_loop_v6 call failed");
    assert_eq!(socket.multicast_loop_v6().unwrap(), false);Run

#### `fn set_ttl(&self, ttl: u32) -> Result<()>`
1.9.0

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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_ttl(42).expect("set_ttl call failed");Run

#### `fn ttl(&self) -> Result<u32>`
1.9.0

Gets the value of the `IP_TTL` option for this socket.

For more information about this option, see `set_ttl`.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_ttl(42).expect("set_ttl call failed");
    assert_eq!(socket.ttl().unwrap(), 42);Run

#### `fn join_multicast_v4(&self,
multiaddr: &Ipv4Addr,
interface: &Ipv4Addr)
-> Result<()>`
1.9.0

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.

#### `fn join_multicast_v6(&self, multiaddr: &Ipv6Addr, interface: u32) -> Result<()>`
1.9.0

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

#### `fn leave_multicast_v4(&self,
multiaddr: &Ipv4Addr,
interface: &Ipv4Addr)
-> Result<()>`
1.9.0

Executes an operation of the `IP_DROP_MEMBERSHIP` type.

For more information about this option, see `join_multicast_v4`.

#### `fn leave_multicast_v6(&self, multiaddr: &Ipv6Addr, interface: u32) -> Result<()>`
1.9.0

Executes an operation of the `IPV6_DROP_MEMBERSHIP` type.

For more information about this option, see `join_multicast_v6`.

#### `fn take_error(&self) -> Result<Option<Error>>`
1.9.0

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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    match socket.take_error() {
        Ok(Some(error)) => println!("UdpSocket error: {:?}", error),
        Ok(None) => println!("No error"),
        Err(error) => println!("UdpSocket.take_error failed: {:?}", error),
    }Run

#### `fn connect<A: ToSocketAddrs>(&self, addr: A) -> Result<()>`
1.9.0

Connects this UDP socket to a remote address, allowing the `send` and `recv` syscalls to be used to send data and also applies filters to only receive data from the specified address.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.connect("127.0.0.1:8080").expect("connect function failed");Run

#### `fn send(&self, buf: &[u8]) -> Result<usize>`
1.9.0

Sends data on the socket to 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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.connect("127.0.0.1:8080").expect("connect function failed");
    socket.send(&[0, 1, 2]).expect("couldn't send message");Run

#### `fn recv(&self, buf: &mut [u8]) -> Result<usize>`
1.9.0

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.

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.connect("127.0.0.1:8080").expect("connect function failed");
    let mut buf = [0; 10];
    match socket.recv(&mut buf) {
        Ok(received) => println!("received {} bytes", received),
        Err(e) => println!("recv function failed: {:?}", e),
    }Run

#### `fn set_nonblocking(&self, nonblocking: bool) -> Result<()>`
1.9.0

Moves this UDP socket into or out of nonblocking mode.

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

# Examples

    use std::net::UdpSocket;

    let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
    socket.set_nonblocking(true).expect("set_nonblocking call failed");Run

## Trait Implementations

### `impl Debug for UdpSocket`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`

Formats the value using the given formatter.

### `impl AsRawFd for UdpSocket`
[src]

#### `fn as_raw_fd(&self) -> RawFd`

Extracts the raw file descriptor. Read more

### `impl FromRawFd for UdpSocket`
1.1.0
[src]

#### `unsafe fn from_raw_fd(fd: RawFd) -> UdpSocket`

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

### `impl IntoRawFd for UdpSocket`
1.4.0
[src]

#### `fn into_raw_fd(self) -> RawFd`

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)