net #

Description

net provides networking functions. It is mostly a wrapper to BSD sockets, so you can listen on a port, connect to remote TCP/UDP services, and communicate with them.

Blocking TCP reads on POSIX sockets use SO_RCVTIMEO to enforce the configured read timeout directly in recv, avoiding a readiness poll before each read. set_read_timeout updates this socket timeout; no_timeout and infinite_timeout disable it. Deadline-only reads and nonblocking reads continue to use readiness polling, as do sockets that do not support the receive-timeout option.

A deadline set with set_read_deadline, set_write_deadline or set_accept_deadline takes precedence over the matching timeout for as long as it is set: a UDP read with a 400 ms deadline waits 400 ms even under the 100 ms default timeout, and a TCP accept, whose timeout is infinite by default, ends at its deadline. Set the deadline back to time.Time{} or time.unix(0) to return to the timeout. These are the only unset deadline values; other timestamps, including those within the first second of 1970, expire when they are in the past. The same rules apply to net.unix waits. With an unset deadline and no_timeout or infinite_timeout, a wait has no time limit. The deadline getters return an error for either unset value and otherwise return the timestamp, including when it has already expired. Far-future deadlines, including dates in year 9999, remain finite and retain their full timestamp. Waits use bounded intervals internally so the remaining time cannot overflow a duration.

A deadline applies where an operation waits before its system call: the wait_for_read/wait_for_write/wait_for_accept methods, and in the default build TCP reads and accepts and UDP reads. In the default build, writes (TCP, UDP and Unix) and Unix stream reads and accepts call send/recv/accept first and block there, where no deadline reaches them. Builds with -d net_nonblocking_sockets or -use-coroutines take other paths.

Networking APIs support -autofree. Invalid-port and timeout results own their error values, while preserving the messages and codes of the corresponding net.err_* constants.

UDP multicast example:

import net

mut socket := net.listen_udp('0.0.0.0:9999')!
socket.join_multicast_group('224.0.0.1', '0.0.0.0')!
socket.set_multicast_ttl(2)!
socket.set_multicast_loop(true)!

Addresses print as host:port, with IPv6 bracketed and rendered per RFC 5952: 127.0.0.1:8080, [2001:db8::1]:8080. A scoped (link-local) address also carries its RFC 4007 zone, as the numeric interface index the kernel reported: [fe80::1%3]:8080. Both split_address and dial_tcp accept that form, so an address read off a socket with peer_addr() stays usable as a dial target.

lookup_host(name) resolves a host name to IPv4 and IPv6 address strings in resolver order. resolve_ip(name) returns the first address. Numeric literals are accepted, including bare or bracketed IPv6, and results omit brackets and ports. Pass only a host name: host:port inputs, malformed brackets, empty names, and names containing NUL bytes return errors. DNS results depend on the host's resolver configuration and can contain more than one address.

IPv4 subnets

parse_cidr('192.168.1.77/24')! creates an IPNet retaining the original address and computing its masked network(), broadcast(), and size(). contains('192.168.1.2') checks membership and returns false for malformed queries. Prefixes range from 0 to 32. parse_ip and format_ip convert between dotted IPv4 addresses and u32 values. Parsing rejects invalid octets, leading zeroes, and numeric overflow. IPv6 CIDR is unsupported.

resolve_ipaddrs rejects an empty address with an error. Use :port for the IPv4 or IPv6 wildcard address, according to the selected address family.

fn addr_from_socket_handle(handle int) Addr

addr_from_socket_handle returns an address, based on the given integer socket handle

fn canonical_ipv6(addr string) !string

canonical_ipv6 takes any RFC 4291 legitimate text form (full, "::"-compressed, or with an embedded IPv4 dotted-quad tail) and returns the RFC 5952 canonical form.

fn canonical_ipv6_from_bytes(b []u8) !string

canonical_ipv6_from_bytes formats a 16-byte IPv6 address as the canonical text representation defined by RFC 5952. Errors only when the input slice is not exactly 16 octets long.

fn close(handle int) !

close a socket, given its file descriptor handle. In non-blocking mode, if close() does not succeed immediately, it causes an error to be propagated to TcpSocket.close(), which is not intended. Therefore, select is used just like connect().

fn default_tcp_dialer() Dialer

default_tcp_dialer will give you an instance of Dialer, that is suitable for making new tcp connections.

fn dial_tcp(oaddress string) !&TcpConn

dial_tcp will try to create a new TcpConn to the given address.

fn dial_tcp_with_bind(saddr string, laddr string) !&TcpConn

dial_tcp_with_bind will bind the given local address laddr and dial.

fn dial_udp(raddr string) !&UdpConn

fn error_code() int

Error code returns the last socket error

fn format_ip(ip u32) string

format_ip renders a u32 as a dotted quad.

fn listen_tcp(family AddrFamily, saddr string, options ListenOptions) !&TcpListener

fn listen_udp(laddr string) !&UdpConn

fn lookup_host(name string) ![]string

lookup_host resolves a host name to the list of its IP address literals, in the order the resolver returned them. Numeric inputs resolve without touching DNS, so the function is safe on values that may or may not need resolution. name is a host name, not a host:port pair. IPv6 literals may optionally be bracketed; a trailing port is rejected. It is the V-idiomatic equivalent of Node's dns.lookup / Go's net.LookupHost.

fn new_ip(port u16, addr [4]u8) Addr

new_ip creates a new Addr from the IPv4 address family, based on the given port and addr

fn new_ip6(port u16, addr [16]u8) Addr

new_ip6 creates a new Addr from the IP6 address family, based on the given port and addr

