1socket(3) Erlang Module Definition socket(3)
2
6 socket - Socket interface.
7
9 This module provides an API for network socket. Functions are provided
10 to create, delete and manupilate the sockets aswell as sending and
11 reciving data on them.
12 The intent is that it shall be as "close as possible" to the OS level
14 socket interface. The only significant addition is that some of the
15 functions, e.g. recv/3, has a timeout argument.
16 Note:
18 Some functions allow for an asynchronous call. This is achieved by
19 setting the Timeout argument to nowait. For instance, if calling the
20 recv/3 function with Timeout set to nowait (recv(Sock, 0, nowait)) when
21 there is actually nothing to read, it will return with {select,
22 SelectInfo} (SelectInfo contains the SelectRef). When data eventually
23 arrives a 'select' message will be sent to the caller:
24 : {'$socket', socket(), select, SelectRef}
26 The caller can now make another call to the recv function and now
28 expect data.
29 Note that all other users are locked out until the 'current user' has
31 called the function (recv in this case).
32 Another message the user must be prepared for (when making asynchronous
34 calls) is the abort message:
35 : {'$socket', socket(), abort, Info}
37 This message indicates that the (asynchronous) operation has been
39 aborted. If, for instance, the socket has been closed (by another
40 process), Info will be {SelectRef, closed}.
41 Note:
44 There is currently no support for Windows.
45 Support for IPv6 has been implemented but not tested.
47 SCTP has only been partly implemented (and not tested).
49
52 domain() = local | inet | inet6
53 type() = stream | dgram | raw | rdm | seqpacket
55 protocol() =
57 ip | tcp | udp | sctp | icmp | igmp | {raw, integer()}
58 socket()
60 As returned by open/1,2,3,4 and accept/1,2.
62 select_tag()
64 A tag that describes the (select) operation.
66 select_ref()
68 A reference that uniquely identifies the (select) operation.
70 select_info() = {select_info, select_tag(), select_ref()}
72 socket_counters() =
74 #{read_byte := integer() >= 0,
75 read_fails := integer() >= 0,
76 read_pkg := integer() >= 0,
77 read_pkg_max := integer() >= 0,
78 read_tries := integer() >= 0,
79 read_waits := integer() >= 0,
80 write_byte := integer() >= 0,
81 write_fails := integer() >= 0,
82 write_pkg := integer() >= 0,
83 write_pkg_max := integer() >= 0,
84 write_tries := integer() >= 0,
85 write_waits := integer() >= 0,
86 acc_success := integer() >= 0,
87 acc_fails := integer() >= 0,
88 acc_tries := integer() >= 0,
89 acc_waits := integer() >= 0}
90 socket_info() =
92 #{domain := domain(),
93 type := type(),
94 protocol := protocol(),
95 ctrl := pid(),
96 ctype := normal | fromfd | {fromfd, integer()},
97 counters := socket_counters(),
98 num_readers := integer() >= 0,
99 num_writers := integer() >= 0,
100 num_acceptors := integer() >= 0,
101 writable := boolean(),
102 readable := boolean()}
103 ip4_address() = {0..255, 0..255, 0..255, 0..255}
105 ip6_address() =
107 {0..65535,
108 0..65535,
109 0..65535,
110 0..65535,
111 0..65535,
112 0..65535,
113 0..65535,
114 0..65535}
115 sockaddr() =
117 sockaddr_in4() |
118 sockaddr_in6() |
119 sockaddr_un() |
120 sockaddr_ll()
121 sockaddr_in4() =
123 #{family := inet,
124 port := port_number(),
125 addr := any | broadcast | loopback | ip4_address()}
126 sockaddr_in6() =
128 #{family := inet6,
129 port := port_number(),
130 addr := any | loopback | ip6_address(),
131 flowinfo := in6_flow_info(),
132 scope_id := in6_scope_id()}
133 sockaddr_un() = #{family := local, path := binary() | string()}
135 sockaddr_ll() =
137 #{family := packet,
138 protocol := integer() >= 0,
139 ifindex := integer(),
140 pkttype := packet_type(),
141 hatype := integer() >= 0,
142 addr := binary()}
143 packet_type() =
145 host | broadcast | multicast | otherhost | outgoing |
146 loopback | user | kernel | fastroute |
147 integer() >= 0
148 port_number() = 0..65535
150 in6_flow_info() = uint20()
152 in6_scope_id() = uint32()
154 send_flags() = [send_flag()]
156 send_flag() = confirm | dontroute | eor | more | nosignal | oob
158 recv_flags() = [recv_flag()]
160 recv_flag() = cmsg_cloexec | errqueue | oob | peek | trunc
162 shutdown_how() = read | write | read_write
164 sockopt_level() =
166 otp | socket | ip | ipv6 | tcp | udp | sctp |
167 integer() >= 0
168 otp_socket_option() =
170 debug | use_registry | iow | controlling_process | rcvbuf |
171 rcvctrlbuf | sndctrlbuf | meta | fd
172 socket_option() =
174 acceptconn | acceptfilter | bindtodevice | broadcast |
175 busy_poll | debug | domain | dontroute | error | keepalive |
176 linger | mark | oobinline | passcred | peek_off | peercred |
177 priority | protocol | rcvbuf | rcvbufforce | rcvlowat |
178 rcvtimeo | reuseaddr | reuseport | rxq_ovfl | setfib |
179 sndbuf | sndbufforce | sndlowat | sndtimeo | timestamp | type
180 ip_socket_option() =
182 add_membership | add_source_membership | block_source |
183 dontfrag | drop_membership | drop_source_membership |
184 freebind | hdrincl | minttl | msfilter | mtu | mtu_discover |
185 multicast_all | multicast_if | multicast_loop |
186 multicast_ttl | nodefrag | options | pktinfo | recverr |
187 recvif | recvdstaddr | recvopts | recvorigdstaddr | recvtos |
188 recvttl | retopts | router_alert | sndsrcaddr | tos |
189 transparent | ttl | unblock_source
190 ipv6_socket_option() =
192 addrform | add_membership | authhdr | auth_level | checksum |
193 drop_membership | dstopts | esp_trans_level |
194 esp_network_level | faith | flowinfo | hopopts |
195 ipcomp_level | join_group | leave_group | mtu | mtu_discover |
196 multicast_hops | multicast_if | multicast_loop | portrange |
197 pktoptions | recverr | recvhoplimit | hoplimit | recvpktinfo |
198 pktinfo | recvtclass | router_alert | rthdr | tclass |
199 unicast_hops | use_min_mtu | v6only
200 tcp_socket_option() =
202 congestion | cork | info | keepcnt | keepidle | keepintvl |
203 maxseg | md5sig | nodelay | noopt | nopush | syncnt |
204 user_timeout
205 udp_socket_option() = cork
207 sctp_socket_option() =
209 adaption_layer | associnfo | auth_active_key | auth_asconf |
210 auth_chunk | auth_key | auth_delete_key | autoclose |
211 context | default_send_params | delayed_ack_time |
212 disable_fragments | hmac_ident | events | explicit_eor |
213 fragment_interleave | get_peer_addr_info | initmsg |
214 i_want_mapped_v4_addr | local_auth_chunks | maxseg |
215 maxburst | nodelay | partial_delivery_point |
216 peer_addr_params | peer_auth_chunks | primary_addr |
217 reset_streams | rtoinfo | set_peer_primary_addr | status |
218 use_ext_recvinfo
219 timeval() = #{sec := integer(), usec := integer()}
221 ip_tos() =
223 lowdelay | throughput | reliability | mincost | integer()
224 ip_mreq() =
226 #{multiaddr := ip4_address(),
227 interface := any | ip4_address()}
228 ip_mreq_source() =
230 #{multiaddr := ip4_address(),
231 interface := ip4_address(),
232 sourceaddr := ip4_address()}
233 ip_pmtudisc() = want | dont | do | probe
235 ip_msfilter_mode() = include | exclude
237 ip_msfilter() =
239 #{multiaddr := ip4_address(),
240 interface := ip4_address(),
241 mode := ip_msfilter_mode(),
242 slist := [ip4_address()]}
243 ip_pktinfo() =
245 #{ifindex := integer() >= 0,
246 spec_dst := ip4_address(),
247 addr := ip4_address()}
248 ipv6_mreq() =
250 #{multiaddr := ip6_address(), interface := integer() >= 0}
251 ipv6_pmtudisc() = ip_pmtudisc()
253 ipv6_pktinfo() = #{addr := ip6_address(), ifindex := integer()}
255 sctp_assoc_id() = int32()
257 sctp_sndrcvinfo() =
259 #{stream := uint16(),
260 ssn := uint16(),
261 flags := uint16(),
262 ppid := uint16(),
263 context := uint16(),
264 timetolive := uint16(),
265 tsn := uint16(),
266 cumtsn := uint16(),
267 assoc_id := sctp_assoc_id()}
268 sctp_event_subscribe() =
270 #{data_in := boolean(),
271 association := boolean(),
272 address := boolean(),
273 send_failure := boolean(),
274 peer_error := boolean(),
275 shutdown := boolean(),
276 partial_delivery := boolean(),
277 adaptation_layer := boolean(),
278 authentication := boolean(),
279 sender_dry := boolean()}
280 sctp_assocparams() =
282 #{assoc_id := sctp_assoc_id(),
283 max_rxt := uint16(),
284 num_peer_dests := uint16(),
285 peer_rwnd := uint32(),
286 local_rwnd := uint32(),
287 cookie_life := uint32()}
288 sctp_initmsg() =
290 #{num_outstreams := uint16(),
291 max_instreams := uint16(),
292 max_attempts := uint16(),
293 max_init_timeo := uint16()}
294 sctp_rtoinfo() =
296 #{assoc_id := sctp_assoc_id(),
297 initial := uint32(),
298 max := uint32(),
299 min := uint32()}
300 msghdr_flag() = ctrunc | eor | errqueue | oob | trunc
302 msghdr_flags() = [msghdr_flag()]
304 msghdr() =
306 #{addr := sockaddr(),
307 iov := [binary()],
308 ctrl := [cmsghdr_recv()] | [cmsghdr_send()],
309 flags := msghdr_flags()}
310 cmsghdr_level() = socket | ip | ipv6 | integer()
312 cmsghdr_type() =
314 credentials | hoplevel | origdstaddr | pktinfo | recvtos |
315 rights | timestamp | tos | ttl |
316 integer()
317 cmsghdr_recv() =
319 #{level := socket, type := timestamp, data := timeval()} |
320 #{level := socket, type := rights, data := binary()} |
321 #{level := socket, type := credentials, data := binary()} |
322 #{level := socket, type := integer(), data := binary()} |
323 #{level := ip, type := tos, data := ip_tos()} |
324 #{level := ip, type := recvtos, data := ip_tos()} |
325 #{level := ip, type := ttl, data := integer()} |
326 #{level := ip, type := recvttl, data := integer()} |
327 #{level := ip, type := pktinfo, data := ip_pktinfo()} |
328 #{level := ip, type := origdstaddr, data := sockaddr_in4()} |
329 #{level := ip,
330 type := recverr,
331 data := extended_err() | binary()} |
332 #{level := ip, type := integer(), data := binary()} |
333 #{level := ipv6, type := hoplevel, data := integer()} |
334 #{level := ipv6, type := pktinfo, data := ipv6_pktinfo()} |
335 #{level := ipv6,
336 type := recverr,
337 data := extended_err() | binary()} |
338 #{level := ipv6, type := tclass, data := integer()} |
339 #{level := ipv6, type := integer(), data := binary()} |
340 #{level := integer(), type := integer(), data := binary()}
341 cmsghdr_send() =
343 #{level := socket, type := timestamp, data := binary()} |
344 #{level := socket, type := rights, data := binary()} |
345 #{level := socket, type := credentials, data := binary()} |
346 #{level := socket, type := integer(), data := binary()} |
347 #{level := ip, type := tos, data := ip_tos() | binary()} |
348 #{level := ip, type := ttl, data := integer() | binary()} |
349 #{level := ip, type := integer(), data := binary()} |
350 #{level := ipv6, type := tclass, data := integer()} |
351 #{level := ipv6, type := integer(), data := binary()} |
352 #{level := udp, type := integer(), data := binary()} |
353 #{level := integer(), type := integer(), data := binary()}
354 icmp_dest_unreach() =
356 net_unreach | host_unreach | port_unreach | frag_needed |
357 net_unknown | host_unknown |
358 uint8()
359 icmpv6_dest_unreach() =
361 noroute | adm_prohibited | not_neighbour | addr_unreach |
362 port_unreach | policy_fail | reject_route |
363 uint8()
364 ee_origin() = none | local | icmp | icmp6 | uint8()
366 extended_err() =
368 #{error := term(),
369 origin := icmp,
370 type := dest_unreach,
371 code := icmp_dest_unreach(),
372 info := uint32(),
373 data := uint32(),
374 offender := undefined | sockaddr()} |
375 #{error := term(),
376 origin := icmp,
377 type := time_exceeded | uint8(),
378 code := uint8(),
379 info := uint32(),
380 data := uint32(),
381 offender := undefined | sockaddr()} |
382 #{error := term(),
383 origin := icmp6,
384 type := dest_unreach,
385 code := icmpv6_dest_unreach(),
386 info := uint32(),
387 data := uint32(),
388 offender := undefined | sockaddr()} |
389 #{error := term(),
390 origin := icmp6,
391 type := pkt_toobig | time_exceeded | uint8(),
392 code := uint8(),
393 info := uint32(),
394 data := uint32(),
395 offender := undefined | sockaddr()} |
396 #{error := term(),
397 origin := ee_origin(),
398 type := uint8(),
399 code := uint8(),
400 info := uint32(),
401 data := uint32(),
402 offender := undefined | sockaddr()}
403 uint8() = 0..255
405 uint16() = 0..65535
407 uint20() = 0..1048575
409 uint32() = 0..4294967295
411 int32() = -2147483648..2147483647
413 errcode() =
415 inet:posix() | exalloc | exmonitor | exselect | exself
416 The POSIX error codes are mostly come from the OS level socket
418 interface, but this module may generate some appropriate POSIX
419 codes.
420 The other values come from this module's lower levels and are
422 all fairly fatal internal errors:
423 exalloc:
425 Memory allocation failed
426 exmonitor:
428 Failed to set a monitor on a process
429 exselect:
431 Select operation failed
432 exself:
434 Failed to get current process
435
437 accept(LSocket) -> {ok, Socket} | {error, Reason}
438 accept(LSocket, Timeout) -> {ok, Socket} | {error, Reason}
440 Types:
442 LSocket = socket()
444 Timeout = timeout()
445 Socket = socket()
446 Reason = errcode() | closed | timeout
447 Accept a connection on a socket.
449 This call is used with connection-based socket types (stream or
451 seqpacket). It extracs the first pending connection request for
452 the listen socket and returns the (newly) connected socket.
453 accept(LSocket, Timeout :: nowait) ->
455 {ok, Socket} | {select, SelectInfo} | {error, Reason}
456 Types:
458 LSocket = Socket = socket()
460 SelectInfo = select_info()
461 Reason = errcode() | closed
462 Accept a connection on a socket.
464 This call is used with connection-based socket types (stream or
466 seqpacket). It extracs the first pending connection request for
467 the listen socket and returns the (newly) connected socket.
468 In the case when there is no connections waiting, the function
470 will return with the SelectInfo. The caller can then await a
471 select message, {'$socket', Socket, select, Info} (where Info is
472 the ref field from the SelectInfo), when a client connects (a
473 subsequent call to accept will then return the socket).
474 bind(Socket, Addr) -> {ok, Port} | {error, Reason}
476 Types:
478 Socket = socket()
480 Addr = sockaddr() | any | broadcast | loopback
481 Port = port_number()
482 Reason = inet:posix() | closed
483 Bind a name to a socket.
485 When a socket is created (with open), it has no address assigned
487 to it. bind assigns the address specified by the Addr argument.
488 The rules used for name binding vary between domains.
490 cancel(Socket, SelectInfo) -> ok | {error, Reason}
492 Types:
494 Socket = socket()
496 SelectInfo = select_info()
497 Reason = einval | closed | exself
498 Cancel an asynchronous request.
500 Call this function in order to cancel a previous asynchronous
502 call to, e.g. recv/3.
503 close(Socket) -> ok | {error, Reason}
505 Types:
507 Socket = socket()
509 Reason = errcode() | closed | timeout
510 Closes the socket.
512 Note:
514 Note that for e.g. protocol = tcp, most implementations doing a
515 close does not guarantee that any data sent is delivered to the
516 recipient before the close is detected at the remote side.
517 One way to handle this is to use the shutdown function
519 (socket:shutdown(Socket, write)) to signal that no more data is
520 to be sent and then wait for the read side of the socket to be
521 closed.
522 connect(Socket, SockAddr) -> ok | {error, Reason}
525 connect(Socket, SockAddr, Timeout) -> ok | {error, Reason}
527 Types:
529 Socket = socket()
531 SockAddr = sockaddr()
532 Timeout = timeout()
533 Reason = errcode() | closed | timeout
534 This function connects the socket to the address specied by the
536 SockAddr argument.
537 connect(Socket, SockAddr, Timeout :: nowait) ->
539 ok | {select, SelectInfo} | {error, Reason}
540 Types:
542 Socket = socket()
544 SockAddr = sockaddr()
545 SelectInfo = select_info()
546 Reason = errcode() | closed
547 This function connects the socket to the address specied by the
549 SockAddr argument.
550 In the case when its not possible to immediately establish a
552 connection, the function will return with the SelectInfo. The
553 caller can then await a select message, {'$socket', Socket,
554 select, Info} (where Info is the ref field from the SelectInfo,
555 a subsequent call to connect will then establish the connec‐
556 tion).
557 getopt(Socket, Level :: otp, Key :: otp_socket_option()) ->
559 {ok, Value} | {error, Reason}
560 getopt(Socket, Level :: socket, Key :: socket_option()) ->
562 {ok, Value} | {error, Reason}
563 getopt(Socket, Level :: ip, Key :: ip_socket_option()) ->
565 {ok, Value} | {error, Reason}
566 getopt(Socket, Level :: ipv6, Key :: ipv6_socket_option()) ->
568 {ok, Value} | {error, Reason}
569 getopt(Socket, Level :: tcp, Key :: tcp_socket_option()) ->
571 {ok, Value} | {error, Reason}
572 getopt(Socket, Level :: udp, Key :: udp_socket_option()) ->
574 {ok, Value} | {error, Reason}
575 getopt(Socket, Level :: sctp, Key :: sctp_socket_option()) ->
577 {ok, Value} | {error, Reason}
578 Types:
580 Socket = socket()
582 Value = term()
583 Reason = inet:posix() | closed
584 Get an option on a socket.
586 What properties are valid depend both on Level and on what kind
588 of socket it is (domain, type and protocol).
589 See the socket options chapter of the users guide for more info.
591 Note:
593 Not all options are valid on all platforms. That is, even if
594 "we" support an option, that does not mean that the underlying
595 OS does.
596 getopt(Socket, Level, Key) -> ok | {ok, Value} | {error, Reason}
599 Types:
601 Socket = socket()
603 Level = integer()
604 Key = {NativeOpt, ValueSize}
605 NativeOpt = integer()
606 ValueSize = int | bool | integer() >= 0
607 Value = term()
608 Reason = inet:posix() | closed
609 Get an option on a socket.
611 When specifying Level as an integer, and therefor using "native
613 mode", it is *currently* up to the caller to know how to inter‐
614 pret the result.
615 For more info, see getopt above.
617 info(Socket) -> socket_info()
619 Types:
621 Socket = socket()
623 Get miscellaneous info about the socket.
625 The function returns a map with each info item as a key-value
627 binding. It reflects the "current" state of the socket.
628 Note:
630 In order to ensure data integrity, mutex'es are taken when
631 needed. So, do not call this function often.
632 listen(Socket) -> ok | {error, Reason}
635 listen(Socket, Backlog) -> ok | {error, Reason}
637 Types:
639 Socket = socket()
641 Backlog = integer()
642 Reason = inet:posix() | closed
643 Listen for connections on a socket.
645 number_of() -> integer() >= 0
647 Returns the number of active sockets.
649 open(FD) -> {ok, Socket} | {error, Reason}
651 open(FD, Opts) -> {ok, Socket} | {error, Reason}
653 Types:
655 FD = integer()
657 Opts =
658 #{domain => domain(),
659 type => type(),
660 protocol => protocol(),
661 dup => boolean(),
662 debug => boolean(),
663 use_registry => boolean()}
664 Socket = socket()
665 Reason = errcode()
666 Create an endpoint (socket) for communication based on an
668 already existing file descriptor. The function attempts to
669 retrieve domain, type and protocol from the system. This is how‐
670 ever not possible on all platforms, and in those cases it
671 expects it in Opts.
672 The Opts argument is intended for providing extra information
674 for the open call:
675 dup: boolean():
677 Shall the provided descriptor be duplicated (dup) or not.
678 Defaults to true.
679 debug: boolean():
681 Enable or disable debug during the open call.
682 Defaults to false.
683 domain: socket:domain():
685 Which domain is the descriptor of.
686 type: socket:type():
688 Which type is the descriptor of.
689 protocol: socket:protocol():
691 Which protocol is the descriptor of.
692 use_registry: boolean():
694 Enable or disable use of the socket registry for this
695 socket. This overrides the global value.
696 Defaults to the global value, see use_registry/1.
697 Note:
699 This function should be used with care!
700 On some platforms its necessary to provide the protocol as its
702 impossible to retrieve it.
703 open(Domain, Type) -> {ok, Socket} | {error, Reason}
706 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
708 open(Domain, Type, Protocol, Opts) ->
710 {ok, Socket} | {error, Reason}
711 Types:
713 Domain = domain()
715 Type = type()
716 Protocol = default | protocol()
717 Opts =
718 #{netns => string(),
719 debug => boolean(),
720 use_registry => boolean()}
721 Socket = socket()
722 Reason = errcode()
723 Creates an endpoint (socket) for communication.
725 For some types there is a default protocol, indicated by
727 default, which it may be possible to specify. And for Domain =
728 local, if a protocol is pecified, it must be default.
729 The Opts argument is intended for "other" options. The supported
731 option(s) are described below:
732 netns: string():
734 Used to set the network namespace during the open call. Only
735 supported on the Linux platform.
736 debug: boolean():
738 Enable or disable debug during the open call.
739 Defaults to false.
740 use_registry: boolean():
742 Enable or disable use of the socket registry for this
743 socket. This overrides the global value.
744 Defaults to the global value, see use_registry/1.
745 Note:
747 It may not be possible to specify the default protocol (except
748 when Domain = local). We need to be able to retreive the result‐
749 ing protocol, which is not possble on all platforms.
750 peername(Socket) -> {ok, SockAddr} | {error, Reason}
753 Types:
755 Socket = socket()
757 SockAddr = sockaddr()
758 Reason = inet:posix() | closed
759 Returns the address of the peer connected to the socket.
761 recv(Socket) -> {ok, Data} | {error, Reason}
763 recv(Socket, Length) -> {ok, Data} | {error, Reason}
765 recv(Socket, Length, Flags) -> {ok, Data} | {error, Reason}
767 recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
769 recv(Socket, Length, Flags, Timeout) ->
771 {ok, Data} | {error, Reason}
772 Types:
774 Socket = socket()
776 Length = integer() >= 0
777 Flags = recv_flags()
778 Timeout = timeout()
779 Data = binary()
780 Reason =
781 errcode() |
782 closed | timeout |
783 {errcode() | closed | timeout, Data :: binary()}
784 Receive a message from a socket.
786 There is a special case for the argument Length. If it is set to
788 zero (0), it means "give me everything you currently have".
789 recv(Socket, Length, Timeout :: nowait) ->
791 {ok, Data} |
792 {ok, {Data, SelectInfo}} |
793 {select, SelectInfo} |
794 {error, Reason}
795 recv(Socket, Length, Flags, Timeout :: nowait) ->
797 {ok, Data} |
798 {ok, {Data, SelectInfo}} |
799 {select, SelectInfo} |
800 {error, Reason}
801 Types:
803 Socket = socket()
805 Length = integer() >= 0
806 Flags = recv_flags()
807 Data = binary()
808 SelectInfo = select_info()
809 Reason =
810 errcode() | closed | {errcode() | closed, Data ::
811 binary()}
812 Receive a message from a socket.
814 There is a special case for the argument Length. If it is set to
816 zero (0), it means "give me everything you currently have".
817 In the case when there is no data waiting, the function will
819 return with the SelectInfo. The caller can then await a select
820 message, {'$socket', Socket, select, Info} (where Info is the
821 ref field from the SelectInfo), when data has arrived (a subse‐
822 quent call to recv will then return the data).
823 Note that if a length (> 0) is specified, and only part of that
825 amount of data is available, the function will return with that
826 data and the SelectInfo (if the caller don't want to wait for
827 the remaining data, it must immediately call the cancel/2 func‐
828 tion.)
829 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
831 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
833 recvfrom(Socket, Flags, Timeout) ->
835 {ok, {Source, Data}} | {error, Reason}
836 recvfrom(Socket, BufSz, Flags) ->
838 {ok, {Source, Data}} | {error, Reason}
839 recvfrom(Socket, BufSz, Timeout) ->
841 {ok, {Source, Data}} | {error, Reason}
842 recvfrom(Socket, BufSz, Flags, Timeout) ->
844 {ok, {Source, Data}} | {error, Reason}
845 Types:
847 Socket = socket()
849 BufSz = integer() >= 0
850 Flags = recv_flags()
851 Timeout = timeout()
852 Source = sockaddr() | undefined
853 Data = binary()
854 Reason = errcode() | closed | timeout
855 Receive a message from a socket.
857 This function reads "messages", which means that regardless of
859 how much we want to read, it returns when we get a message (if
860 the buffer size is too small, the message will be truncated).
861 The BufSz argument basically defines the size of the receive
863 buffer. By setting the value to zero (0), the configured size
864 (setopt with Level = otp and Key = rcvbuf) is used.
865 It may be impossible to know what (buffer) size is appropriate
867 "in advance", and in those cases it may be convenient to use the
868 (recv) 'peek' flag. When this flag is provided, the message is
869 *not* "consumed" from the underlying buffers, so another
870 recvfrom call is needed, possibly with a then adjusted buffer
871 size.
872 recvfrom(Socket, Flags, Timeout :: nowait) ->
874 {ok, {Source, Data}} |
875 {select, SelectInfo} |
876 {error, Reason}
877 recvfrom(Socket, BufSz, Timeout :: nowait) ->
879 {ok, {Source, Data}} |
880 {select, SelectInfo} |
881 {error, Reason}
882 recvfrom(Socket, BufSz, Flags, Timeout :: nowait) ->
884 {ok, {Source, Data}} |
885 {select, SelectInfo} |
886 {error, Reason}
887 Types:
889 Socket = socket()
891 BufSz = integer() >= 0
892 Flags = recv_flags()
893 Source = sockaddr() | undefined
894 Data = binary()
895 SelectInfo = select_info()
896 Reason = errcode() | closed
897 Receive a message from a socket.
899 This function reads "messages", which means that regardless of
901 how much we want to read, it returns when we get a message (if
902 the buffer size is too small, the message will be truncated).
903 The BufSz argument basically defines the size of the receive
905 buffer. By setting the value to zero (0), the configured size
906 (setopt with Level = otp and Key = rcvbuf) is used.
907 It may be impossible to know what (buffer) size is appropriate
909 "in advance", and in those cases it may be convenient to use the
910 (recv) 'peek' flag. When this flag is provided, the message is
911 *not* "consumed" from the underlying buffers, so another
912 recvfrom call is needed, possibly with a then adjusted buffer
913 size.
914 In the case when there is no data waiting, the function will
916 return with the SelectInfo. The caller can then await a select
917 message, {'$socket', Socket, select, Info} (where Info is the
918 ref field from the SelectInfo), when data has arrived (a subse‐
919 quent call to recvfrom will then return the data).
920 recvmsg(Socket) -> {ok, MsgHdr} | {error, Reason}
922 recvmsg(Socket, Flags) -> {ok, MsgHdr} | {error, Reason}
924 recvmsg(Socket, Timeout) -> {ok, MsgHdr} | {error, Reason}
926 recvmsg(Socket, Flags, Timeout) -> {ok, MsgHdr} | {error, Reason}
928 recvmsg(Socket, BufSz, CtrlSz) -> {ok, MsgHdr} | {error, Reason}
930 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout) ->
932 {ok, MsgHdr} | {error, Reason}
933 Types:
935 Socket = socket()
937 BufSz = CtrlSz = integer() >= 0
938 Flags = recv_flags()
939 Timeout = timeout()
940 MsgHdr = msghdr()
941 Reason = errcode() | closed | timeout
942 Receive a message from a socket.
944 This function reads "messages", which means that regardless of
946 how much we want to read, it returns when we get a message.
947 The message will be delivered in the form of a msghdr(), which
949 may contain the source address (if socket not connected), a list
950 of cmsghdr_recv() (depends on what socket options have been set
951 and what the protocol and platform supports) and also a set of
952 flags, providing further info about the read.
953 The BufSz argument basically defines the size of the receive
955 buffer. By setting the value to zero (0), the configured size
956 (setopt with Level = otp and Key = rcvbuf) is used.
957 The CtrlSz argument basically defines the size of the receive
959 buffer for the control messages. By setting the value to zero
960 (0), the configured size (setopt with Level = otp) is used.
961 It may be impossible to know what (buffer) size is appropriate
963 "in advance", and in those cases it may be convenient to use the
964 (recv) 'peek' flag. When this flag is provided, the message is
965 *not* "consumed" from the underlying buffers, so another recvmsg
966 call is needed, possibly with a then adjusted buffer size.
967 recvmsg(Socket, Timeout :: nowait) ->
969 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
970 recvmsg(Socket, Flags, Timeout :: nowait) ->
972 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
973 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: nowait) ->
975 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
976 Types:
978 Socket = socket()
980 BufSz = CtrlSz = integer() >= 0
981 Flags = recv_flags()
982 MsgHdr = msghdr()
983 SelectInfo = select_info()
984 Reason = errcode() | closed
985 Receive a message from a socket.
987 This function reads "messages", which means that regardless of
989 how much we want to read, it returns when we get a message.
990 The message will be delivered in the form of a msghdr(), which
992 may contain the source address (if socket not connected), a list
993 of cmsghdr_recv() (depends on what socket options have been set
994 and what the protocol and platform supports) and also a set of
995 flags, providing further info about the read.
996 The BufSz argument basically defines the size of the receive
998 buffer. By setting the value to zero (0), the configured size
999 (setopt with Level = otp and Key = rcvbuf) is used.
1000 The CtrlSz argument basically defines the size of the receive
1002 buffer for the control messages. By setting the value to zero
1003 (0), the configured size (setopt with Level = otp) is used.
1004 It may be impossible to know what (buffer) size is appropriate
1006 "in advance", and in those cases it may be convenient to use the
1007 (recv) 'peek' flag. When this flag is provided, the message is
1008 *not* "consumed" from the underlying buffers, so another recvmsg
1009 call is needed, possibly with a then adjusted buffer size.
1010 In the case when there is no data waiting, the function will
1012 return with the SelectInfo. The caller can then await a select
1013 message, {'$socket', Socket, select, Info} (where Info is the
1014 ref field from the SelectInfo), when data has arrived (a subse‐
1015 quent call to recvmsg will then return the data).
1016 send(Socket, Data) -> ok | {error, Reason}
1018 send(Socket, Data, Flags) -> ok | {error, Reason}
1020 send(Socket, Data, Timeout) -> ok | {error, Reason}
1022 send(Socket, Data, Flags, Timeout) -> ok | {error, Reason}
1024 Types:
1026 Socket = socket()
1028 Data = iodata()
1029 Flags = send_flags()
1030 Timeout = timeout()
1031 Reason =
1032 {errcode() | closed | timeout, Remaining :: integer() >=
1033 1}
1034 Send a message on a connected socket.
1036 send(Socket, Data, Timeout :: nowait) ->
1038 ok |
1039 {ok, {binary(), SelectInfo}} |
1040 {select, SelectInfo} |
1041 {ok, {RestData, SelectInfo}} |
1042 {error, Reason}
1043 send(Socket, Data, Flags, Timeout :: nowait) ->
1045 ok |
1046 {select, SelectInfo} |
1047 {ok, {RestData, SelectInfo}} |
1048 {error, Reason}
1049 Types:
1051 Socket = socket()
1053 Data = iodata()
1054 Flags = send_flags()
1055 RestData = binary()
1056 SelectInfo = select_info()
1057 Reason = {errcode() | closed, Remaining :: integer() >= 1}
1058 Send a message on a connected socket.
1060 In the case when there is no room in the (system-) buffers, the
1062 function will return with the SelectInfo. The caller can then
1063 await a select message, {'$socket', Socket, select, Info} (where
1064 Info is the ref field from the SelectInfo), when there is room
1065 for more data (a subsequent call to send will then send the
1066 data).
1067 Note that if not all the data was sent, the function will return
1069 with the remaining data and the SelectInfo (if the caller don't
1070 want to wait to be able to send the rest, it should immediately
1071 call the cancel/2 function.)
1072 sendmsg(Socket, MsgHdr) -> ok | {ok, Remaining} | {error, Reason}
1074 sendmsg(Socket, MsgHdr, Flags) -> ok | {error, Reason}
1076 sendmsg(Socket, MsgHdr, Timeout) -> ok | {error, Reason}
1078 sendmsg(Socket, MsgHdr, Flags, Timeout) ->
1080 ok | {ok, Remaining} | {error, Reason}
1081 Types:
1083 Socket = socket()
1085 MsgHdr = msghdr()
1086 Flags = send_flags()
1087 Timeout = timeout()
1088 Remaining = erlang:iovec()
1089 Reason = errcode() | closed | timeout
1090 Send a message on a socket. The destination, if needed (socket
1092 not connected) is provided in the MsgHdr, which also contains
1093 the message to send, The MsgHdr may also contain an list of
1094 optional cmsghdr_send() (depends on what the protocol and plat‐
1095 form supports).
1096 Unlike the send function, this one sends one message. This means
1098 that if, for whatever reason, its not possible to send the mes‐
1099 sage in one go, the function will instead return with the
1100 remaining data ({ok, Remaining}). Thereby leaving it up to the
1101 caller to decide what to do (retry with the remaining data of
1102 give up).
1103 sendmsg(Socket, MsgHdr, Timeout :: nowait) ->
1105 ok | {ok, Remaining} | {error, Reason}
1106 sendmsg(Socket, MsgHdr, Flags, Timeout :: nowait) ->
1108 ok | {ok, Remaining} | {error, Reason}
1109 Types:
1111 Socket = socket()
1113 MsgHdr = msghdr()
1114 Flags = send_flags()
1115 Remaining = erlang:iovec()
1116 Reason = errcode() | closed
1117 Send a message on a socket. The destination, if needed (socket
1119 not connected) is provided in the MsgHdr, which also contains
1120 the message to send, The MsgHdr may also contain an list of
1121 optional cmsghdr_send() (depends on what the protocol and plat‐
1122 form supports).
1123 Unlike the send function, this one sends one message. This means
1125 that if, for whatever reason, its not possible to send the mes‐
1126 sage in one go, the function will instead return with the
1127 remaining data ({ok, Remaining}). Thereby leaving it up to the
1128 caller to decide what to do (retry with the remaining data of
1129 give up).
1130 In the case when there is no room in the (system-) buffers, the
1132 function will return with the SelectInfo. The caller can then
1133 await a select message, {'$socket', Socket, select, Info} (where
1134 Info is the ref field from the SelectInfo), when there is room
1135 for more data (a subsequent call to sendmsg will then send the
1136 data).
1137 sendto(Socket, Data, Dest) -> ok | {error, Reason}
1139 sendto(Socket, Data, Dest, Flags) -> ok | {error, Reason}
1141 sendto(Socket, Data, Dest, Timeout) -> ok | {error, Reason}
1143 sendto(Socket, Data, Dest, Flags, Timeout) -> ok | {error, Reason}
1145 Types:
1147 Socket = socket()
1149 Data = binary()
1150 Dest = sockaddr()
1151 Flags = send_flags()
1152 Timeout = timeout()
1153 Reason =
1154 {errcode() | closed | timeout, Remaining :: integer() >=
1155 1}
1156 Send a message on a socket, to the specified destination.
1158 sendto(Socket, Data, Dest, Timeout :: nowait) ->
1160 ok | {select, SelectInfo} | {error, Reason}
1161 sendto(Socket, Data, Dest, Flags, Timeout :: nowait) ->
1163 ok |
1164 {ok, {binary(), SelectInfo}} |
1165 {select, SelectInfo} |
1166 {error, Reason}
1167 Types:
1169 Socket = socket()
1171 Data = binary()
1172 Dest = sockaddr()
1173 Flags = send_flags()
1174 SelectInfo = select_info()
1175 Reason = {errcode() | closed, Remaining :: integer() >= 1}
1176 Send a message on a socket, to the specified destination.
1178 In the case when there is no room in the (system-) buffers, the
1180 function will return with the SelectInfo. The caller can then
1181 await a select message, {'$socket', Socket, select, Info} (where
1182 Info is the ref field from the SelectInfo), when there is room
1183 for more data (a subsequent call to sendto will then send the
1184 data).
1185 setopt(Socket, Level :: otp, Key :: otp_socket_option(), Value) ->
1187 ok | {error, Reason}
1188 setopt(Socket, Level :: socket, Key :: socket_option(), Value) ->
1190 ok | {error, Reason}
1191 setopt(Socket, Level :: ip, Key :: ip_socket_option(), Value) ->
1193 ok | {error, Reason}
1194 setopt(Socket, Level :: ipv6, Key :: ipv6_socket_option(), Value) ->
1196 ok | {error, Reason}
1197 setopt(Socket, Level :: tcp, Key :: tcp_socket_option(), Value) ->
1199 ok | {error, Reason}
1200 setopt(Socket, Level :: udp, Key :: udp_socket_option(), Value) ->
1202 ok | {error, Reason}
1203 setopt(Socket, Level :: sctp, Key :: sctp_socket_option(), Value) ->
1205 ok | {error, Reason}
1206 setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
1208 Types:
1210 Socket = socket()
1212 Level = Key = integer() >= 0
1213 Value = binary()
1214 Reason = inet:posix() | closed
1215 Set an option on a socket.
1217 What options are valid depend both on Level and on what kind of
1219 socket it is (domain, type and protocol).
1220 See the socket options chapter of the users guide for more info.
1222 Note:
1224 Not all options are valid on all platforms. That is, even if
1225 "we" support an option, that does not mean that the underlying
1226 OS does.
1227 Note:
1230 Sockets are set 'non-blocking' when created, so this option is
1231 *not* available (as it would adversely effect the Erlang VM to
1232 set a socket 'blocking').
1233 setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
1236 Types:
1238 Socket = socket()
1240 Level = Key = integer() >= 0
1241 Value = binary()
1242 Reason = inet:posix() | closed
1243 Set options on a socket.
1245 When specifying Level as an integer, and therefor using "native
1247 mode", it is *currently* up to the caller to know how to encode
1248 the Value.
1249 For more info, see setopt above.
1251 shutdown(Socket, How) -> ok | {error, Reason}
1253 Types:
1255 Socket = socket()
1257 How = shutdown_how()
1258 Reason = inet:posix() | closed
1259 Shut down all or part of a full-duplex connection.
1261 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
1263 Types:
1265 Socket = socket()
1267 SockAddr = sockaddr()
1268 Reason = inet:posix() | closed
1269 Returns the current address to which the socket is bound.
1271 supports() -> Supports
1273 supports(Key1 :: options) -> SupportsOptions
1274 supports(Key1 :: send_flags) -> SupportsSendFlags
1275 supports(Key1 :: recv_flags) -> SupportsRecvFlags
1276 supports(Key1 :: options, Key2 :: socket) -> SupportsOptionsSocket
1277 supports(Key1 :: options, Key2 :: ip) -> SupportsOptionsIP
1278 supports(Key1 :: options, Key2 :: ipv6) -> SupportsOptionsIPv6
1279 supports(Key1 :: options, Key2 :: tcp) -> SupportsOptionsTCP
1280 supports(Key1 :: options, Key2 :: udp) -> SupportsOptionsUDP
1281 supports(Key1 :: options, Key2 :: sctp) -> SupportsOptionsSCTP
1282 Types:
1284 Supports :: [{Feature, boolean()} | {send_flags, Support‐
1286 sSendFlags} | {recv_flags, SupportsRecvFlags} | {options,
1287 SupportsOptions}]
1288 Feature :: sctp | ipv6 | local | netns
1289 SupportsSendFlags :: [{send_flag(), boolean()}]
1290 SupportsRecvFlags :: [{recv_flag(), boolean()}]
1291 SupportsOptions :: [{socket, SupportsOptionsSocket} | {ip,
1292 SupportsOptionsIP} | {ipv6, SupportsOptionsIPv6} | {tcp, Sup‐
1293 portsOptionsTCP} | {udp, SupportsOptionsUDP} | {sctp, Sup‐
1294 portsOptionsSCTP}]
1295 SupportsOptionsSocket :: [{socket_option(), boolean()}]
1296 SupportsOptionsIP :: [{ip_socket_option(), boolean()}]
1297 SupportsOptionsIPv6 :: [{ipv6_socket_option(), boolean()}]
1298 SupportsOptionsTCP :: [{tcp_socket_option(), boolean()}]
1299 SupportsOptionsUDP :: [{udp_socket_option(), boolean()}]
1300 SupportsOptionsSCTP :: [{sctp_socket_option(), boolean()}]
1301 This function retreives information about what the platform sup‐
1303 ports, such as if SCTP is supported, or which socket options are
1304 supported.
1305 For keys other than the known the empty list is returned, Note
1307 that in a future version or on a different platform there might
1308 be more supported items.
1309 is_supported(Key1 :: sctp | ipv6 | local | netns) -> boolean()
1311 is_supported(Key1 :: send_flags, Key2 :: SendFlag) -> boolean()
1312 is_supported(Key1 :: recv_flags, Key2 :: RecvFlag) -> boolean()
1313 is_supported(Key1 :: options, Key2 :: socket, Key3 :: SocketOption) ->
1314 boolean()
1315 is_supported(Key1 :: options, Key2 :: ip, Key3 :: IPSocketOption) ->
1316 boolean()
1317 is_supported(Key1 :: options, Key2 :: ipv6, Key3 :: IPv6SocketOption)
1318 -> boolean()
1319 is_supported(Key1 :: options, Key2 :: tcp, Key3 :: TCPSocketOption) ->
1320 boolean()
1321 is_supported(Key1 :: options, Key2 :: udp, Key3 :: UDPSocketOption) ->
1322 boolean()
1323 is_supported(Key1 :: options, Key2 :: sctp, Key3 :: SCTPSocketOption)
1324 -> boolean()
1325 Types:
1327 SocketOption :: socket_option()
1329 IPSocketOption :: ip_socket_option()
1330 IPv6SocketOption :: ipv6_socket_option()
1331 TCPSocketOption :: tcp_socket_option()
1332 UDPSocketOption :: udp_socket_option()
1333 SCTPSocketOption :: sctp_socket_option()
1334 This function retreives information about what the platform sup‐
1336 ports, such as if SCTP is supported, or which socket options are
1337 supported.
1338 For keys other than the known false is returned. Note that in a
1340 future version or on a different platform there might be more
1341 supported items.
1342 use_registry(D :: boolean()) -> ok
1344 Globally change if the socket registry is to be used or not.
1346 Note that its still possible to override this explicitly when
1347 creating an individual sockets, see open/2 or open/4 for more
1348 info (use the Extra argument).
1349 which_sockets() -> [socket()]
1351 which_sockets(FilterRule) -> [socket()]
1353 Types:
1355 FilterRule =
1357 inet | inet6 | stream | dgram | seqpacket | sctp | tcp |
1358 udp |
1359 pid() |
1360 fun((socket_info()) -> boolean())
1361 Returns a list of all sockets, according to the filter rule.
1363 There are several pre-made filter rule(s) and one general:
1365 inet | inet6:
1367 Selection based on the domain of the socket.
1368 Only a subset is valid.
1369 stream | dgram | seqpacket:
1371 Selection based on the type of the socket.
1372 Only a subset is valid.
1373 sctp | tcp | udp:
1375 Selection based on the protocol of the socket.
1376 Only a subset is valid.
1377 pid():
1379 Selection base on which sockets has this pid as Controlling
1380 Process.
1381 fun((socket_info()) -> boolean()):
1383 The general filter rule.
1384 A fun that takes the socket info and returns a boolean()
1385 (true if the socket sould be included and false if should
1386 not).
1387
1389 client(Addr, SAddr, SPort) ->
1390 {ok, Sock} = socket:open(inet, stream, tcp),
1391 {ok, _} = socket:bind(Sock, #{family => inet,
1392 addr => Addr}),
1393 ok = socket:connect(Sock, #{family => inet,
1394 addr => SAddr,
1395 port => SPort}),
1396 Msg = list_to_binary("hello"),
1397 ok = socket:send(Sock, Msg),
1398 ok = socket:shutdown(Sock, write),
1399 {ok, Msg} = socket:recv(Sock),
1400 ok = socket:close(Sock).
1401 server(Addr, Port) ->
1403 {ok, LSock} = socket:open(inet, stream, tcp),
1404 {ok, _} = socket:bind(LSock, #{family => inet,
1405 port => Port,
1406 addr => Addr}),
1407 ok = socket:listen(LSock),
1408 {ok, Sock} = socket:accept(LSock),
1409 {ok, Msg} = socket:recv(Sock),
1410 ok = socket:send(Sock, Msg),
1411 ok = socket:shutdown(Sock, write),
1412 ok = socket:close(Sock),
1413 ok = socket:close(LSock).
1414Ericsson AB kernel 7.3 socket(3)