Struct libsocket::Socket

pub struct Socket { /* fields omitted */ }

Methods

impl Socket

fn new(
    domain: Domain,
    sock_type: c_int,
    protocol: c_int
) -> Result<Socket, Error>

Creates a new socket with the passed options.

fn from_fd(fd: c_int) -> Socket

Creates a socket from an already established socket fd.

fn bind(
    &self,
    address: *const sockaddr,
    address_len: socklen_t
) -> Result<(), Error>

Assigns the address specified by address to the socket

fn connect(
    &self,
    address: *const sockaddr,
    address_len: socklen_t
) -> Result<(), Error>

Connects the socket to address.

fn listen(&self, backlog: usize) -> Result<(), Error>

Marks the socket as a socket that will be used to accept incoming connections.

fn accept(
    &self,
    address: *mut sockaddr,
    address_len: *mut socklen_t
) -> Result<Socket, Error>

Extracts the first connection from the backlog queue of pending connections and creates and returns a new Socket.

fn recv(&self, buf: &mut [u8], flags: c_int) -> Result<usize, Error>

If no messages are available at the socket, the call waits for a message to arrive, unless the socket is nonblocking, in which case ErrorKind::WouldBlock is returned. The call normally returns any data available, up to the requested amount, rather than waiting for receipt of the full amount requested.

fn send(&self, buf: &[u8], flags: c_int) -> Result<usize, Error>

If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a send(). Locally detected errors are indicated by an Error returned. When the message does not fit into the send buffer of the socket, send() normally blocks, unless the socket has been placed in nonblocking I/O mode. In nonblocking mode it would fail with the error ErrorKind::WouldBlock in this case.

fn shutdown(&self, how: Shutdown) -> Result<(), Error>

Disables subsequent send and/or receive operations on a socket, depending on the value of the how argument.

fn close(&self) -> Result<(), Error>

Closes the underlying file descriptor of the socket.

fn set_tcp_nodelay(&mut self, nodelay: bool) -> Result<(), Error>

If set, disable 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, which results in poor utilization of the network. This option is overridden by TCP_CORK; however, setting this option forces an explicit flush of pending output, even if TCP_CORK is currently set.

fn set_nonblocking(&mut self) -> Result<(), Error>

Sets the O_NONBLOCK flag on the underlying fd

fn set_bindtodevice(&mut self, interface: String) -> Result<(), Error>

Bind this socket to a particular device like "eth0", as specified in the passed interface name. If the name is an empty string or the option length is zero, the socket device binding is removed. The passed option is a variable-length null-terminated interface name string with the maximum size of IFNAMSIZ. If a socket is bound to an interface, only packets received from that particular interface are processed by the socket. Note that this only works for some socket types, particularly AF_INET sockets. It is not supported for packet sockets (use normal bind(2) there).

Before Linux 3.8, this socket option could be set, but could not retrieved with getsockopt(2). Since Linux 3.8, it is readable. The optlen argument should contain the buffer size available to receive the device name and is recommended to be IFNAMSZ bytes. The real device name length is reported back in the optlen argument.

fn set_broadcast(&mut self, option: bool) -> Result<(), Error>

When enabled, datagram sockets are allowed to send packets to a broadcast address. This option has no effect on stream-oriented sockets.

fn set_bsdcompat(&mut self, option: bool) -> Result<(), Error>

Enable BSD bug-to-bug compatibility. This is used by the UDP protocol module in Linux 2.0 and 2.2. If enabled ICMP errors received for a UDP socket will not be passed to the user program. In later kernel versions, support for this option has been phased out: Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning (printk()) if a program uses this option. Linux 2.0 also enabled BSD bug-to-bug compatibility options (random header changing, skipping of the broadcast flag) for raw sockets with this option, but that was removed in Linux 2.2.

fn set_debug(&mut self, option: bool) -> Result<(), Error>

Enable socket debugging. Only allowed for processes with the CAP_NET_ADMIN capability or an effective user ID of 0.

fn set_dontroute(&mut self, option: bool) -> Result<(), Error>

Don't send via a gateway, only send to directly connected hosts. The same effect can be achieved by setting the MSG_DONTROUTE flag on a socket send(2) operation. Expects an integer boolean flag.

fn set_keepalive(&mut self, option: bool) -> Result<(), Error>

Enable sending of keep-alive messages on connection-oriented sockets. Expects an integer boolean flag.

fn set_linger(&mut self, option: bool, sec: u32) -> Result<(), Error>

Sets or gets the SO_LINGER option. When enabled, a close(2) or shutdown(2) will not return until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Otherwise, the call returns immediately and the closing is done in the background. When the socket is closed as part of exit(2), it always lingers in the background.

fn set_mark(&mut self, option: bool) -> Result<(), Error>

Set the mark for each packet sent through this socket (similar to the netfilter MARK target but socket-based). Changing the mark can be used for mark-based routing without netfilter or for packet filtering. Setting this option requires the CAP_NET_ADMIN capability.

fn set_oobinline(&mut self, option: bool) -> Result<(), Error>

If this option is enabled, out-of-band data is directly placed into the receive data stream. Otherwise out-of-band data is only passed when the MSG_OOB flag is set during receiving.

fn set_passcred(&mut self, option: bool) -> Result<(), Error>

Enable or disable the receiving of the SCM_CREDENTIALS control message. For more information see unix(7).

fn set_priority(&mut self, priority: u32) -> Result<(), Error>