fn new_raw_socket(config RawSocketConfig) !&RawConn

new_raw_socket creates a new raw socket with the given configuration. Raw sockets typically require elevated privileges (root/administrator).

fn new_tcp_socket(family AddrFamily) !TcpSocket

This is a workaround for issue https://github.com/vlang/v/issues/20858 noline ensure that in -prod mode(CFLAG = -O3 -flto), gcc does not generate wrong instruction sequence

fn parse_cidr(s string) !IPNet

parse_cidr parses 'address/prefix' with prefix 0..32.

fn parse_ip(s string) !u32

parse_ip parses a dotted quad into its u32 value.

fn peer_addr_from_socket_handle(handle int) !Addr

peer_addr_from_socket_handle retrieves the ip address and port number, given a socket handle

fn resolve_addrs(addr string, family AddrFamily, typ SocketType) ![]Addr

resolve_addrs converts the given addr, family and typ to a list of addresses

fn resolve_addrs_fuzzy(addr string, typ SocketType) ![]Addr

resolve_addrs converts the given addr and typ to a list of addresses

fn resolve_ip(name string) !string

resolve_ip resolves a host name and returns its first address, the common convenience case.

fn resolve_ipaddrs(addr string, family AddrFamily, typ SocketType) ![]Addr

resolve_ipaddrs converts the given addr, family and typ to a list of addresses. An empty address returns an error; :port selects the wildcard address.

fn set_blocking(handle int, state bool) !

set_blocking will change the state of the socket to either blocking, when state is true, or non blocking (false).

fn shutdown(handle int, config ShutdownConfig) int

shutdown shutsdown a socket, given its file descriptor handle. By default it shuts it down in both directions, both for reading and for writing. You can change that using net.shutdown(handle, how: .read) or net.shutdown(handle, how: .write) In non-blocking mode, shutdown() may not succeed immediately, so select is also used to make sure that the function doesn't return an incorrect result.

fn socket_error(potential_code int) !int

fn socket_error_message(potential_code int, s string) !int

fn split_address(addr string) !(string, u16)

split_address splits an address into its host name and its port

fn tcp_socket_from_handle_raw(sockfd int) TcpSocket

tcp_socket_from_handle_raw is similar to tcp_socket_from_handle, but it does not modify any socket options

fn validate_port(port int) !u16

validate_port checks whether a port is valid and returns the port or an error. The valid ports numbers are between 0 and 0xFFFF. For TCP, port number 0 is reserved and cannot be used, while for UDP, the source port is optional and a value of zero means no port. See also https://en.wikipedia.org/wiki/Port_%28computer_networking%29 .

fn wrap_error(error_code int) !

Available on Windows only.

fn wsa_error(code int) WsaError

wsa_error casts an int to its WsaError value

fn AddrFamily.from[W](input W) !AddrFamily

from returns the AddrFamily value of an integer or of a field name, or an error if there is none.

fn Protocol.from[W](input W) !Protocol

from returns the Protocol value of an integer or of a field name, or an error if there is none.

fn ShutdownDirection.from[W](input W) !ShutdownDirection

from returns the ShutdownDirection value of an integer or of a field name, or an error if there is none.

fn SocketOption.from[W](input W) !SocketOption

from returns the SocketOption value of an integer or of a field name, or an error if there is none.

fn SocketType.from[W](input W) !SocketType

from returns the SocketType value of an integer or of a field name, or an error if there is none.

Available on Windows only.

fn WsaError.from[W](input W) !WsaError

from returns the WsaError value of an integer or of a field name, or an error if there is none.

interface Connection {
	addr() !Addr
	peer_addr() !Addr
mut:
	read(mut []u8) !int
	write([]u8) !int
	close() !
}

Connection provides a generic SOCK_STREAM style interface that protocols can use as a base connection object to support TCP, UNIX Domain Sockets and various proxying solutions.

interface Dialer {
	dial(address string) !Connection
}

Dialer is an abstract dialer interface for producing connections to addresses.

fn (mut s RawSocket) set_option_bool(opt SocketOption, value bool) !

set_option_bool sets a boolean socket option.

fn (mut s RawSocket) set_option_int(opt SocketOption, value int) !

set_option_int sets an integer socket option.

fn (mut s RawSocket) set_ip_header_included(on bool) !

set_ip_header_included enables or disables the IP_HDRINCL option. When enabled, the user must provide the complete IP header.

fn (mut s RawSocket) close() !

close shuts down and closes the socket.

fn (mut s RawSocket) select(test Select, timeout time.Duration) !bool

select waits for no more than timeout for the IO operation, defined by test, to be available.

fn (s &RawSocket) remote() ?Addr

remote returns the remote Addr of the socket or none if not set.

fn (mut s UdpSocket) set_option_bool(opt SocketOption, value bool) !

set_option_bool sets a boolean socket option on the UDP socket.

fn (mut s UdpSocket) set_dualstack(on bool) !

set_dualstack enables or disables dual-stack behavior for IPv6 UDP sockets.

fn (mut s UdpSocket) close() !

close shuts down and closes the socket for communication.

fn (mut s UdpSocket) select(test Select, timeout time.Duration) !bool

select waits for no more than timeout for the IO operation, defined by test, to be available.

fn (s &UdpSocket) remote() ?Addr

remote returns the remote Addr address of the socket or none if no remote is has been resolved.

enum AddrFamily {
	unix   = C.AF_UNIX
	ip     = C.AF_INET
	ip6    = C.AF_INET6
	unspec = C.AF_UNSPEC
}

AddrFamily are the available address families

