socket(3erl) Erlang Module Definition socket(3erl)
NAME
socket - Socket interface.
DESCRIPTION
This module provides an API for network socket. Functions are provided
to create, delete and manupilate the sockets aswell as sending and re-
civing data on them.
The intent is that it shall be as "close as possible" to the OS level
socket interface. The only significant addition is that some of the
functions, e.g. recv/3, has a timeout argument.
Note:
Some functions allow for an asynchronous call. This is achieved by
setting the Timeout argument to nowait. For instance, if calling the
recv/3 function with Timeout set to nowait (recv(Sock, 0, nowait)) when
there is actually nothing to read, it will return with {select, Se-
lectInfo} (SelectInfo contains the SelectRef). When data eventually ar-
rives a 'select' message will be sent to the caller:
: {'$socket', socket(), select, SelectRef}
The caller can now make another call to the recv function and now ex-
pect data.
Note that all other users are locked out until the 'current user' has
called the function (recv in this case).
Another message the user must be prepared for (when making asynchronous
calls) is the abort message:
: {'$socket', socket(), abort, Info}
This message indicates that the (asynchronous) operation has been
aborted. If, for instance, the socket has been closed (by another
process), Info will be {SelectRef, closed}.
Note:
There is currently no support for Windows.
Support for IPv6 has been implemented but not tested.
SCTP has only been partly implemented (and not tested).
DATA TYPES
domain() = local | inet | inet6
type() = stream | dgram | raw | rdm | seqpacket
protocol() =
ip | tcp | udp | sctp | icmp | igmp | {raw, integer()}
socket()
As returned by open/1,2,3,4 and accept/1,2.
select_tag()
A tag that describes the (select) operation.
select_ref()
A reference that uniquely identifies the (select) operation.
select_info() = {select_info, select_tag(), select_ref()}
socket_counters() =
#{read_byte := integer() >= 0,
read_fails := integer() >= 0,
read_pkg := integer() >= 0,
read_pkg_max := integer() >= 0,
read_tries := integer() >= 0,
read_waits := integer() >= 0,
write_byte := integer() >= 0,
write_fails := integer() >= 0,
write_pkg := integer() >= 0,
write_pkg_max := integer() >= 0,
write_tries := integer() >= 0,
write_waits := integer() >= 0,
acc_success := integer() >= 0,
acc_fails := integer() >= 0,
acc_tries := integer() >= 0,
acc_waits := integer() >= 0}
socket_info() =
#{domain := domain(),
type := type(),
protocol := protocol(),
ctrl := pid(),
ctype := normal | fromfd | {fromfd, integer()},
counters := socket_counters(),
num_readers := integer() >= 0,
num_writers := integer() >= 0,
num_acceptors := integer() >= 0,
writable := boolean(),
readable := boolean()}
ip4_address() = {0..255, 0..255, 0..255, 0..255}
ip6_address() =
{0..65535,
0..65535,
0..65535,
0..65535,
0..65535,
0..65535,
0..65535,
0..65535}
sockaddr() =
sockaddr_in4() |
sockaddr_in6() |
sockaddr_un() |
sockaddr_ll()
sockaddr_in4() =
#{family := inet,
port := port_number(),
addr := any | broadcast | loopback | ip4_address()}
sockaddr_in6() =
#{family := inet6,
port := port_number(),
addr := any | loopback | ip6_address(),
flowinfo := in6_flow_info(),
scope_id := in6_scope_id()}
sockaddr_un() = #{family := local, path := binary() | string()}
sockaddr_ll() =
#{family := packet,
protocol := integer() >= 0,
ifindex := integer(),
pkttype := packet_type(),
hatype := integer() >= 0,
addr := binary()}
packet_type() =
host | broadcast | multicast | otherhost | outgoing |
loopback | user | kernel | fastroute |
integer() >= 0
port_number() = 0..65535
in6_flow_info() = uint20()
in6_scope_id() = uint32()
send_flags() = [send_flag()]
send_flag() = confirm | dontroute | eor | more | nosignal | oob
recv_flags() = [recv_flag()]
recv_flag() = cmsg_cloexec | errqueue | oob | peek | trunc
shutdown_how() = read | write | read_write
sockopt_level() =
otp | socket | ip | ipv6 | tcp | udp | sctp |
integer() >= 0
otp_socket_option() =
debug | iow | controlling_process | rcvbuf | rcvctrlbuf |
sndctrlbuf | meta | fd
socket_option() =
acceptconn | acceptfilter | bindtodevice | broadcast |
busy_poll | debug | domain | dontroute | error | keepalive |
linger | mark | oobinline | passcred | peek_off | peercred |
priority | protocol | rcvbuf | rcvbufforce | rcvlowat |
rcvtimeo | reuseaddr | reuseport | rxq_ovfl | setfib |
sndbuf | sndbufforce | sndlowat | sndtimeo | timestamp | type
ip_socket_option() =
add_membership | add_source_membership | block_source |
dontfrag | drop_membership | drop_source_membership |
freebind | hdrincl | minttl | msfilter | mtu | mtu_discover |
multicast_all | multicast_if | multicast_loop |
multicast_ttl | nodefrag | options | pktinfo | recverr |
recvif | recvdstaddr | recvopts | recvorigdstaddr | recvtos |
recvttl | retopts | router_alert | sndsrcaddr | tos |
transparent | ttl | unblock_source
ipv6_socket_option() =
addrform | add_membership | authhdr | auth_level | checksum |
drop_membership | dstopts | esp_trans_level |
esp_network_level | faith | flowinfo | hopopts |
ipcomp_level | join_group | leave_group | mtu | mtu_discover |
multicast_hops | multicast_if | multicast_loop | portrange |
pktoptions | recverr | recvhoplimit | hoplimit | recvpktinfo |
pktinfo | recvtclass | router_alert | rthdr | tclass |
unicast_hops | use_min_mtu | v6only
tcp_socket_option() =
congestion | cork | info | keepcnt | keepidle | keepintvl |
maxseg | md5sig | nodelay | noopt | nopush | syncnt |
user_timeout
udp_socket_option() = cork
sctp_socket_option() =
adaption_layer | associnfo | auth_active_key | auth_asconf |
auth_chunk | auth_key | auth_delete_key | autoclose |
context | default_send_params | delayed_ack_time |
disable_fragments | hmac_ident | events | explicit_eor |
fragment_interleave | get_peer_addr_info | initmsg |
i_want_mapped_v4_addr | local_auth_chunks | maxseg |
maxburst | nodelay | partial_delivery_point |
peer_addr_params | peer_auth_chunks | primary_addr |
reset_streams | rtoinfo | set_peer_primary_addr | status |
use_ext_recvinfo
timeval() = #{sec := integer(), usec := integer()}
ip_tos() =
lowdelay | throughput | reliability | mincost | integer()
ip_mreq() =
#{multiaddr := ip4_address(),
interface := any | ip4_address()}
ip_mreq_source() =
#{multiaddr := ip4_address(),
interface := ip4_address(),
sourceaddr := ip4_address()}
ip_pmtudisc() = want | dont | do | probe
ip_msfilter_mode() = include | exclude
ip_msfilter() =
#{multiaddr := ip4_address(),
interface := ip4_address(),
mode := ip_msfilter_mode(),
slist := [ip4_address()]}
ip_pktinfo() =
#{ifindex := integer() >= 0,
spec_dst := ip4_address(),
addr := ip4_address()}
ipv6_mreq() =
#{multiaddr := ip6_address(), interface := integer() >= 0}
ipv6_pmtudisc() = ip_pmtudisc()
ipv6_pktinfo() = #{addr := ip6_address(), ifindex := integer()}
sctp_assoc_id() = int32()
sctp_sndrcvinfo() =
#{stream := uint16(),
ssn := uint16(),
flags := uint16(),
ppid := uint16(),
context := uint16(),
timetolive := uint16(),
tsn := uint16(),
cumtsn := uint16(),
assoc_id := sctp_assoc_id()}
sctp_event_subscribe() =
#{data_in := boolean(),
association := boolean(),
address := boolean(),
send_failure := boolean(),
peer_error := boolean(),
shutdown := boolean(),
partial_delivery := boolean(),
adaptation_layer := boolean(),
authentication := boolean(),
sender_dry := boolean()}
sctp_assocparams() =
#{assoc_id := sctp_assoc_id(),
max_rxt := uint16(),
num_peer_dests := uint16(),
peer_rwnd := uint32(),
local_rwnd := uint32(),
cookie_life := uint32()}
sctp_initmsg() =
#{num_outstreams := uint16(),
max_instreams := uint16(),
max_attempts := uint16(),
max_init_timeo := uint16()}
sctp_rtoinfo() =
#{assoc_id := sctp_assoc_id(),
initial := uint32(),
max := uint32(),
min := uint32()}
msghdr_flag() = ctrunc | eor | errqueue | oob | trunc
msghdr_flags() = [msghdr_flag()]
msghdr() =
#{addr := sockaddr(),
iov := [binary()],
ctrl := [cmsghdr_recv()] | [cmsghdr_send()],
flags := msghdr_flags()}
cmsghdr_level() = socket | ip | ipv6 | integer()
cmsghdr_type() =
credentials | hoplevel | origdstaddr | pktinfo | recvtos |
rights | timestamp | tos | ttl |
integer()
cmsghdr_recv() =
#{level := socket, type := timestamp, data := timeval()} |
#{level := socket, type := rights, data := binary()} |
#{level := socket, type := credentials, data := binary()} |
#{level := socket, type := integer(), data := binary()} |
#{level := ip, type := tos, data := ip_tos()} |
#{level := ip, type := recvtos, data := ip_tos()} |
#{level := ip, type := ttl, data := integer()} |
#{level := ip, type := recvttl, data := integer()} |
#{level := ip, type := pktinfo, data := ip_pktinfo()} |
#{level := ip, type := origdstaddr, data := sockaddr_in4()} |
#{level := ip,
type := recverr,
data := extended_err() | binary()} |
#{level := ip, type := integer(), data := binary()} |
#{level := ipv6, type := hoplevel, data := integer()} |
#{level := ipv6, type := pktinfo, data := ipv6_pktinfo()} |
#{level := ipv6,
type := recverr,
data := extended_err() | binary()} |
#{level := ipv6, type := tclass, data := integer()} |
#{level := ipv6, type := integer(), data := binary()} |
#{level := integer(), type := integer(), data := binary()}
cmsghdr_send() =
#{level := socket, type := timestamp, data := binary()} |
#{level := socket, type := rights, data := binary()} |
#{level := socket, type := credentials, data := binary()} |
#{level := socket, type := integer(), data := binary()} |
#{level := ip, type := tos, data := ip_tos() | binary()} |
#{level := ip, type := ttl, data := integer() | binary()} |
#{level := ip, type := integer(), data := binary()} |
#{level := ipv6, type := tclass, data := integer()} |
#{level := ipv6, type := integer(), data := binary()} |
#{level := udp, type := integer(), data := binary()} |
#{level := integer(), type := integer(), data := binary()}
icmp_dest_unreach() =
net_unreach | host_unreach | port_unreach | frag_needed |
net_unknown | host_unknown |
uint8()
icmpv6_dest_unreach() =
noroute | adm_prohibited | not_neighbour | addr_unreach |
port_unreach | policy_fail | reject_route |
uint8()
ee_origin() = none | local | icmp | icmp6 | uint8()
extended_err() =
#{error := term(),
origin := icmp,
type := dest_unreach,
code := icmp_dest_unreach(),
info := uint32(),
data := uint32(),
offender := undefined | sockaddr()} |
#{error := term(),
origin := icmp,
type := time_exceeded | uint8(),
code := uint8(),
info := uint32(),
data := uint32(),
offender := undefined | sockaddr()} |
#{error := term(),
origin := icmp6,
type := dest_unreach,
code := icmpv6_dest_unreach(),
info := uint32(),
data := uint32(),
offender := undefined | sockaddr()} |
#{error := term(),
origin := icmp6,
type := pkt_toobig | time_exceeded | uint8(),
code := uint8(),
info := uint32(),
data := uint32(),
offender := undefined | sockaddr()} |
#{error := term(),
origin := ee_origin(),
type := uint8(),
code := uint8(),
info := uint32(),
data := uint32(),
offender := undefined | sockaddr()}
uint8() = 0..255
uint16() = 0..65535
uint20() = 0..1048575
uint32() = 0..4294967295
int32() = -2147483648..2147483647
errcode() =
inet:posix() | exalloc | exmonitor | exselect | exself
The POSIX error codes are mostly come from the OS level socket
interface, but this module may generate some appropriate POSIX
codes.
The other values come from this module's lower levels and are
all fairly fatal internal errors:
exalloc:
Memory allocation failed
exmonitor:
Failed to set a monitor on a process
exselect:
Select operation failed
exself:
Failed to get current process
EXPORTS
accept(LSocket) -> {ok, Socket} | {error, Reason}
accept(LSocket, Timeout) -> {ok, Socket} | {error, Reason}
Types:
LSocket = socket()
Timeout = timeout()
Socket = socket()
Reason = errcode() | closed | timeout
Accept a connection on a socket.
This call is used with connection-based socket types (stream or
seqpacket). It extracs the first pending connection request for
the listen socket and returns the (newly) connected socket.
accept(LSocket, Timeout :: nowait) ->
{ok, Socket} | {select, SelectInfo} | {error, Reason}
Types:
LSocket = Socket = socket()
SelectInfo = select_info()
Reason = errcode() | closed
Accept a connection on a socket.
This call is used with connection-based socket types (stream or
seqpacket). It extracs the first pending connection request for
the listen socket and returns the (newly) connected socket.
In the case when there is no connections waiting, the function
will return with the SelectInfo. The caller can then await a se-
lect message, {'$socket', Socket, select, Info} (where Info is
the ref field from the SelectInfo), when a client connects (a
subsequent call to accept will then return the socket).
bind(Socket, Addr) -> {ok, Port} | {error, Reason}
Types:
Socket = socket()
Addr = sockaddr() | any | broadcast | loopback
Port = port_number()
Reason = inet:posix() | closed
Bind a name to a socket.
When a socket is created (with open), it has no address assigned
to it. bind assigns the address specified by the Addr argument.
The rules used for name binding vary between domains.
cancel(Socket, SelectInfo) -> ok | {error, Reason}
Types:
Socket = socket()
SelectInfo = select_info()
Reason = einval | closed | exself
Cancel an asynchronous request.
Call this function in order to cancel a previous asynchronous
call to, e.g. recv/3.
close(Socket) -> ok | {error, Reason}
Types:
Socket = socket()
Reason = errcode() | closed | timeout
Closes the socket.
Note:
Note that for e.g. protocol = tcp, most implementations doing a
close does not guarantee that any data sent is delivered to the
recipient before the close is detected at the remote side.
One way to handle this is to use the shutdown function
(socket:shutdown(Socket, write)) to signal that no more data is
to be sent and then wait for the read side of the socket to be
closed.
connect(Socket, SockAddr) -> ok | {error, Reason}
connect(Socket, SockAddr, Timeout) -> ok | {error, Reason}
Types:
Socket = socket()
SockAddr = sockaddr()
Timeout = timeout()
Reason = errcode() | closed | timeout
This function connects the socket to the address specied by the
SockAddr argument.
connect(Socket, SockAddr, Timeout :: nowait) ->
ok | {select, SelectInfo} | {error, Reason}
Types:
Socket = socket()
SockAddr = sockaddr()
SelectInfo = select_info()
Reason = errcode() | closed
This function connects the socket to the address specied by the
SockAddr argument.
In the case when its not possible to immediately establish a
connection, the function will return with the SelectInfo. The
caller can then await a select message, {'$socket', Socket, se-
lect, Info} (where Info is the ref field from the SelectInfo, a
subsequent call to connect will then establish the connection).
getopt(Socket, Level :: otp, Key :: otp_socket_option()) ->
{ok, Value} | {error, Reason}
getopt(Socket, Level :: socket, Key :: socket_option()) ->
{ok, Value} | {error, Reason}
getopt(Socket, Level :: ip, Key :: ip_socket_option()) ->
{ok, Value} | {error, Reason}
getopt(Socket, Level :: ipv6, Key :: ipv6_socket_option()) ->
{ok, Value} | {error, Reason}
getopt(Socket, Level :: tcp, Key :: tcp_socket_option()) ->
{ok, Value} | {error, Reason}
getopt(Socket, Level :: udp, Key :: udp_socket_option()) ->
{ok, Value} | {error, Reason}
getopt(Socket, Level :: sctp, Key :: sctp_socket_option()) ->
{ok, Value} | {error, Reason}
Types:
Socket = socket()
Value = term()
Reason = inet:posix() | closed
Get an option on a socket.
What properties are valid depend both on Level and on what kind
of socket it is (domain, type and protocol).
See the socket options chapter of the users guide for more info.
Note:
Not all options are valid on all platforms. That is, even if
"we" support an option, that does not mean that the underlying
OS does.
getopt(Socket, Level, Key) -> ok | {ok, Value} | {error, Reason}
Types:
Socket = socket()
Level = integer()
Key = {NativeOpt, ValueSize}
NativeOpt = integer()
ValueSize = int | bool | integer() >= 0
Value = term()
Reason = inet:posix() | closed
Get an option on a socket.
When specifying Level as an integer, and therefor using "native
mode", it is *currently* up to the caller to know how to inter-
pret the result.
For more info, see getopt above.
info(Socket) -> socket_info()
Types:
Socket = socket()
Get miscellaneous info about the socket.
The function returns a map with each info item as a key-value
binding. It reflects the "current" state of the socket.
Note:
In order to ensure data integrity, mutex'es are taken when
needed. So, do not call this function often.
listen(Socket) -> ok | {error, Reason}
listen(Socket, Backlog) -> ok | {error, Reason}
Types:
Socket = socket()
Backlog = integer()
Reason = inet:posix() | closed
Listen for connections on a socket.
number_of() -> integer() >= 0
Returns the number of active sockets.
open(FD) -> {ok, Socket} | {error, Reason}
open(FD, Opts) -> {ok, Socket} | {error, Reason}
Types:
FD = integer()
Opts =
#{domain => domain(),
type => type(),
protocol => protocol(),
dup => boolean()}
Socket = socket()
Reason = errcode()
Create an endpoint (socket) for communication based on an al-
ready existing file descriptor. The function attempts to re-
trieve domain, type and protocol from the system. This is how-
ever not possible on all platforms, and in those cases it ex-
pects it in Opts.
The Opts argument is intended for providing extra information
for the open call:
dup: boolean():
Shall the provided descriptor be duplicated (dup) or not.
Defaults to true.
debug: boolean():
Enable or disable debug during the open call.
Defaults to false.
domain: socket:domain():
Which domain is the descriptor of.
type: socket:type():
Which type is the descriptor of.
protocol: socket:protocol():
Which protocol is the descriptor of.
Note:
This function should be used with care!
On some platforms its necessary to provide the protocol as its
impossible to retrieve it.
open(Domain, Type) -> {ok, Socket} | {error, Reason}
open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
open(Domain, Type, Protocol, Opts) ->
{ok, Socket} | {error, Reason}
Types:
Domain = domain()
Type = type()
Protocol = default | protocol()
Opts = map()
Socket = socket()
Reason = errcode()
Creates an endpoint (socket) for communication.
For some types there is a default protocol, indicated by de-
fault, which it may be possible to specify. And for Domain = lo-
cal, if a protocol is pecified, it must be default.
The Opts argument is intended for "other" options. Currently the
only supported option(s) are netns, which is only supported on
the linux platform and debug (controls debug printouts during
the open call).
Note:
It may not be possible to specify the default protocol (except
when Domain = local). We need to be able to retreive the result-
ing protocol, which is not possble on all platforms.
peername(Socket) -> {ok, SockAddr} | {error, Reason}
Types:
Socket = socket()
SockAddr = sockaddr()
Reason = inet:posix() | closed
Returns the address of the peer connected to the socket.
recv(Socket) -> {ok, Data} | {error, Reason}
recv(Socket, Length) -> {ok, Data} | {error, Reason}
recv(Socket, Length, Flags) -> {ok, Data} | {error, Reason}
recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
recv(Socket, Length, Flags, Timeout) ->
{ok, Data} | {error, Reason}
Types:
Socket = socket()
Length = integer() >= 0
Flags = recv_flags()
Timeout = timeout()
Data = binary()
Reason =
errcode() |
closed | timeout |
{errcode() | closed | timeout, Data :: binary()}
Receive a message from a socket.
There is a special case for the argument Length. If it is set to
zero (0), it means "give me everything you currently have".
recv(Socket, Length, Timeout :: nowait) ->
{ok, Data} |
{ok, {Data, SelectInfo}} |
{select, SelectInfo} |
{error, Reason}
recv(Socket, Length, Flags, Timeout :: nowait) ->
{ok, Data} |
{ok, {Data, SelectInfo}} |
{select, SelectInfo} |
{error, Reason}
Types:
Socket = socket()
Length = integer() >= 0
Flags = recv_flags()
Data = binary()
SelectInfo = select_info()
Reason =
errcode() | closed | {errcode() | closed, Data :: bi-
nary()}
Receive a message from a socket.
There is a special case for the argument Length. If it is set to
zero (0), it means "give me everything you currently have".
In the case when there is no data waiting, the function will re-
turn with the SelectInfo. The caller can then await a select
message, {'$socket', Socket, select, Info} (where Info is the
ref field from the SelectInfo), when data has arrived (a subse-
quent call to recv will then return the data).
Note that if a length (> 0) is specified, and only part of that
amount of data is available, the function will return with that
data and the SelectInfo (if the caller don't want to wait for
the remaining data, it must immediately call the cancel/2 func-
tion.)
recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
recvfrom(Socket, Flags, Timeout) ->
{ok, {Source, Data}} | {error, Reason}
recvfrom(Socket, BufSz, Flags) ->
{ok, {Source, Data}} | {error, Reason}
recvfrom(Socket, BufSz, Timeout) ->
{ok, {Source, Data}} | {error, Reason}
recvfrom(Socket, BufSz, Flags, Timeout) ->
{ok, {Source, Data}} | {error, Reason}
Types:
Socket = socket()
BufSz = integer() >= 0
Flags = recv_flags()
Timeout = timeout()
Source = sockaddr() | undefined
Data = binary()
Reason = errcode() | closed | timeout
Receive a message from a socket.
This function reads "messages", which means that regardless of
how much we want to read, it returns when we get a message (if
the buffer size is too small, the message will be truncated).
The BufSz argument basically defines the size of the receive
buffer. By setting the value to zero (0), the configured size
(setopt with Level = otp and Key = rcvbuf) is used.
It may be impossible to know what (buffer) size is appropriate
"in advance", and in those cases it may be convenient to use the
(recv) 'peek' flag. When this flag is provided, the message is
*not* "consumed" from the underlying buffers, so another
recvfrom call is needed, possibly with a then adjusted buffer
size.
recvfrom(Socket, Flags, Timeout :: nowait) ->
{ok, {Source, Data}} |
{select, SelectInfo} |
{error, Reason}
recvfrom(Socket, BufSz, Timeout :: nowait) ->
{ok, {Source, Data}} |
{select, SelectInfo} |
{error, Reason}
recvfrom(Socket, BufSz, Flags, Timeout :: nowait) ->
{ok, {Source, Data}} |
{select, SelectInfo} |
{error, Reason}
Types:
Socket = socket()
BufSz = integer() >= 0
Flags = recv_flags()
Source = sockaddr() | undefined
Data = binary()
SelectInfo = select_info()
Reason = errcode() | closed
Receive a message from a socket.
This function reads "messages", which means that regardless of
how much we want to read, it returns when we get a message (if
the buffer size is too small, the message will be truncated).
The BufSz argument basically defines the size of the receive
buffer. By setting the value to zero (0), the configured size
(setopt with Level = otp and Key = rcvbuf) is used.
It may be impossible to know what (buffer) size is appropriate
"in advance", and in those cases it may be convenient to use the
(recv) 'peek' flag. When this flag is provided, the message is
*not* "consumed" from the underlying buffers, so another
recvfrom call is needed, possibly with a then adjusted buffer
size.
In the case when there is no data waiting, the function will re-
turn with the SelectInfo. The caller can then await a select
message, {'$socket', Socket, select, Info} (where Info is the
ref field from the SelectInfo), when data has arrived (a subse-
quent call to recvfrom will then return the data).
recvmsg(Socket) -> {ok, MsgHdr} | {error, Reason}
recvmsg(Socket, Flags) -> {ok, MsgHdr} | {error, Reason}
recvmsg(Socket, Timeout) -> {ok, MsgHdr} | {error, Reason}
recvmsg(Socket, Flags, Timeout) -> {ok, MsgHdr} | {error, Reason}
recvmsg(Socket, BufSz, CtrlSz) -> {ok, MsgHdr} | {error, Reason}
recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout) ->
{ok, MsgHdr} | {error, Reason}
Types:
Socket = socket()
BufSz = CtrlSz = integer() >= 0
Flags = recv_flags()
Timeout = timeout()
MsgHdr = msghdr()
Reason = errcode() | closed | timeout
Receive a message from a socket.
This function reads "messages", which means that regardless of
how much we want to read, it returns when we get a message.
The message will be delivered in the form of a msghdr(), which
may contain the source address (if socket not connected), a list
of cmsghdr_recv() (depends on what socket options have been set
and what the protocol and platform supports) and also a set of
flags, providing further info about the read.
The BufSz argument basically defines the size of the receive
buffer. By setting the value to zero (0), the configured size
(setopt with Level = otp and Key = rcvbuf) is used.
The CtrlSz argument basically defines the size of the receive
buffer for the control messages. By setting the value to zero
(0), the configured size (setopt with Level = otp) is used.
It may be impossible to know what (buffer) size is appropriate
"in advance", and in those cases it may be convenient to use the
(recv) 'peek' flag. When this flag is provided, the message is
*not* "consumed" from the underlying buffers, so another recvmsg
call is needed, possibly with a then adjusted buffer size.
recvmsg(Socket, Timeout :: nowait) ->
{ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
recvmsg(Socket, Flags, Timeout :: nowait) ->
{ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: nowait) ->
{ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
Types:
Socket = socket()
BufSz = CtrlSz = integer() >= 0
Flags = recv_flags()
MsgHdr = msghdr()
SelectInfo = select_info()
Reason = errcode() | closed
Receive a message from a socket.
This function reads "messages", which means that regardless of
how much we want to read, it returns when we get a message.
The message will be delivered in the form of a msghdr(), which
may contain the source address (if socket not connected), a list
of cmsghdr_recv() (depends on what socket options have been set
and what the protocol and platform supports) and also a set of
flags, providing further info about the read.
The BufSz argument basically defines the size of the receive
buffer. By setting the value to zero (0), the configured size
(setopt with Level = otp and Key = rcvbuf) is used.
The CtrlSz argument basically defines the size of the receive
buffer for the control messages. By setting the value to zero
(0), the configured size (setopt with Level = otp) is used.
It may be impossible to know what (buffer) size is appropriate
"in advance", and in those cases it may be convenient to use the
(recv) 'peek' flag. When this flag is provided, the message is
*not* "consumed" from the underlying buffers, so another recvmsg
call is needed, possibly with a then adjusted buffer size.
In the case when there is no data waiting, the function will re-
turn with the SelectInfo. The caller can then await a select
message, {'$socket', Socket, select, Info} (where Info is the
ref field from the SelectInfo), when data has arrived (a subse-
quent call to recvmsg will then return the data).
send(Socket, Data) -> ok | {error, Reason}
send(Socket, Data, Flags) -> ok | {error, Reason}
send(Socket, Data, Timeout) -> ok | {error, Reason}
send(Socket, Data, Flags, Timeout) -> ok | {error, Reason}
Types:
Socket = socket()
Data = iodata()
Flags = send_flags()
Timeout = timeout()
Reason =
{errcode() | closed | timeout, Remaining :: integer() >=
1}
Send a message on a connected socket.
send(Socket, Data, Timeout :: nowait) ->
ok |
{ok, {binary(), SelectInfo}} |
{select, SelectInfo} |
{ok, {RestData, SelectInfo}} |
{error, Reason}
send(Socket, Data, Flags, Timeout :: nowait) ->
ok |
{select, SelectInfo} |
{ok, {RestData, SelectInfo}} |
{error, Reason}
Types:
Socket = socket()
Data = iodata()
Flags = send_flags()
RestData = binary()
SelectInfo = select_info()
Reason = {errcode() | closed, Remaining :: integer() >= 1}
Send a message on a connected socket.
In the case when there is no room in the (system-) buffers, the
function will return with the SelectInfo. The caller can then
await a select message, {'$socket', Socket, select, Info} (where
Info is the ref field from the SelectInfo), when there is room
for more data (a subsequent call to send will then send the
data).
Note that if not all the data was sent, the function will return
with the remaining data and the SelectInfo (if the caller don't
want to wait to be able to send the rest, it should immediately
call the cancel/2 function.)
sendmsg(Socket, MsgHdr) -> ok | {ok, Remaining} | {error, Reason}
sendmsg(Socket, MsgHdr, Flags) -> ok | {error, Reason}
sendmsg(Socket, MsgHdr, Timeout) -> ok | {error, Reason}
sendmsg(Socket, MsgHdr, Flags, Timeout) ->
ok | {ok, Remaining} | {error, Reason}
Types:
Socket = socket()
MsgHdr = msghdr()
Flags = send_flags()
Timeout = timeout()
Remaining = erlang:iovec()
Reason = errcode() | closed | timeout
Send a message on a socket. The destination, if needed (socket
not connected) is provided in the MsgHdr, which also contains
the message to send, The MsgHdr may also contain an list of op-
tional cmsghdr_send() (depends on what the protocol and platform
supports).
Unlike the send function, this one sends one message. This means
that if, for whatever reason, its not possible to send the mes-
sage in one go, the function will instead return with the re-
maining data ({ok, Remaining}). Thereby leaving it up to the
caller to decide what to do (retry with the remaining data of
give up).
sendmsg(Socket, MsgHdr, Timeout :: nowait) ->
ok | {ok, Remaining} | {error, Reason}
sendmsg(Socket, MsgHdr, Flags, Timeout :: nowait) ->
ok | {ok, Remaining} | {error, Reason}
Types:
Socket = socket()
MsgHdr = msghdr()
Flags = send_flags()
Remaining = erlang:iovec()
Reason = errcode() | closed
Send a message on a socket. The destination, if needed (socket
not connected) is provided in the MsgHdr, which also contains
the message to send, The MsgHdr may also contain an list of op-
tional cmsghdr_send() (depends on what the protocol and platform
supports).
Unlike the send function, this one sends one message. This means
that if, for whatever reason, its not possible to send the mes-
sage in one go, the function will instead return with the re-
maining data ({ok, Remaining}). Thereby leaving it up to the
caller to decide what to do (retry with the remaining data of
give up).
In the case when there is no room in the (system-) buffers, the
function will return with the SelectInfo. The caller can then
await a select message, {'$socket', Socket, select, Info} (where
Info is the ref field from the SelectInfo), when there is room
for more data (a subsequent call to sendmsg will then send the
data).
sendto(Socket, Data, Dest) -> ok | {error, Reason}
sendto(Socket, Data, Dest, Flags) -> ok | {error, Reason}
sendto(Socket, Data, Dest, Timeout) -> ok | {error, Reason}
sendto(Socket, Data, Dest, Flags, Timeout) -> ok | {error, Reason}
Types:
Socket = socket()
Data = binary()
Dest = sockaddr()
Flags = send_flags()
Timeout = timeout()
Reason =
{errcode() | closed | timeout, Remaining :: integer() >=
1}
Send a message on a socket, to the specified destination.
sendto(Socket, Data, Dest, Timeout :: nowait) ->
ok | {select, SelectInfo} | {error, Reason}
sendto(Socket, Data, Dest, Flags, Timeout :: nowait) ->
ok |
{ok, {binary(), SelectInfo}} |
{select, SelectInfo} |
{error, Reason}
Types:
Socket = socket()
Data = binary()
Dest = sockaddr()
Flags = send_flags()
SelectInfo = select_info()
Reason = {errcode() | closed, Remaining :: integer() >= 1}
Send a message on a socket, to the specified destination.
In the case when there is no room in the (system-) buffers, the
function will return with the SelectInfo. The caller can then
await a select message, {'$socket', Socket, select, Info} (where
Info is the ref field from the SelectInfo), when there is room
for more data (a subsequent call to sendto will then send the
data).
setopt(Socket, Level :: otp, Key :: otp_socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level :: socket, Key :: socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level :: ip, Key :: ip_socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level :: ipv6, Key :: ipv6_socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level :: tcp, Key :: tcp_socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level :: udp, Key :: udp_socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level :: sctp, Key :: sctp_socket_option(), Value) ->
ok | {error, Reason}
setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
Types:
Socket = socket()
Level = Key = integer() >= 0
Value = binary()
Reason = inet:posix() | closed
Set an option on a socket.
What options are valid depend both on Level and on what kind of
socket it is (domain, type and protocol).
See the socket options chapter of the users guide for more info.
Note:
Not all options are valid on all platforms. That is, even if
"we" support an option, that does not mean that the underlying
OS does.
Note:
Sockets are set 'non-blocking' when created, so this option is
*not* available (as it would adversely effect the Erlang VM to
set a socket 'blocking').
setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
Types:
Socket = socket()
Level = Key = integer() >= 0
Value = binary()
Reason = inet:posix() | closed
Set options on a socket.
When specifying Level as an integer, and therefor using "native
mode", it is *currently* up to the caller to know how to encode
the Value.
For more info, see setopt above.
shutdown(Socket, How) -> ok | {error, Reason}
Types:
Socket = socket()
How = shutdown_how()
Reason = inet:posix() | closed
Shut down all or part of a full-duplex connection.
sockname(Socket) -> {ok, SockAddr} | {error, Reason}
Types:
Socket = socket()
SockAddr = sockaddr()
Reason = inet:posix() | closed
Returns the current address to which the socket is bound.
supports() -> Supports
supports(Key1 :: options) -> SupportsOptions
supports(Key1 :: send_flags) -> SupportsSendFlags
supports(Key1 :: recv_flags) -> SupportsRecvFlags
supports(Key1 :: options, Key2 :: socket) -> SupportsOptionsSocket
supports(Key1 :: options, Key2 :: ip) -> SupportsOptionsIP
supports(Key1 :: options, Key2 :: ipv6) -> SupportsOptionsIPv6
supports(Key1 :: options, Key2 :: tcp) -> SupportsOptionsTCP
supports(Key1 :: options, Key2 :: udp) -> SupportsOptionsUDP
supports(Key1 :: options, Key2 :: sctp) -> SupportsOptionsSCTP
Types:
Supports :: [{Feature, boolean()} | {send_flags, Support-
sSendFlags} | {recv_flags, SupportsRecvFlags} | {options,
SupportsOptions}]
Feature :: sctp | ipv6 | local | netns
SupportsSendFlags :: [{send_flag(), boolean()}]
SupportsRecvFlags :: [{recv_flag(), boolean()}]
SupportsOptions :: [{socket, SupportsOptionsSocket} | {ip,
SupportsOptionsIP} | {ipv6, SupportsOptionsIPv6} | {tcp, Sup-
portsOptionsTCP} | {udp, SupportsOptionsUDP} | {sctp, Sup-
portsOptionsSCTP}]
SupportsOptionsSocket :: [{socket_option(), boolean()}]
SupportsOptionsIP :: [{ip_socket_option(), boolean()}]
SupportsOptionsIPv6 :: [{ipv6_socket_option(), boolean()}]
SupportsOptionsTCP :: [{tcp_socket_option(), boolean()}]
SupportsOptionsUDP :: [{udp_socket_option(), boolean()}]
SupportsOptionsSCTP :: [{sctp_socket_option(), boolean()}]
This function retreives information about what the platform sup-
ports, such as if SCTP is supported, or which socket options are
supported.
For keys other than the known the empty list is returned, Note
that in a future version or on a different platform there might
be more supported items.
is_supported(Key1 :: sctp | ipv6 | local | netns) -> boolean()
is_supported(Key1 :: send_flags, Key2 :: SendFlag) -> boolean()
is_supported(Key1 :: recv_flags, Key2 :: RecvFlag) -> boolean()
is_supported(Key1 :: options, Key2 :: socket, Key3 :: SocketOption) ->
boolean()
is_supported(Key1 :: options, Key2 :: ip, Key3 :: IPSocketOption) ->
boolean()
is_supported(Key1 :: options, Key2 :: ipv6, Key3 :: IPv6SocketOption)
-> boolean()
is_supported(Key1 :: options, Key2 :: tcp, Key3 :: TCPSocketOption) ->
boolean()
is_supported(Key1 :: options, Key2 :: udp, Key3 :: UDPSocketOption) ->
boolean()
is_supported(Key1 :: options, Key2 :: sctp, Key3 :: SCTPSocketOption)
-> boolean()
Types:
SocketOption :: socket_option()
IPSocketOption :: ip_socket_option()
IPv6SocketOption :: ipv6_socket_option()
TCPSocketOption :: tcp_socket_option()
UDPSocketOption :: udp_socket_option()
SCTPSocketOption :: sctp_socket_option()
This function retreives information about what the platform sup-
ports, such as if SCTP is supported, or which socket options are
supported.
For keys other than the known false is returned. Note that in a
future version or on a different platform there might be more
supported items.
which_sockets() -> [socket()]
which_sockets(FilterRule) -> [socket()]
Types:
FilterRule =
inet | inet6 | stream | dgram | seqpacket | sctp | tcp |
udp |
pid() |
fun((socket_info()) -> boolean())
Returns a list of all sockets, according to the filter rule.
There are several pre-made filter rule(s) and one general:
inet | inet6:
Selection based on the domain of the socket.
Only a subset is valid.
stream | dgram | seqpacket:
Selection based on the type of the socket.
Only a subset is valid.
sctp | tcp | udp:
Selection based on the protocol of the socket.
Only a subset is valid.
pid():
Selection base on which sockets has this pid as Controlling
Process.
fun((socket_info()) -> boolean()):
The general filter rule.
A fun that takes the socket info and returns a boolean()
(true if the socket sould be included and false if should
not).
EXAMPLES
client(Addr, SAddr, SPort) ->
{ok, Sock} = socket:open(inet, stream, tcp),
{ok, _} = socket:bind(Sock, #{family => inet,
addr => Addr}),
ok = socket:connect(Sock, #{family => inet,
addr => SAddr,
port => SPort}),
Msg = list_to_binary("hello"),
ok = socket:send(Sock, Msg),
ok = socket:shutdown(Sock, write),
{ok, Msg} = socket:recv(Sock),
ok = socket:close(Sock).
server(Addr, Port) ->
{ok, LSock} = socket:open(inet, stream, tcp),
{ok, _} = socket:bind(LSock, #{family => inet,
port => Port,
addr => Addr}),
ok = socket:listen(LSock),
{ok, Sock} = socket:accept(LSock),
{ok, Msg} = socket:recv(Sock),
ok = socket:send(Sock, Msg),
ok = socket:shutdown(Sock, write),
ok = socket:close(Sock),
ok = socket:close(LSock).
Ericsson AB kernel 7.0 socket(3erl)