Set the protocol-defined priority for all packets to be sent on this socket. Linux uses this value to order the networking queues: packets with a higher priority may be processed first depending on the selected device queueing discipline. For ip(7), this also sets the IP type-of-service (TOS) field for outgoing packets. Setting a priority outside the range 0 to 6 requires the CAP_NET_ADMIN capability.

fn set_rcvbuf(&mut self, size: usize) -> Result<(), Error>

Sets or gets the maximum socket receive buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using setsockopt(2), and this doubled value is returned by getsockopt(2). The default value is set by the /proc/sys/net/core/rmem_default file, and the maximum allowed value is set by the /proc/sys/net/core/rmem_max file. The minimum (doubled) value for this option is 256.

fn set_rcvbufforce(&mut self, size: usize) -> Result<(), Error>

Using this socket option, a privileged (CAP_NET_ADMIN) process can perform the same task as SO_RCVBUF, but the rmem_max limit can be overridden.

fn set_rcvlowat(&mut self, bytes: usize) -> Result<(), Error>

Specify the minimum number of bytes in the buffer until the socket layer will pass the data to the protocol (SO_SNDLOWAT) or the user on receiving (SO_RCVLOWAT). These two values are initialized to 1. SO_SNDLOWAT is not changeable on Linux (setsockopt(2) fails with the error ENOPROTOOPT). SO_RCVLOWAT is changeable only since Linux 2.4. The select(2) and poll(2) system calls currently do not respect the SO_RCVLOWAT setting on Linux, and mark a socket readable when even a single byte of data is available. A subsequent read from the socket will block until SO_RCVLOWAT bytes are available.

fn set_sndlowat(&mut self, bytes: usize) -> Result<(), Error>

Specify the minimum number of bytes in the buffer until the socket layer will pass the data to the protocol (SO_SNDLOWAT) or the user on receiving (SO_RCVLOWAT). These two values are initialized to 1. SO_SNDLOWAT is not changeable on Linux (setsockopt(2) fails with the error ENOPROTOOPT). SO_RCVLOWAT is changeable only since Linux 2.4. The select(2) and poll(2) system calls currently do not respect the SO_RCVLOWAT setting on Linux, and mark a socket readable when even a single byte of data is available. A subsequent read from the socket will block until SO_RCVLOWAT bytes are available.

fn set_rcvtimeo(
    &mut self,
    sec: time_t,
    micro_sec: suseconds_t
) -> Result<(), Error>

Specify the receiving or sending timeouts until reporting an error. The argument is a struct timeval. If an input or output function blocks for this period of time, and data has been sent or received, the return value of that function will be the amount of data transferred; if no data has been transferred and the timeout has been reached then -1 is returned with errno set to EAGAIN or EWOULDBLOCK, or EINPROGRESS (for connect(2)) just as if the socket was specified to be nonblocking. If the timeout is set to zero (the default) then the operation will never timeout. Timeouts only have effect for system calls that perform socket I/O (e.g., read(2), recvmsg(2), send(2), sendmsg(2)); timeouts have no effect for select(2), poll(2), epoll_wait(2), and so on.

fn set_sndtimeo(
    &mut self,
    sec: time_t,
    micro_sec: suseconds_t
) -> Result<(), Error>

Specify the receiving or sending timeouts until reporting an error. The argument is a struct timeval. If an input or output function blocks for this period of time, and data has been sent or received, the return value of that function will be the amount of data transferred; if no data has been transferred and the timeout has been reached then -1 is returned with errno set to EAGAIN or EWOULDBLOCK, or EINPROGRESS (for connect(2)) just as if the socket was specified to be nonblocking. If the timeout is set to zero (the default) then the operation will never timeout. Timeouts only have effect for system calls that perform socket I/O (e.g., read(2), recvmsg(2), send(2), sendmsg(2)); timeouts have no effect for select(2), poll(2), epoll_wait(2), and so on.

fn set_reuseaddr(&mut self, option: bool) -> Result<(), Error>

Indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. For AF_INET sockets this means that a socket may bind, except when there is an active listening socket bound to the address. When the listening socket is bound to INADDR_ANY with a specific port then it is not possible to bind to this port for any local address. Argument is an integer boolean flag.

fn set_sndbuf(&mut self, size: usize) -> Result<(), Error>

Sets or gets the maximum socket send buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using setsockopt(2), and this doubled value is returned by getsockopt(2). The default value is set by the /proc/sys/net/core/wmem_default file and the maximum allowed value is set by the /proc/sys/net/core/wmem_max file. The minimum (doubled) value for this option is 2048.

fn set_sndbufforce(&mut self, size: usize) -> Result<(), Error>

Using this socket option, a privileged (CAP_NET_ADMIN) process can perform the same task as SO_SNDBUF, but the wmem_max limit can be overridden.

fn set_timestamp(&mut self, option: bool) -> Result<(), Error>

Enable or disable the receiving of the SO_TIMESTAMP control message. The timestamp control message is sent with level SOL_SOCKET and the cmsg_data field is a struct timeval indicating the reception time of the last packet passed to the user in this call. See cmsg(3) for details on control messages.

Trait Implementations

impl Read for Socket

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

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

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

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

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

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

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

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

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

fn chars(self) -> Chars<Self>

🔬 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 chars.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

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

impl Write for Socket

fn write(&mut self, buf: &[u8]) -> Result<usize, Error>

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

fn flush(&mut self) -> Result<(), Error>

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

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

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

fn by_ref(&mut self) -> &mut Self

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

impl AsRawFd for Socket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Send for Socket

impl Sync for Socket