enum Protocol {
	not_set = 0
	icmp    = C.IPPROTO_ICMP
	tcp     = C.IPPROTO_TCP
	udp     = C.IPPROTO_UDP
	ipv6    = C.IPPROTO_IPV6
	raw     = C.IPPROTO_RAW
	icmpv6  = C.IPPROTO_ICMPV6
}

Protocol specifies the IP protocol to use with raw sockets.

enum ShutdownDirection {
	read
	write
	read_and_write
}

ShutdownDirection is used by net.shutdown, for specifying the direction for which the communication will be cut.

enum SocketOption {
	// TODO: SO_ACCEPT_CONN is not here because windows doesn't support it
	// and there is no easy way to define it
	broadcast        = C.SO_BROADCAST
	debug            = C.SO_DEBUG
	dont_route       = C.SO_DONTROUTE
	error            = C.SO_ERROR
	keep_alive       = C.SO_KEEPALIVE
	linger           = C.SO_LINGER
	oob_inline       = C.SO_OOBINLINE
	reuse_addr       = C.SO_REUSEADDR
	receive_buf_size = C.SO_RCVBUF
	receive_low_size = C.SO_RCVLOWAT
	receive_timeout  = C.SO_RCVTIMEO
	send_buf_size    = C.SO_SNDBUF
	send_low_size    = C.SO_SNDLOWAT
	send_timeout     = C.SO_SNDTIMEO
	socket_type      = C.SO_TYPE
	ipv6_only        = C.IPV6_V6ONLY
	ip_proto_ipv6    = C.IPPROTO_IPV6
	// reuse_port       = C.SO_REUSEPORT // TODO make it work in windows
	// tcp_fastopen     = C.TCP_FASTOPEN // TODO make it work in windows
	// tcp_quickack     = C.TCP_QUICKACK // TODO make it work in os != linux
	// tcp_defer_accept = C.TCP_DEFER_ACCEPT // TODO make it work in windows
}

enum SocketType {
	udp       = C.SOCK_DGRAM
	tcp       = C.SOCK_STREAM
	seqpacket = C.SOCK_SEQPACKET
	raw       = C.SOCK_RAW
}

SocketType are the available sockets

Available on Windows only.

enum WsaError {
	// MessageId: WSAEINTR, A blocking operation was interrupted by a call to WSACancelBlockingCall.
	wsaeintr                    = 10004
	// MessageId: WSAEBADF, The file handle supplied is not valid.
	wsaebadf                    = 10009
	// MessageId: WSAEACCES, An attempt was made to access a socket in a way forbidden by its access permissions.
	wsaeacces                   = 10013
	// MessageId: WSAEFAULT, The system detected an invalid pointer address in attempting to use a pointer argument in a call.
	wsaefault                   = 10014
	// MessageId: WSAEINVAL, An invalid argument was supplied.
	wsaeinval                   = 10022
	// MessageId: WSAEMFILE, Too many open sockets.
	wsaemfile                   = 10024
	// MessageId: WSAEWOULDBLOCK, A non-blocking socket operation could not be completed immediately.
	wsaewouldblock              = 10035
	// MessageId: WSAEINPROGRESS, A blocking operation is currently executing.
	wsaeinprogress              = 10036
	// MessageId: WSAEALREADY, An operation was attempted on a non-blocking socket that already had an operation in progress.
	wsaealready                 = 10037
	// MessageId: WSAENOTSOCK, An operation was attempted on something that is not a socket.
	wsaenotsock                 = 10038
	// MessageId: WSAEDESTADDRREQ, A required address was omitted from an operation on a socket.
	wsaedestaddrreq             = 10039
	// MessageId: WSAEMSGSIZE, A message sent on a datagram socket was larger than the internal message buffer or some other network limit, or the buffer used to receive a datagram into was smaller than the datagram itself.
	wsaemsgsize                 = 10040
	// MessageId: WSAEPROTOTYPE, A protocol was specified in the socket function call that does not support the semantics of the socket type requested.
	wsaeprototype               = 10041
	// MessageId: WSAENOPROTOOPT, An unknown, invalid, or unsupported option or level was specified in a getsockopt or setsockopt call.
	wsaenoprotoopt              = 10042
	// MessageId: WSAEPROTONOSUPPORT, The requested protocol has not been configured into the system, or no implementation for it exists.
	wsaeprotonosupport          = 10043
	// MessageId: WSAESOCKTNOSUPPORT, The support for the specified socket type does not exist in this address family.
	wsaesocktnosupport          = 10044
	// MessageId: WSAEOPNOTSUPP, The attempted operation is not supported for the type of object referenced.
	wsaeopnotsupp               = 10045
	// MessageId: WSAEPFNOSUPPORT, The protocol family has not been configured into the system or no implementation for it exists.
	wsaepfnosupport             = 10046
	// MessageId: WSAEAFNOSUPPORT, An address incompatible with the requested protocol was used.
	wsaeafnosupport             = 10047
	// MessageId: WSAEADDRINUSE, Only one usage of each socket address (protocol/network address/port) is normally permitted.
	wsaeaddrinuse               = 10048
	// MessageId: WSAEADDRNOTAVAIL, The requested address is not valid in its context.
	wsaeaddrnotavail            = 10049
	// MessageId: WSAENETDOWN, A socket operation encountered a dead network.
	wsaenetdown                 = 10050
	// MessageId: WSAENETUNREACH, A socket operation was attempted to an unreachable network.
	wsaenetunreach              = 10051
	// MessageId: WSAENETRESET, The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress.
	wsaenetreset                = 10052
	// MessageId: WSAECONNABORTED, An established connection was aborted by the software in your host machine.
	wsaeconnaborted             = 10053
	// MessageId: WSAECONNRESET, An existing connection was forcibly closed by the remote host.
	wsaeconnreset               = 10054
	// MessageId: WSAENOBUFS, An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full.
	wsaenobufs                  = 10055
	// MessageId: WSAEISCONN, A connect request was made on an already connected socket.
	wsaeisconn                  = 10056
	// MessageId: WSAENOTCONN, A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no address was supplied.
	wsaenotconn                 = 10057
	// MessageId: WSAESHUTDOWN, A request to send or receive data was disallowed because the socket had already been shut down in that direction with a previous shutdown call.
	wsaeshutdown                = 10058
	// MessageId: WSAETOOMANYREFS, Too many references to some kernel object.
	wsaetoomanyrefs             = 10059
	// MessageId: WSAETIMEDOUT, A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.
	wsaetimedout                = 10060
	// MessageId: WSAECONNREFUSED, No connection could be made because the target machine actively refused it.
	wsaeconnrefused             = 10061
	// MessageId: WSAELOOP, Cannot translate name.
	wsaeloop                    = 10062
	// MessageId: WSAENAMETOOLONG, Name component or name was too long.
	wsaenametoolong             = 10063
	// MessageId: WSAEHOSTDOWN, A socket operation failed because the destination host was down.
	wsaehostdown                = 10064
	// MessageId: WSAEHOSTUNREACH, A socket operation was attempted to an unreachable host.
	wsaehostunreach             = 10065
	// MessageId: WSAENOTEMPTY, Cannot remove a directory that is not empty.
	wsaenotempty                = 10066
	// MessageId: WSAEPROCLIM, A Windows Sockets implementation may have a limit on the number of applications that may use it simultaneously.
	wsaeproclim                 = 10067
	// MessageId: WSAEUSERS, Ran out of quota.
	wsaeusers                   = 10068
	// MessageId: WSAEDQUOT, Ran out of disk quota.
	wsaedquot                   = 10069
	// MessageId: WSAESTALE, File handle reference is no longer available.
	wsaestale                   = 10070
	// MessageId: WSAEREMOTE, Item is not available locally.
	wsaeremote                  = 10071
	// MessageId: WSASYSNOTREADY, WSAStartup cannot function at this time because the underlying system it uses to provide network services is currently unavailable.
	wsasysnotready              = 10091
	// MessageId: WSAVERNOTSUPPORTED, The Windows Sockets version requested is not supported.
	wsavernotsupported          = 10092
	// MessageId: WSANOTINITIALISED, Either the application has not called WSAStartup, or WSAStartup failed.
	wsanotinitialised           = 10093
	// MessageId: WSAEDISCON, Returned by WSARecv or WSARecvFrom to indicate the remote party has initiated a graceful shutdown sequence.
	wsaediscon                  = 10101
	// MessageId: WSAENOMORE, No more results can be returned by WSALookupServiceNext.
	wsaenomore                  = 10102
	// MessageId: WSAECANCELLED, A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled.
	wsaecancelled               = 10103
	// MessageId: WSAEINVALIDPROCTABLE, The procedure call table is invalid.
	wsaeinvalidproctable        = 10104
	// MessageId: WSAEINVALIDPROVIDER, The requested service provider is invalid.
	wsaeinvalidprovider         = 10105
	// MessageId: WSAEPROVIDERFAILEDINIT, The requested service provider could not be loaded or initialized.
	wsaeproviderfailedinit      = 10106
	// MessageId: WSASYSCALLFAILURE, A system call has failed.
	wsasyscallfailure           = 10107
	// MessageId: WSASERVICE_NOT_FOUND, No such service is known. The service cannot be found in the specified name space.
	wsaservice_not_found        = 10108
	// MessageId: WSATYPE_NOT_FOUND, The specified class was not found.
	wsatype_not_found           = 10109
	// MessageId: WSA_E_NO_MORE, No more results can be returned by WSALookupServiceNext.
	wsa_e_no_more               = 10110
	// MessageId: WSA_E_CANCELLED, A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled.
	wsa_e_cancelled             = 10111
	// MessageId: WSAEREFUSED, A database query failed because it was actively refused.
	wsaerefused                 = 10112
	// MessageId: WSAHOST_NOT_FOUND, No such host is known.
	wsahost_not_found           = 11001
	// MessageId: WSATRY_AGAIN, This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server.
	wsatry_again                = 11002
	// MessageId: WSANO_RECOVERY, A non-recoverable error occurred during a database lookup.
	wsano_recovery              = 11003
	// MessageId: WSANO_DATA, The requested name is valid, but no data of the requested type was found.
	wsano_data                  = 11004
	// MessageId: WSA_QOS_RECEIVERS, At least one reserve has arrived.
	wsa_qos_receivers           = 11005
	// MessageId: WSA_QOS_SENDERS, At least one path has arrived.
	wsa_qos_senders             = 11006
	// MessageId: WSA_QOS_NO_SENDERS, There are no senders.
	wsa_qos_no_senders          = 11007
	// MessageId: WSA_QOS_NO_RECEIVERS, There are no receivers.
	wsa_qos_no_receivers        = 11008
	// MessageId: WSA_QOS_REQUEST_CONFIRMED, Reserve has been confirmed.
	wsa_qos_request_confirmed   = 11009
	// MessageId: WSA_QOS_ADMISSION_FAILURE, Error due to lack of resources.
	wsa_qos_admission_failure   = 11010
	// MessageId: WSA_QOS_POLICY_FAILURE, Rejected for administrative reasons - bad credentials.
	wsa_qos_policy_failure      = 11011
	// MessageId: WSA_QOS_BAD_STYLE, Unknown or conflicting style.
	wsa_qos_bad_style           = 11012
	// MessageId: WSA_QOS_BAD_OBJECT, Problem with some part of the filterspec or providerspecific buffer in general.
	wsa_qos_bad_object          = 11013
	// MessageId: WSA_QOS_TRAFFIC_CTRL_ERROR, Problem with some part of the flowspec.
	wsa_qos_traffic_ctrl_error  = 11014
	// MessageId: WSA_QOS_GENERIC_ERROR, General QOS error.
	wsa_qos_generic_error       = 11015
	// MessageId: WSA_QOS_ESERVICETYPE, An invalid or unrecognized service type was found in the flowspec.
	wsa_qos_eservicetype        = 11016
	// MessageId: WSA_QOS_EFLOWSPEC, An invalid or inconsistent flowspec was found in the QOS structure.
	wsa_qos_eflowspec           = 11017
	// MessageId: WSA_QOS_EPROVSPECBUF, Invalid QOS provider-specific buffer.
	wsa_qos_eprovspecbuf        = 11018
	// MessageId: WSA_QOS_EFILTERSTYLE, An invalid QOS filter style was used.
	wsa_qos_efilterstyle        = 11019
	// MessageId: WSA_QOS_EFILTERTYPE, An invalid QOS filter type was used.
	wsa_qos_efiltertype         = 11020
	// MessageId: WSA_QOS_EFILTERCOUNT, An incorrect number of QOS FILTERSPECs were specified in the FLOWDESCRIPTOR.
	wsa_qos_efiltercount        = 11021
	// MessageId: WSA_QOS_EOBJLENGTH, An object with an invalid ObjectLength field was specified in the QOS provider-specific buffer.
	wsa_qos_eobjlength          = 11022
	// MessageId: WSA_QOS_EFLOWCOUNT, An incorrect number of flow descriptors was specified in the QOS structure.
	wsa_qos_eflowcount          = 11023
	// MessageId: WSA_QOS_EUNKOWNPSOBJ, An unrecognized object was found in the QOS provider-specific buffer.
	wsa_qos_eunkownpsobj        = 11024
	// MessageId: WSA_QOS_EPOLICYOBJ, An invalid policy object was found in the QOS provider-specific buffer.
	wsa_qos_epolicyobj          = 11025
	// MessageId: WSA_QOS_EFLOWDESC, An invalid QOS flow descriptor was found in the flow descriptor list.
	wsa_qos_eflowdesc           = 11026
	// MessageId: WSA_QOS_EPSFLOWSPEC, An invalid or inconsistent flowspec was found in the QOS provider specific buffer.
	wsa_qos_epsflowspec         = 11027
	// MessageId: WSA_QOS_EPSFILTERSPEC, An invalid FILTERSPEC was found in the QOS provider-specific buffer.
	wsa_qos_epsfilterspec       = 11028
	// MessageId: WSA_QOS_ESDMODEOBJ, An invalid shape discard mode object was found in the QOS provider specific buffer.
	wsa_qos_esdmodeobj          = 11029
	// MessageId: WSA_QOS_ESHAPERATEOBJ, An invalid shaping rate object was found in the QOS provider-specific buffer.
	wsa_qos_eshaperateobj       = 11030
	// MessageId: WSA_QOS_RESERVED_PETYPE, A reserved policy element was found in the QOS provider-specific buffer.
	wsa_qos_reserved_petype     = 11031
	// MessageId: WSA_SECURE_HOST_NOT_FOUND, No such host is known securely.
	wsa_secure_host_not_found   = 11032
	// MessageId: WSA_IPSEC_NAME_POLICY_ERROR, Name based IPSEC policy could not be added.
	wsa_ipsec_name_policy_error = 11033
}

WsaError is all of the socket errors that WSA provides from WSAGetLastError

Available on Linux, Windows, Android and Termux only.

@[_pack: '1']
struct Addr {
pub:
	f    u16
	addr AddrData
}

Available on macOS, FreeBSD, OpenBSD, NetBSD and DragonFly BSD only.

@[_pack: '1']
struct Addr {
pub:
	len  u8
	f    u8
	addr AddrData
}

fn (a Addr) family() AddrFamily

family returns the family/kind of the given address a

fn (a Addr) port() !u16

port returns the ip or ip6 port of the given address a

fn (a &Addr) len() u32

len returns the length in bytes of the address a, depending on its family

fn (a Addr) str() string

str returns a string representation of the address a

Available on Windows only.

struct C.WSADATA {
mut:
	wVersion       u16
	wHighVersion   u16
	szDescription  [257]u8
	szSystemStatus [129]u8
	iMaxSockets    u16
	iMaxUdpDg      u16
	lpVendorInfo   &u8
}

Available on Windows only.

struct C.WSAData {
mut:
	wVersion       u16
	wHighVersion   u16
	szDescription  [257]u8
	szSystemStatus [129]u8
	iMaxSockets    u16
	iMaxUdpDg      u16
	lpVendorInfo   &u8
}

struct C.addrinfo {
mut:
	ai_family    i32
	ai_socktype  i32
	ai_flags     i32
	ai_protocol  i32
	ai_addrlen   i32
	ai_addr      voidptr
	ai_canonname voidptr
	ai_next      voidptr
}

struct C.fd_set {}

Available on Linux, Windows, Android and Termux only.

struct C.sockaddr_in {
mut:
	sin_family u16
	sin_port   u16
	sin_addr   u32
}

Available on macOS, FreeBSD, OpenBSD, NetBSD and DragonFly BSD only.

struct C.sockaddr_in {
mut:
	sin_len    u8
	sin_family u8
	sin_port   u16
	sin_addr   u32
	sin_zero   [8]char
}

Available on iOS, Solaris, Haiku, SerenityOS and Vinix only.

struct C.sockaddr_in {
mut:
	sin_family u8
	sin_port   u16
	sin_addr   u32
}

Available on Linux, Windows, Android and Termux only.

struct C.sockaddr_in6 {
mut:
	sin6_family u16
	sin6_port   u16
	sin6_addr   [4]u32
}

Available on macOS, FreeBSD, OpenBSD, NetBSD and DragonFly BSD only.

struct C.sockaddr_in6 {
mut:
	// 1 + 1 + 2 + 4 + 16 + 4 = 28;
	sin6_len      u8     // 1
	sin6_family   u8     // 1
	sin6_port     u16    // 2
	sin6_flowinfo u32    // 4
	sin6_addr     [16]u8 // 16
	sin6_scope_id u32    // 4
}

Available on iOS, Solaris, Haiku, SerenityOS and Vinix only.

struct C.sockaddr_in6 {
mut:
	sin6_family u8
	sin6_port   u16
	sin6_addr   [4]u32
}

Available on Linux, Windows, Android and Termux only.

struct C.sockaddr_un {
mut:
	sun_family u16
	sun_path   [max_unix_path]char
}

Available on macOS, FreeBSD, OpenBSD, NetBSD and DragonFly BSD only.

struct C.sockaddr_un {
mut:
	sun_len    u8
	sun_family u8
	sun_path   [max_unix_path]char
}

Available on iOS, Solaris, Haiku, SerenityOS and Vinix only.

struct C.sockaddr_un {
mut:
	sun_family u8
	sun_path   [max_unix_path]char
}

struct IPNet {
pub:
	ip         u32 // the address as written, before masking
	prefix     int
	mask       u32
	network_   u32
	broadcast_ u32
}

IPNet is a parsed IPv4 CIDR block, e.g. 192.168.1.0/24: the network address, prefix length and derived broadcast/size. It is the V-idiomatic equivalent of the IPv4 half of Python's ipaddress (IPv6 is a stated follow-up reusing ipv6.v). ACLs, firewall rules and peer selection all need this; vlib/net previously only canonicalized addresses.

fn (n &IPNet) contains(ip string) bool

contains reports whether the dotted-quad ip lies in the block. Malformed input is simply not contained.

fn (n &IPNet) network() string

network returns the network address literal.

fn (n &IPNet) broadcast() string

broadcast returns the directed-broadcast literal (network | ~mask).

fn (n &IPNet) size() u64

size returns the number of addresses in the block (2 for /31, 1 for /32).

Available on all platforms except iOS, Solaris, Haiku, SerenityOS and Vinix.

struct Ip {
	port u16
	addr [4]u8
	// Pad to size so that socket functions
	// dont complain to us (see  in.h and bind())
	// TODO(emily): I would really like to use
	// some constant calculations here
	// so that this doesnt have to be hardcoded
	sin_pad [8]u8
}

fn (a Ip) str() string

str returns a string representation of a

Available on all platforms except iOS, Solaris, Haiku, SerenityOS and Vinix.

struct Ip6 {
	port      u16
	flow_info u32
	addr      [16]u8
	scope_id  u32
}

fn (a Ip6) str() string

str returns a string representation of a. The IPv6 portion is rendered per RFC 5952 by canonical_ipv6_from_bytes (pure V), instead of libc's inet_ntop, which historically emits the deprecated IPv4-compatible mixed form (::a.b.c.d) for any address with the upper 96 bits zero.

A non-zero scope_id is appended as an RFC 4007 zone identifier, as in [fe80::1%3]:8080. Without it, link-local peers reached over different interfaces are indistinguishable, and the address cannot be dialled back: a link-local address only identifies a host together with its zone. The zone is the numeric interface index the kernel reported, which is what getaddrinfo (and so net.dial_tcp/split_address) accepts here, since V does not wrap if_indextoname to map it to a name.

scope_id is zero for every global and loopback address, so ordinary IPv6 addresses render exactly as before.

struct ListenOptions {
pub:
	dualstack bool = true
	backlog   int  = 128
}

struct RawConn {
pub mut:
	sock RawSocket
mut:
	write_deadline time.Time
	read_deadline  time.Time
	read_timeout   time.Duration
	write_timeout  time.Duration
}

RawConn represents a raw socket connection for low-level network access. Raw sockets allow sending and receiving packets at the IP layer, bypassing the TCP/UDP transport layer.

fn (mut c RawConn) write_ptr(b &u8, len int) !int

write_ptr writes data from b of length len to the connected remote address.

fn (mut c RawConn) write(buf []u8) !int

write writes buf to the connected remote address.

fn (mut c RawConn) write_string(s string) !int

write_string writes string s to the connected remote address.

fn (mut c RawConn) write_to_ptr(addr Addr, b &u8, len int) !int

write_to_ptr writes data from b of length len to the specified addr.

fn (mut c RawConn) write_to(addr Addr, buf []u8) !int

write_to writes buf to the specified addr.

fn (mut c RawConn) write_to_string(addr Addr, s string) !int

write_to_string writes string s to the specified addr.

fn (c &RawConn) read_ptr(buf_ptr &u8, len int) !(int, Addr)

read_ptr reads from the socket into buf_ptr up to len bytes, returning the number of bytes read and the source Addr.

fn (mut c RawConn) read(mut buf []u8) !(int, Addr)

read reads from the socket into buf, returning the number of bytes read and the source Addr.

fn (c &RawConn) read_deadline() !time.Time

read_deadline returns the current read deadline, or an error when it is unset.

fn (mut c RawConn) set_read_deadline(deadline time.Time)

set_read_deadline sets the read deadline.

fn (c &RawConn) write_deadline() !time.Time

write_deadline returns the current write deadline, or an error when it is unset.

fn (mut c RawConn) set_write_deadline(deadline time.Time)

set_write_deadline sets the write deadline.

fn (c &RawConn) read_timeout() time.Duration

read_timeout returns the current read timeout duration.

fn (mut c RawConn) set_read_timeout(t time.Duration)

set_read_timeout sets the read timeout duration.

fn (c &RawConn) write_timeout() time.Duration

write_timeout returns the current write timeout duration.

fn (mut c RawConn) set_write_timeout(t time.Duration)

set_write_timeout sets the write timeout duration.

fn (c &RawConn) wait_for_read() !

wait_for_read waits for a read operation to be available.

fn (mut c RawConn) wait_for_write() !

wait_for_write waits for a write operation to be available.

fn (c &RawConn) str() string

str returns a string representation of the RawConn.

fn (mut c RawConn) close() !

close closes the raw socket connection.

fn (mut c RawConn) set_remote(addr Addr)

set_remote sets the remote address for write operations.

fn (c &RawConn) protocol() Protocol

protocol returns the protocol used by this socket.

fn (c &RawConn) addr() !Addr

addr returns the local address of the socket.

struct RawSocketConfig {
pub:
	family   AddrFamily = .ip
	protocol Protocol   = .icmp
}

RawSocketConfig configures the creation of a raw socket.

struct ShutdownConfig {
pub:
	how ShutdownDirection = .read_and_write
}

struct Socket {
pub:
	handle int
}

fn (s &Socket) address() !Addr

address gets the address of a socket

struct TCPDialer {}

TCPDialer is a concrete instance of the Dialer interface, for creating tcp connections.

fn (t TCPDialer) dial(address string) !Connection

dial will try to create a new abstract connection to the given address. It will return an error, if that is not possible.

struct TcpConn {
pub mut:
	sock           TcpSocket
	handle         int
	write_deadline time.Time
	read_deadline  time.Time
	read_timeout   time.Duration
	write_timeout  time.Duration
	is_blocking    bool = true
	// last_write_sent is the exact number of bytes the most recent write_ptr
	// call sent, valid even when it then returned an error (send() is
	// byte-accurate), so a caller can tell a zero-byte failure — 0, safe to
	// replay — from a partial write. (The TLS backends expose the same field but
	// use -1 for the indeterminate case they cannot prove; plain TCP never does.)
	last_write_sent int
mut:
	read_timeout_in_socket     bool
	socket_read_timeout_value  time.Duration
	socket_read_timeout_handle int
}

fn (mut c TcpConn) close() !

close closes the tcp connection

fn (c TcpConn) read_ptr(buf_ptr &u8, len int) !int

read_ptr reads data from the tcp connection to the given buffer. It reads at most len bytes. It returns the number of actually read bytes, which can vary between 0 to len.

fn (c TcpConn) read(mut buf []u8) !int

read reads data from the tcp connection into the mutable buffer buf. The number of bytes read is limited to the length of the buffer buf.len. The returned value is the number of read bytes (between 0 and buf.len).

fn (mut c TcpConn) read_deadline() !time.Time

read_deadline returns the current read deadline, or an error when it is unset.

fn (mut c TcpConn) write_ptr(b &u8, len int) !int

write_ptr blocks and attempts to write all data

fn (mut c TcpConn) write(bytes []u8) !int

write blocks and attempts to write all data

fn (mut c TcpConn) write_string(s string) !int

write_string blocks and attempts to write all data

fn (mut c TcpConn) set_read_deadline(deadline time.Time)

fn (mut c TcpConn) write_deadline() !time.Time

write_deadline returns the current write deadline, or an error when it is unset.

fn (mut c TcpConn) set_write_deadline(deadline time.Time)

fn (c &TcpConn) read_timeout() time.Duration

fn (mut c TcpConn) set_read_timeout(t time.Duration)

set_read_timeout sets the timeout used by subsequent reads. On POSIX sockets, blocking recv enforces it directly when the socket option is available.

fn (c &TcpConn) write_timeout() time.Duration

fn (mut c TcpConn) set_write_timeout(t time.Duration)

fn (c TcpConn) wait_for_read() !

fn (mut c TcpConn) wait_for_write() !

fn (mut c TcpConn) set_sock() !

set_sock initialises the c.sock field. It should be called after .accept_only()!.

Note: just use .accept()!. In most cases it is simpler, and calls .set_sock()! for you.

fn (c &TcpConn) peer_addr() !Addr

peer_addr retrieves the ip address and port number used by the peer

fn (c &TcpConn) peer_ip() !string

peer_ip retrieves the ip address used by the peer, and returns it as a string

fn (c &TcpConn) addr() !Addr

fn (c TcpConn) str() string

fn (mut con TcpConn) get_blocking() bool

get_blocking returns whether the connection is in a blocking state, that is calls to .read_line, C.recv etc will block till there is new data arrived, instead of returning immediately.

fn (mut con TcpConn) set_blocking(state bool) !

set_blocking will change the state of the connection to either blocking, when state is true, or non blocking (false). The default for net tcp connections is the blocking mode. Calling .read_line will set the connection to blocking mode. In general, changing the blocking mode after a successful connection may cause unexpected surprises, so this function is not recommended to be called anywhere but for this file.

fn (mut con TcpConn) read_line() string

read_line is a simple, non customizable, blocking line reader. It will return a line, ending with LF, or just '', on EOF.

Note: if you want more control over the buffer, please use a buffered IO reader instead: io.new_buffered_reader({reader: io.make_reader(con)})

fn (mut con TcpConn) read_line_max(max_line_len int) string

read_line_max is a simple, non customizable, blocking line reader. It will return a line, ending with LF, '' on EOF. It stops reading, when the result line length exceeds max_line_len.

struct TcpListener {
pub mut:
	sock            TcpSocket
	accept_timeout  time.Duration
	accept_deadline time.Time
	is_blocking     bool = true
}

fn (mut l TcpListener) accept() !&TcpConn

accept a tcp connection from an external source to the listener l.

fn (mut l TcpListener) accept_only() !&TcpConn

accept_only accepts a tcp connection from an external source to the listener l. Unlike accept, accept_only will not call .set_sock()! on the result, and is thus faster.

Note: you need to call .set_sock()! manually, before using theconnection after calling .accept_only()!, but that does not have to happen in the same thread that called .accept_only()!. The intention of this API, is to have a more efficient way to accept connections, that are later processed by a thread pool, while the main thread remains active, so that it can accept other connections. See also vlib/veb/veb.v .

If you do not need that, just call .accept()! instead, which will call .set_sock()! for you.

fn (c &TcpListener) accept_deadline() !time.Time

accept_deadline returns the current accept deadline, or an error when it is unset.

fn (mut c TcpListener) set_accept_deadline(deadline time.Time)

fn (c &TcpListener) accept_timeout() time.Duration

fn (mut c TcpListener) set_accept_timeout(t time.Duration)

fn (mut c TcpListener) wait_for_accept() !

fn (mut c TcpListener) close() !

fn (c &TcpListener) addr() !Addr

struct TcpSocket {
	Socket
}

fn (mut s TcpSocket) set_option_bool(opt SocketOption, value bool) !

fn (mut s TcpSocket) set_option_int(opt SocketOption, value int) !

fn (mut s TcpSocket) set_dualstack(on bool) !

fn (mut s TcpSocket) bind(addr string) !

bind a local rddress for TcpSocket

struct UdpConn {
pub mut:
	sock UdpSocket
mut:
	write_deadline time.Time
	read_deadline  time.Time
	read_timeout   time.Duration
	write_timeout  time.Duration
	is_blocking    bool = true
}

fn (mut c UdpConn) write_ptr(b &u8, len int) !int

fn (mut c UdpConn) write(buf []u8) !int

fn (mut c UdpConn) write_string(s string) !int

fn (mut c UdpConn) write_to_ptr(addr Addr, b &u8, len int) !int

fn (mut c UdpConn) write_to(addr Addr, buf []u8) !int

write_to blocks and writes the buf to the remote addr specified

fn (mut c UdpConn) write_to_string(addr Addr, s string) !int

write_to_string blocks and writes the buf to the remote addr specified

fn (c &UdpConn) read_ptr(buf_ptr &u8, len int) !(int, Addr)

read_ptr reads from the socket into buf_ptr up to len bytes, returning the number of bytes read and the Addr read from.

fn (mut c UdpConn) read(mut buf []u8) !(int, Addr)

read reads from the socket into buf up to buf.len returning the number of bytes read

fn (c &UdpConn) read_deadline() !time.Time

read_deadline returns the current read deadline, or an error when it is unset.

fn (mut c UdpConn) set_read_deadline(deadline time.Time)

fn (c &UdpConn) write_deadline() !time.Time

write_deadline returns the current write deadline, or an error when it is unset.

fn (mut c UdpConn) set_write_deadline(deadline time.Time)

fn (c &UdpConn) read_timeout() time.Duration

fn (mut c UdpConn) set_read_timeout(t time.Duration)

fn (c &UdpConn) write_timeout() time.Duration

fn (mut c UdpConn) set_write_timeout(t time.Duration)

fn (c &UdpConn) wait_for_read() !

fn (mut c UdpConn) wait_for_write() !

fn (c &UdpConn) str() string

fn (mut c UdpConn) close() !

fn (mut c UdpConn) join_multicast_group(multicast_addr string, iface_addr string) !

join_multicast_group joins the UDP socket to an IPv4 or IPv6 multicast group. For IPv4 sockets, iface_addr must be an IPv4 address or '' to use the default interface. For IPv6 sockets, iface_addr must be a numeric interface index or '' to use the default interface.

fn (mut c UdpConn) leave_multicast_group(multicast_addr string, iface_addr string) !

leave_multicast_group leaves an IPv4 or IPv6 multicast group previously joined by the socket. iface_addr follows the same rules as join_multicast_group.

fn (mut c UdpConn) set_multicast_ttl(ttl int) !

set_multicast_ttl sets the IPv4 TTL or IPv6 hop limit used for outgoing multicast traffic. Valid values are between 0 and 255 inclusive.

fn (mut c UdpConn) set_multicast_loop(enable bool) !

set_multicast_loop enables or disables local loopback for outgoing multicast packets.

fn (mut c UdpConn) set_multicast_interface(iface_addr string) !

set_multicast_interface sets the outgoing multicast interface for the UDP socket. For IPv4 sockets, iface_addr must be an IPv4 address or '' to clear it to the default interface. For IPv6 sockets, iface_addr must be a numeric interface index or '' to use the default interface.

Available on Linux, Windows, Android and Termux only.

struct Unix {
	path [max_unix_path]u8
}

Available on macOS, FreeBSD, OpenBSD, NetBSD and DragonFly BSD only.

struct Unix {
	path [max_unix_path]char
}