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 manipulate the sockets as well as sending and re‐
11 ceiving 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, have a time-out argument.
16 Note:
18 Some functions allow for an asynchronous call. This is achieved by
19 setting the Timeout argument to nowait or to a (select or completion)
20 handle .
21 For instance, if calling the recv/3 function with Timeout set to nowait
23 (recv(Sock, 0, nowait)) when there is actually nothing to read, it will
24 return with either one of:
25 : {completion, CompletionInfo}
27 : {select, SelectInfo}
29 CompletionInfo contains the CompletionHandle and SelectInfo contains
31 the SelectHandle.
32 We have two different implementations. One on Unix (select, based di‐
34 rectly on the synchronous standard socket interface) and one on Windows
35 (completion, based on the asynchronous I/O Completion Ports).
36 These two implementations have a slightly different behaviour and mes‐
38 sage interface.
39 The difference will only manifest for the user, if calls are made with
41 the timeout argument set to 'nowait' (see above).
42 When an completion message is received (with the result of the opera‐
44 tion), that means that the operation (connect, send, recv, ...) has
45 been completed (successfully or otherwise). When a select message is
46 received, that only means that the operation can now be completed, via
47 a call to, for instance, connect/1.
48 The completion message has the format:
50 : {'$socket', socket(), completion, {CompletionHandle, CompletionSta‐
52 tus}}
53 The select message has the format:
55 : {'$socket', socket(), select, SelectHandle}
57 Note that, on select "system", all other users are locked out until the
59 'current user' has called the function (recv for instance) and its re‐
60 turn value shows that the operation has completed. Such an operation
61 can also be cancelled with cancel/2.
62 Instead of Timeout = nowait it is equivalent to create a SelectHandle
64 or CompletionHandle with make_ref() and give as Timeout. This will then
65 be the Handle in the 'completion' or 'select' message, which enables a
66 compiler optimization for receiving a message containing a newly cre‐
67 ated reference() (ignore the part of the message queue that had arrived
68 before the the reference() was created).
69 Another message the user must be prepared for (when making asynchronous
71 calls) is the abort message:
72 : {'$socket', socket(), abort, Info}
74 This message indicates that the (asynchronous) operation has been
76 aborted. If, for instance, the socket has been closed (by another
77 process), Info will be {SelectHandle, closed}.
78 Note:
81 The Windows support has currently pre-release status.
82 Support for IPv6 has been implemented but not fully tested.
84 SCTP has only been partly implemented (and not tested).
86
89 invalid() = {invalid, What :: term()}
90 eei() =
92 #{info :=
93 econnreset | econnaborted | netname_deleted |
94 too_many_cmds |
95 atom(),
96 raw_info := term()}
97 Extended Error Info. A term containing additional (error) info
99 if the socket nif has been configured to produce it.
100 domain() = inet | inet6 | local | unspec
102 A lowercase atom() representing a protocol domain on the plat‐
104 form named AF_* (or PF_*).
105 The calls supports(), is_supported(ipv6) and is_supported(local)
107 tells if the IPv6 protocol for the inet6 protocol domain / ad‐
108 dress family, and if the local protocol domain / address family
109 is supported by the platform's header files.
110 type() = stream | dgram | raw | rdm | seqpacket
112 A lowercase atom() representing a protocol type on the platform
114 named SOCK_*.
115 protocol() = atom()
117 An atom() means any protocol as enumerated by the C library call
119 getprotoent() on the platform, or at least the supported ones of
120 ip | ipv6 | tcp | udp | sctp.
121 See open/2,3,4
123 The call supports(protocols) returns which protocols are sup‐
125 ported, and is_supported(protocols, Protocol) tells if Protocol
126 is among the enumerated.
127 socket() = {'$socket', socket_handle()}
129 As returned by open/1,2,3,4 and accept/1,2.
131 socket_handle()
133 An opaque socket handle unique for the socket.
135 select_tag()
137 A tag that describes the (select) operation, contained in the
139 returned select_info().
140 select_handle() = reference()
142 A reference() that uniquely identifies the (select) operation,
144 contained in the returned select_info().
145 select_info() =
147 {select_info,
148 SelectTag :: select_tag(),
149 SelectHandle :: select_handle()}
150 Returned by an operation that requires the caller to wait for a
152 select message containing the SelectHandle.
153 completion_tag()
155 A tag that describes the ongoing (completion) operation, con‐
157 tained in the returned completion_info().
158 completion_handle() = reference()
160 A reference() that uniquely identifies the (completion) opera‐
162 tion, contained in the returned completion_info().
163 completion_info() =
165 {completion_info,
166 CompletionTag :: completion_tag(),
167 CompletionHandle :: completion_handle()}
168 Returned by an operation that requires the caller to wait for a
170 completion message containing the CompletionHandle and the re‐
171 sult of the operation; the CompletionStatus.
172 info() =
174 #{counters := #{atom() := integer() >= 0},
175 iov_max := integer() >= 0,
176 use_registry := boolean(),
177 io_backend := #{name := atom()}}
178 The smallest allowed iov_max value according to POSIX is 16, but
180 check your platform documentation to be sure.
181 socket_counters() =
183 #{read_byte := integer() >= 0,
184 read_fails := integer() >= 0,
185 read_pkg := integer() >= 0,
186 read_pkg_max := integer() >= 0,
187 read_tries := integer() >= 0,
188 read_waits := integer() >= 0,
189 write_byte := integer() >= 0,
190 write_fails := integer() >= 0,
191 write_pkg := integer() >= 0,
192 write_pkg_max := integer() >= 0,
193 write_tries := integer() >= 0,
194 write_waits := integer() >= 0,
195 sendfile => integer() >= 0,
196 sendfile_byte => integer() >= 0,
197 sendfile_fails => integer() >= 0,
198 sendfile_max => integer() >= 0,
199 sendfile_pkg => integer() >= 0,
200 sendfile_pkg_max => integer() >= 0,
201 sendfile_tries => integer() >= 0,
202 sendfile_waits => integer() >= 0,
203 acc_success := integer() >= 0,
204 acc_fails := integer() >= 0,
205 acc_tries := integer() >= 0,
206 acc_waits := integer() >= 0}
207 info_keys() =
209 [domain | type | protocol | fd | owner | local_address |
210 remote_address | recv | sent | state]
211 Defines the information elements of the table(s) printed by the
213 i/0, i/1 and i/2 functions.
214 socket_info() =
216 #{domain := domain() | integer(),
217 type := type() | integer(),
218 protocol := protocol() | integer(),
219 owner := pid(),
220 ctype := normal | fromfd | {fromfd, integer()},
221 counters := socket_counters(),
222 num_readers := integer() >= 0,
223 num_writers := integer() >= 0,
224 num_acceptors := integer() >= 0,
225 writable := boolean(),
226 readable := boolean(),
227 rstates := [atom()],
228 wstates := [atom()]}
229 in_addr() = {0..255, 0..255, 0..255, 0..255}
231 in6_addr() =
233 {0..65535,
234 0..65535,
235 0..65535,
236 0..65535,
237 0..65535,
238 0..65535,
239 0..65535,
240 0..65535}
241 sockaddr() =
243 sockaddr_in() |
244 sockaddr_in6() |
245 sockaddr_un() |
246 sockaddr_ll() |
247 sockaddr_dl() |
248 sockaddr_unspec() |
249 sockaddr_native()
250 sockaddr_recv() = sockaddr() | binary()
252 sockaddr_in() =
254 #{family := inet,
255 port := port_number(),
256 addr := any | broadcast | loopback | in_addr()}
257 sockaddr_in6() =
259 #{family := inet6,
260 port := port_number(),
261 addr := any | loopback | in6_addr(),
262 flowinfo := in6_flow_info(),
263 scope_id := in6_scope_id()}
264 sockaddr_un() = #{family := local, path := binary() | string()}
266 The path element will always be a binary when returned from this
268 module. When supplied to an API function in this module it may
269 be a string(), which will be encoded into a binary according to
270 the native file name encoding on the platform.
271 A terminating zero character will be appended before the address
273 path is given to the OS, and the terminating zero will be
274 stripped before giving the address path to the caller.
275 Linux's non-portable abstract socket address extension is han‐
277 dled by not doing any terminating zero processing in either di‐
278 rection, if the first byte of the address is zero.
279 sockaddr_ll() =
281 #{family := packet,
282 protocol := integer() >= 0,
283 ifindex := integer(),
284 pkttype := packet_type(),
285 hatype := hatype(),
286 addr := binary()}
287 sockaddr_dl() =
289 #{family := link,
290 index := integer() >= 0,
291 type := integer() >= 0,
292 nlen := integer() >= 0,
293 alen := integer() >= 0,
294 slen := integer() >= 0,
295 data := binary()}
296 sockaddr_unspec() = #{family := unspec, addr := binary()}
298 sockaddr_native() = #{family := integer(), addr := binary()}
300 packet_type() =
302 host | broadcast | multicast | otherhost | outgoing |
303 loopback | user | kernel | fastroute |
304 integer() >= 0
305 hatype() =
307 netrom | eether | ether | ax25 | pronet | chaos | ieee802 |
308 arcnet | appletlk | dlci | atm | metricom | ieee1394 | eui64 |
309 infiniband | tunnel | tunnel6 | loopback | localtlk | none |
310 void |
311 integer() >= 0
312 port_number() = 0..65535
314 in6_flow_info() = 0..1048575
316 in6_scope_id() = 0..4294967295
318 msg_flag() =
320 cmsg_cloexec | confirm | ctrunc | dontroute | eor | errqueue |
321 more | oob | peek | trunc
322 Flags corresponding to the message flag constants on the plat‐
324 form. The flags are lowercase and the constants are uppercase
325 with the prefix MSG_.
326 Some flags are only used for sending, some only for receiving,
328 some in received control messages, and some for several of
329 these. Not all flags are supported on all platforms. See the
330 platform's documentation, supports(msg_flags), and is_sup‐
331 ported(msg_flags, MsgFlag).
332 level() = socket | protocol()
334 The OS protocol levels for, for example, socket options and con‐
336 trol messages, with the following names in the OS header files:
337 socket:
339 SOL_SOCKET with options named SO_*.
340 ip:
342 IPPROTO_IP a.k.a SOL_IP with options named IP_*.
343 ipv6:
345 IPPROTO_IPV6 a.k.a SOL_IPV6 with options named IPV6_*.
346 tcp:
348 IPPROTO_TCP with options named TCP_*.
349 udp:
351 IPPROTO_UDP with options named UDP_*.
352 sctp:
354 IPPROTO_SCTP with options named SCTP_*.
355 There are many other possible protocols, but the ones above are
357 those for which this socket library implements socket options
358 and/or control messages.
359 All protocols known to the OS are enumerated when the Erlang VM
361 is started. See the OS man page for protocols(5). The protocol
362 level 'socket' is always implemented as SOL_SOCKET and all the
363 others mentioned in the list above are valid, if supported by
364 the platform, enumerated or not.
365 The calls supports() and is_supported(protocols, Protocol) can
367 be used to find out if protocols ipv6 and/or sctp are supported
368 according to the platform's header files.
369 otp_socket_option() =
371 debug | iow | controlling_process | rcvbuf | rcvctrlbuf |
372 sndctrlbuf | meta | use_registry | fd | domain
373 These are socket options for the otp protocol level, that is
375 {otp, Name} options, above all OS protocol levels. They affect
376 Erlang/OTP's socket implementation.
377 debug:
379 boolean() - Activate debug printout.
380 iow:
382 boolean() - Inform On Wrap of statistics counters.
383 controlling_process:
385 pid() - The socket "owner". Only the current controlling
386 process can set this option.
387 rcvbuf:
389 BufSize :: (default | integer()>0) | {N :: integer()>0,
390 BufSize :: (default | integer()>0)} - Receive buffer size.
391 The value default is only valid to set. N specifies the num‐
392 ber of read attempts to do in a tight loop before assuming
393 no more data is pending.
394 rcvctrlbuf:
396 BufSize :: (default | integer()>0) - Buffer size for re‐
397 ceived ancillary messages. The value default is only valid
398 to set.
399 sndctrlbuf:
401 BufSize :: (default | integer()>0) - Buffer size for sent
402 ancillary messages. The value default is only valid to set.
403 fd:
405 integer() - Only valid to get. The OS protocol levels'
406 socket descriptor. Functions open/1,2 can be used to create
407 a socket according to this module from an existing OS socket
408 descriptor.
409 use_registry:
411 boolean() - Only valid to get. The value is set when the
412 socket is created with open/2 or open/4.
413 Options not described here are intentionally undocumented and
415 for Erlang/OTP internal use only.
416 socket_option() =
418 {Level :: socket,
419 Opt ::
420 acceptconn | acceptfilter | bindtodevice | broadcast |
421 bsp_state | busy_poll | debug | domain | dontroute |
422 error | exclusiveaddruse | keepalive | linger | mark |
423 maxdg | max_msg_size | oobinline | passcred | peek_off |
424 peercred | priority | protocol | rcvbuf | rcvbufforce |
425 rcvlowat | rcvtimeo | reuseaddr | reuseport | rxq_ovfl |
426 setfib | sndbuf | sndbufforce | sndlowat | sndtimeo |
427 timestamp | type} |
428 {Level :: ip,
429 Opt ::
430 add_membership | add_source_membership | block_source |
431 dontfrag | drop_membership | drop_source_membership |
432 freebind | hdrincl | minttl | msfilter | mtu |
433 mtu_discover | multicast_all | multicast_if |
434 multicast_loop | multicast_ttl | nodefrag | options |
435 pktinfo | recvdstaddr | recverr | recvif | recvopts |
436 recvorigdstaddr | recvtos | recvttl | retopts |
437 router_alert | sndsrcaddr | tos | transparent | ttl |
438 unblock_source} |
439 {Level :: ipv6,
440 Opt ::
441 addrform | add_membership | authhdr | auth_level |
442 checksum | drop_membership | dstopts | esp_trans_level |
443 esp_network_level | faith | flowinfo | hopopts |
444 ipcomp_level | join_group | leave_group | mtu |
445 mtu_discover | multicast_hops | multicast_if |
446 multicast_loop | portrange | pktoptions | recverr |
447 recvhoplimit | hoplimit | recvpktinfo | pktinfo |
448 recvtclass | router_alert | rthdr | tclass |
449 unicast_hops | use_min_mtu | v6only} |
450 {Level :: tcp,
451 Opt ::
452 congestion | cork | info | keepcnt | keepidle |
453 keepintvl | maxseg | md5sig | nodelay | noopt | nopush |
454 syncnt | user_timeout} |
455 {Level :: udp, Opt :: cork} |
456 {Level :: sctp,
457 Opt ::
458 adaption_layer | associnfo | auth_active_key |
459 auth_asconf | auth_chunk | auth_key | auth_delete_key |
460 autoclose | context | default_send_params |
461 delayed_ack_time | disable_fragments | hmac_ident |
462 events | explicit_eor | fragment_interleave |
463 get_peer_addr_info | initmsg | i_want_mapped_v4_addr |
464 local_auth_chunks | maxseg | maxburst | nodelay |
465 partial_delivery_point | peer_addr_params |
466 peer_auth_chunks | primary_addr | reset_streams |
467 rtoinfo | set_peer_primary_addr | status |
468 use_ext_recvinfo}
469 Socket option on the form {Level, Opt} where the OS protocol
471 Level = level() and Opt is a socket option on that protocol
472 level.
473 The OS name for an options is, except where otherwise noted, the
475 Opt atom, in capitals, with prefix according to level().
476 Note:
478 The IPv6 option pktoptions is a special (barf) case. It is in‐
479 tended for backward compatibility usage only.
480 Do not use this option.
482 Note:
485 See the OS documentation for every socket option.
486 An option below that has the value type boolean() will translate
489 the value false to a C int with value 0, and the value true to
490 !!0 (not (not false)).
491 An option with value type integer() will be translated to a C
493 int that may have a restricted range, for example byte: 0..255.
494 See the OS documentation.
495 The calls supports(options), supports(options, Level) and
497 is_supported(options, {Level, Opt}) can be used to find out
498 which socket options that are supported by the platform.
499 Options for protocol level socket:
501 {socket, acceptconn}:
503 Value = boolean()
504 {socket, bindtodevice}:
506 Value = string()
507 {socket, broadcast}:
509 Value = boolean()
510 {socket, debug}:
512 Value = integer()
513 {socket, domain}:
515 Value = domain()
516 Only valid to get.
518 The socket's protocol domain. Does not work on for instance
520 FreeBSD.
521 {socket, dontroute}:
523 Value = boolean()
524 {socket, keepalive}:
526 Value = boolean()
527 {socket, linger}:
529 Value = abort | linger()
530 The value abort is shorthand for #{onoff => true, linger =>
532 0}, and only valid to set.
533 {socket, oobinline}:
535 Value = boolean()
536 {socket, passcred}:
538 Value = boolean()
539 {socket, peek_off}:
541 Value = integer()
542 Currently disabled due to a possible infinite loop when
544 calling recv/1-4 with peek in Flags.
545 {socket, priority}:
547 Value = integer()
548 {socket, protocol}:
550 Value = protocol()
551 Only valid to get.
553 The socket's protocol. Does not work on for instance Darwin.
555 {socket, rcvbuf}:
557 Value = integer()
558 {socket, rcvlowat}:
560 Value = integer()
561 {socket, rcvtimeo}:
563 Value = timeval()
564 This option is unsupported per default; OTP has to be ex‐
566 plicitly built with the --enable-esock-rcvsndtimeo configure
567 option for this to be available.
568 Since our implementation uses nonblocking sockets, it is un‐
570 known if and how this option works, or even if it may cause
571 malfunction. Therefore, we do not recommend setting this op‐
572 tion.
573 Instead, use the Timeout argument to, for instance, the
575 recv/3 function.
576 {socket, reuseaddr}:
578 Value = boolean()
579 {socket, reuseport}:
581 Value = boolean()
582 {socket, sndbuf}:
584 Value = integer()
585 {socket, sndlowat}:
587 Value = integer()
588 {socket, sndtimeo}:
590 Value = timeval()
591 This option is unsupported per default; OTP has to be ex‐
593 plicitly built with the --enable-esock-rcvsndtimeo configure
594 option for this to be available.
595 Since our implementation uses nonblocking sockets, it is un‐
597 known if and how this option works, or even if it may cause
598 malfunction. Therefore, we do not recommend setting this op‐
599 tion.
600 Instead, use the Timeout argument to, for instance, the
602 send/3 function.
603 {socket, timestamp}:
605 Value = boolean()
606 {socket, type}:
608 Value = type()
609 Only valid to get.
611 The socket's type.
613 Options for protocol level ip:
615 {ip, add_membership}:
617 Value = ip_mreq()
618 Only valid to set.
620 {ip, add_source_membership}:
622 Value = ip_mreq_source()
623 Only valid to set.
625 {ip, block_source}:
627 Value = ip_mreq_source()
628 Only valid to set.
630 {ip, drop_membership}:
632 Value = ip_mreq()
633 Only valid to set.
635 {ip, drop_source_membership}:
637 Value = ip_mreq_source()
638 Only valid to set.
640 {ip, freebind}:
642 Value = boolean()
643 {ip, hdrincl}:
645 Value = boolean()
646 {ip, minttl}:
648 Value = integer()
649 {ip, msfilter}:
651 Value = null | ip_msfilter()
652 Only valid to set.
654 The value null passes a NULL pointer and size 0 to the C li‐
656 brary call.
657 {ip, mtu}:
659 Value = integer()
660 Only valid to get.
662 {ip, mtu_discover}:
664 Value = ip_pmtudisc() | integer()
665 An integer() value is according to the platform's header
667 files.
668 {ip, multicast_all}:
670 Value = boolean()
671 {ip, multicast_if}:
673 Value = any | in_addr()
674 {ip, multicast_loop}:
676 Value = boolean()
677 {ip, multicast_ttl}:
679 Value = integer()
680 {ip, nodefrag}:
682 Value = boolean()
683 {ip, pktinfo}:
685 Value = boolean()
686 {ip, recvdstaddr}:
688 Value = boolean()
689 {ip, recverr}:
691 Value = boolean()
692 Warning! When this option is enabled, error messages may ar‐
694 rive on the socket's error queue, which should be read using
695 the message flag errqueue, and using recvmsg/1,2,3,4,5 to
696 get all error information in the message's ctrl field as a
697 control message #{level := ip, type := recverr}.
698 A working strategy should be to first poll the error queue
700 using recvmsg/2,3,4 with Timeout =:= 0 and Flags containing
701 errqueue (ignore the return value {error, timeout}) before
702 reading the actual data to ensure that the error queue gets
703 cleared. And read the data using one of the nowait | se‐
704 lect_handle() recv functions: recv/3,4, recvfrom/3,4 or
705 recvmsg/3,4,5. Otherwise you might accidentally cause a busy
706 loop in and out of 'select' for the socket.
707 {ip, recvif}:
709 Value = boolean()
710 {ip, recvopts}:
712 Value = boolean()
713 {ip, recvorigdstaddr}:
715 Value = boolean()
716 {ip, recvtos}:
718 Value = boolean()
719 {ip, recvttl}:
721 Value = boolean()
722 {ip, retopts}:
724 Value = boolean()
725 {ip, router_alert}:
727 Value = integer()
728 {ip, sendsrcaddr}:
730 Value = boolean()
731 {ip, tos}:
733 Value = ip_tos() | integer()
734 An integer() value is according to the platform's header
736 files.
737 {ip, transparent}:
739 Value = boolean()
740 {ip, ttl}:
742 Value = integer()
743 {ip, unblock_source}:
745 Value = ip_mreq_source()
746 Only valid to set.
748 Options for protocol level ipv6:
750 {ipv6, addrform}:
752 Value = domain()
753 As far as we know the only valid value is inet and it is
755 only allowed for an IPv6 socket that is connected and bound
756 to an IPv4-mapped IPv6 address.
757 {ipv6, add_membership}:
759 Value = ipv6_mreq()
760 Only valid to set.
762 {ipv6, authhdr}:
764 Value = boolean()
765 {ipv6, drop_membership}:
767 Value = ipv6_mreq()
768 Only valid to set.
770 {ipv6, dstopts}:
772 Value = boolean()
773 {ipv6, flowinfo}:
775 Value = boolean()
776 {ipv6, hoplimit}:
778 Value = boolean()
779 {ipv6, hopopts}:
781 Value = boolean()
782 {ipv6, mtu}:
784 Value = integer()
785 {ipv6, mtu_discover}:
787 Value = ipv6_pmtudisc() | integer()
788 An integer() value is according to the platform's header
790 files.
791 {ipv6, multicast_hops}:
793 Value = ipv6_hops()
794 {ipv6, multicast_if}:
796 Value = integer()
797 {ipv6, multicast_loop}:
799 Value = boolean()
800 {ipv6, recverr}:
802 Value = boolean()
803 Warning! See the socket option {ip, recverr} regarding the
805 socket's error queue. The same warning applies for this op‐
806 tion.
807 {ipv6, recvhoplimit}:
809 Value = boolean()
810 {ipv6, recvpktinfo}:
812 Value = boolean()
813 {ipv6, recvtclass}:
815 Value = boolean()
816 {ipv6, router_alert}:
818 Value = integer()
819 {ipv6, rthdr}:
821 Value = boolean()
822 {ipv6, tclass}:
824 Value = boolean()
825 {ipv6, unicast_hops}:
827 Value = ipv6_hops()
828 {ipv6, v6only}:
830 Value = boolean()
831 Options for protocol level sctp. See also RFC 6458.
833 {sctp, associnfo}:
835 Value = sctp_assocparams()
836 {sctp, autoclose}:
838 Value = integer()
839 {sctp, disable_fragments}:
841 Value = boolean()
842 {sctp, events}:
844 Value = sctp_event_subscribe()
845 Only valid to set.
847 {sctp, initmsg}:
849 Value = sctp_initmsg()
850 {sctp, maxseg}:
852 Value = integer()
853 {sctp, nodelay}:
855 Value = boolean()
856 {sctp, rtoinfo}:
858 Value = sctp_rtoinfo()
859 Options for protocol level tcp:
861 {tcp, congestion}:
863 Value = string()
864 {tcp, cork}:
866 Value = boolean()
867 {tcp, maxseg}:
869 Value = integer()
870 {tcp, nodelay}:
872 Value = boolean()
873 Options for protocol level udp:
875 {udp, cork}:
877 Value = boolean()
878 linger() = #{onoff := boolean(), linger := integer() >= 0}
880 Corresponds to the C struct linger for managing the socket op‐
882 tion {socket, linger}.
883 timeval() = #{sec := integer(), usec := integer()}
885 Corresponds to the C struct timeval. The field sec holds sec‐
887 onds, and usec microseconds.
888 ip_mreq() = #{multiaddr := in_addr(), interface := in_addr()}
890 Corresponds to the C struct ip_mreq for managing multicast
892 groups.
893 ip_mreq_source() =
895 #{multiaddr := in_addr(),
896 interface := in_addr(),
897 sourceaddr := in_addr()}
898 Corresponds to the C struct ip_mreq_source for managing multi‐
900 cast groups.
901 ip_msfilter() =
903 #{multiaddr := in_addr(),
904 interface := in_addr(),
905 mode := include | exclude,
906 slist := [in_addr()]}
907 Corresponds to the C struct ip_msfilter for managing multicast
909 source filtering (RFC 3376).
910 ip_pmtudisc() = want | dont | do | probe
912 Lowercase atom() values corresponding to the C library constants
914 IP_PMTUDISC_*. Some constant(s) may be unsupported by the plat‐
915 form.
916 ip_tos() = lowdelay | throughput | reliability | mincost
918 Lowercase atom() values corresponding to the C library constants
920 IPTOS_*. Some constant(s) may be unsupported by the platform.
921 ip_pktinfo() =
923 #{ifindex := integer() >= 0,
924 spec_dst := in_addr(),
925 addr := in_addr()}
926 ipv6_mreq() =
928 #{multiaddr := in6_addr(), interface := integer() >= 0}
929 Corresponds to the C struct ipv6_mreq for managing multicast
931 groups. See also RFC 2553.
932 ipv6_hops() = default | 0..255
934 The value default is only valid to set and is translated to the
936 C value -1, meaning the route default.
937 ipv6_pmtudisc() = want | dont | do | probe
939 Lowercase atom() values corresponding to the C library constants
941 IPV6_PMTUDISC_*. Some constant(s) may be unsupported by the
942 platform.
943 ipv6_pktinfo() = #{addr := in6_addr(), ifindex := integer()}
945 sctp_assocparams() =
947 #{assoc_id := integer(),
948 asocmaxrxt := 0..65535,
949 numbe_peer_destinations := 0..65535,
950 peer_rwnd := 0..4294967295,
951 local_rwnd := 0..4294967295,
952 cookie_life := 0..4294967295}
953 Corresponds to the C struct sctp_assocparams.
955 sctp_event_subscribe() =
957 #{data_io := boolean(),
958 association := boolean(),
959 address := boolean(),
960 send_failure := boolean(),
961 peer_error := boolean(),
962 shutdown := boolean(),
963 partial_delivery := boolean(),
964 adaptation_layer => boolean(),
965 sender_dry => boolean()}
966 Corresponds to the C struct sctp_event_subscribe.
968 Not all fields are implemented on all platforms; unimplemented
970 fields are ignored, but implemented fields are mandatory. Note
971 that the '_event' suffixes have been stripped from the C struct
972 field names, for convenience.
973 sctp_initmsg() =
975 #{num_ostreams := 0..65535,
976 max_instreams := 0..65535,
977 max_attempts := 0..65535,
978 max_init_timeo := 0..65535}
979 Corresponds to the C struct sctp_initmsg.
981 sctp_rtoinfo() =
983 #{assoc_id := integer(),
984 initial := 0..4294967295,
985 max := 0..4294967295,
986 min := 0..4294967295}
987 Corresponds to the C struct sctp_rtoinfo.
989 msg() = msg_send() | msg_recv()
991 msg_send() =
993 #{addr => sockaddr(),
994 iov := erlang:iovec(),
995 ctrl =>
996 [cmsg_send() |
997 #{level := level() | integer(),
998 type := integer(),
999 data := binary()}]}
1000 Message sent by sendmsg/2,3,4.
1002 Corresponds to a C struct msghdr, see your platform documenta‐
1004 tion for sendmsg(2).
1005 addr:
1007 Optional peer address, used on unconnected sockets. Corre‐
1008 sponds to msg_name and msg_namelen fields of a struct ms‐
1009 ghdr. If not used they are set to NULL, 0.
1010 iov:
1012 Mandatory data as a list of binaries. The msg_iov and
1013 msg_iovlen fields of a struct msghdr.
1014 ctrl:
1016 Optional list of control messages (CMSG). Corresponds to
1017 the msg_control and msg_controllen fields of a struct ms‐
1018 ghdr. If not used they are set to NULL, 0.
1019 The msg_flags field of the struct msghdr is set to 0.
1021 msg_recv() =
1023 #{addr => sockaddr_recv(),
1024 iov := erlang:iovec(),
1025 ctrl :=
1026 [cmsg_recv() |
1027 #{level := level() | integer(),
1028 type := integer(),
1029 data := binary()}],
1030 flags := [msg_flag() | integer()]}
1031 Message returned by recvmsg/1,2,3,5.
1033 Corresponds to a C struct msghdr, see your platform documenta‐
1035 tion for recvmsg(2).
1036 addr:
1038 Optional peer address, used on unconnected sockets. Corre‐
1039 sponds to msg_name and msg_namelen fields of a struct ms‐
1040 ghdr. If NULL the map key is not present.
1041 iov:
1043 Data as a list of binaries. The msg_iov and msg_iovlen
1044 fields of a struct msghdr.
1045 ctrl:
1047 A possibly empty list of control messages (CMSG). Corre‐
1048 sponds to the msg_control and msg_controllen fields of a
1049 struct msghdr.
1050 flags:
1052 Message flags. Corresponds to the msg_flags field of a
1053 struct msghdr. Unknown flags, if any, are returned in one
1054 integer(), last in the containing list.
1055 native_value() = integer() | boolean() | binary()
1057 cmsg_send() =
1059 #{level := socket,
1060 type := timestamp,
1061 data => native_value(),
1062 value => timeval()} |
1063 #{level := socket, type := rights, data := native_value()} |
1064 #{level := socket,
1065 type := credentials,
1066 data := native_value()} |
1067 #{level := ip,
1068 type := tos,
1069 data => native_value(),
1070 value => ip_tos() | integer()} |
1071 #{level := ip,
1072 type := ttl,
1073 data => native_value(),
1074 value => integer()} |
1075 #{level := ip,
1076 type := hoplimit,
1077 data => native_value(),
1078 value => integer()} |
1079 #{level := ipv6,
1080 type := tclass,
1081 data => native_value(),
1082 value => integer()}
1083 Control messages (ancillary messages) accepted by sendmsg/2,3,4.
1085 A control message may for some message types have a value field
1087 with a symbolic value, or a data field with a native value, that
1088 has to be binary compatible what is defined in the platform's
1089 header files.
1090 cmsg_recv() =
1092 #{level := socket,
1093 type := timestamp,
1094 data := binary(),
1095 value => timeval()} |
1096 #{level := socket, type := rights, data := binary()} |
1097 #{level := socket, type := credentials, data := binary()} |
1098 #{level := ip,
1099 type := tos,
1100 data := binary(),
1101 value => ip_tos() | integer()} |
1102 #{level := ip,
1103 type := recvtos,
1104 data := binary(),
1105 value := ip_tos() | integer()} |
1106 #{level := ip,
1107 type := ttl,
1108 data := binary(),
1109 value => integer()} |
1110 #{level := ip,
1111 type := recvttl,
1112 data := binary(),
1113 value := integer()} |
1114 #{level := ip,
1115 type := pktinfo,
1116 data := binary(),
1117 value => ip_pktinfo()} |
1118 #{level := ip,
1119 type := origdstaddr,
1120 data := binary(),
1121 value => sockaddr_recv()} |
1122 #{level := ip,
1123 type := recverr,
1124 data := binary(),
1125 value => extended_err()} |
1126 #{level := ipv6,
1127 type := hoplimit,
1128 data := binary(),
1129 value => integer()} |
1130 #{level := ipv6,
1131 type := pktinfo,
1132 data := binary(),
1133 value => ipv6_pktinfo()} |
1134 #{level := ipv6,
1135 type := recverr,
1136 data := binary(),
1137 value => extended_err()} |
1138 #{level := ipv6,
1139 type := tclass,
1140 data := binary(),
1141 value => integer()}
1142 Control messages (ancillary messages) returned by
1144 recvmsg/1,2,3,5.
1145 A control message has got a data field with a native (binary)
1147 value for the message data, and may also have a decoded value
1148 field if this socket library successfully decoded the data.
1149 icmp_dest_unreach() =
1151 net_unreach | host_unreach | port_unreach | frag_needed |
1152 net_unknown | host_unknown
1153 icmpv6_dest_unreach() =
1155 noroute | adm_prohibited | not_neighbour | addr_unreach |
1156 port_unreach | policy_fail | reject_route
1157 ee_origin() = none | local | icmp | icmp6
1159 extended_err() =
1161 #{error := posix(),
1162 origin := icmp,
1163 type := dest_unreach,
1164 code := icmp_dest_unreach() | 0..255,
1165 info := 0..4294967295,
1166 data := 0..4294967295,
1167 offender := sockaddr_recv()} |
1168 #{error := posix(),
1169 origin := icmp,
1170 type := time_exceeded | 0..255,
1171 code := 0..255,
1172 info := 0..4294967295,
1173 data := 0..4294967295,
1174 offender := sockaddr_recv()} |
1175 #{error := posix(),
1176 origin := icmp6,
1177 type := dest_unreach,
1178 code := icmpv6_dest_unreach() | 0..255,
1179 info := 0..4294967295,
1180 data := 0..4294967295,
1181 offender := sockaddr_recv()} |
1182 #{error := posix(),
1183 origin := icmp6,
1184 type := pkt_toobig | time_exceeded | 0..255,
1185 code := 0..255,
1186 info := 0..4294967295,
1187 data := 0..4294967295,
1188 offender := sockaddr_recv()} |
1189 #{error := posix(),
1190 origin := ee_origin() | 0..255,
1191 type := 0..255,
1192 code := 0..255,
1193 info := 0..4294967295,
1194 data := 0..4294967295,
1195 offender := sockaddr_recv()}
1196 posix() = inet:posix()
1198 The POSIX error codes originates from the OS level socket inter‐
1200 face.
1201
1203 accept(ListenSocket) -> {ok, Socket} | {error, Reason}
1204 accept(ListenSocket, Timeout :: infinity) ->
1206 {ok, Socket} | {error, Reason}
1207 Types:
1209 ListenSocket = Socket = socket()
1211 Reason =
1212 posix() |
1213 closed |
1214 invalid() |
1215 {create_accept_socket, posix()} |
1216 {add_socket, posix()} |
1217 {update_accept_context, posix()}
1218 Accept a connection on a socket.
1220 This call is used with connection oriented socket types (stream
1222 or seqpacket). It returns the first pending incoming connection
1223 for a listen socket, or waits for one to arrive, and returns the
1224 (newly) connected socket.
1225 accept(ListenSocket, Timeout :: integer() >= 0) ->
1227 {ok, Socket} | {error, Reason}
1228 Types:
1230 ListenSocket = Socket = socket()
1232 Reason =
1233 posix() |
1234 closed |
1235 invalid() |
1236 timeout |
1237 {create_accept_socket, posix()} |
1238 {add_socket, posix()} |
1239 {update_accept_context, posix()}
1240 The same as accept/1 but returns {error, timeout} if no connec‐
1242 tion has been accepted after Timeout milliseconds.
1243 Note:
1245 On unix, note that if multiple calls are made only the last call
1246 is "valid":
1247 {select, {select_info, _Handle}} = socket:accept(LSock, nowait),
1249 {error, timeout} = socket:accept(LSock, 500),
1250 .
1251 .
1252 .
1253 In the example above, Handle is not valid once the second (ac‐
1256 cept-) call has been made (the first call is automatically "can‐
1257 celled" and an abort messaage sent, when the second call is
1258 made). After the (accept-) call resulting in the timeout has
1259 been made, there is no longer an active accept call!
1260 accept(ListenSocket, Timeout :: nowait) ->
1263 {ok, Socket} |
1264 {select, SelectInfo} |
1265 {completion, CompletionInfo} |
1266 {error, Reason}
1267 accept(ListenSocket,
1269 Handle :: select_handle() | completion_handle()) ->
1270 {ok, Socket} |
1271 {select, SelectInfo} |
1272 {completion, CompletionInfo} |
1273 {error, Reason}
1274 Types:
1276 ListenSocket = Socket = socket()
1278 SelectInfo = select_info()
1279 CompletionInfo = completion_info()
1280 Reason =
1281 posix() |
1282 closed |
1283 invalid() |
1284 {create_accept_socket, posix()} |
1285 {add_socket, posix()} |
1286 {update_accept_context, posix()}
1287 The same as accept/1 but returns promptly.
1289 When there is no pending connection to return, the function will
1291 return (on Unix ) {select, SelectInfo} or (on Windows ) {comple‐
1292 tion, CompletionInfo}, and the caller will later receive either
1293 one of these messages (depending on the platform) when the
1294 client connects:
1295 select message:
1297 {'$socket', Socket, select, SelectHandle} (with the Selec‐
1298 tHandle contained in the SelectInfo).
1299 A subsequent call to accept/1,2 will then return the socket.
1301 completion message:
1303 {'$socket', Socket, completion, {CompletionHandle, Comple‐
1304 tionStatus}} (with the CompletionHandle contained in the
1305 CompletionInfo).
1306 The result of the accept will be in the CompletionStatus.
1308 If the time-out argument is a Handle, that term will be con‐
1310 tained in a returned SelectInfo or CompletionInfo and the corre‐
1311 sponding select or completion message. The Handle is presumed to
1312 be unique to this call.
1313 If the time-out argument is nowait:
1315 On Unix :
1317 And a SelectInfo is returned, it will contain a select_han‐
1318 dle() generated by the call.
1319 On Windows :
1321 And a CompletionInfo is returned, it will contain a comple‐
1322 tion_handle() generated by the call.
1323 If the caller doesn't want to wait for a connection, it must im‐
1325 mediately call cancel/2 to cancel the operation.
1326 Note:
1328 On unix, note that if multiple calls are made only the last call
1329 is "valid":
1330 {select, {select_info, _Handle1}} = socket:accept(LSock, nowait),
1332 {select, {select_info, _Handle2}} = socket:accept(LSock, nowait),
1333 receive
1334 {'$socket', LSock, select, Handle2} ->
1335 {ok, ASock} = socket:accept(LSock, nowait),
1336 .
1337 .
1338 .
1339 end
1340 In the example above, only Handle2 is valid once the second (ac‐
1343 cept-) call has been made (the first call is automatically "can‐
1344 celled" and an abort messaage sent, when the second call is
1345 made).
1346 bind(Socket, Addr) -> ok | {error, Reason}
1349 Types:
1351 Socket = socket()
1353 Addr = sockaddr() | any | broadcast | loopback
1354 Reason = posix() | closed | invalid()
1355 Bind a name to a socket.
1357 When a socket is created (with open), it has no address assigned
1359 to it. bind assigns the address specified by the Addr argument.
1360 The rules used for name binding vary between domains.
1362 If you bind a socket to an address in for example the 'inet' or
1364 'inet6' address families, with an ephemeral port number (0), and
1365 want to know which port that was chosen, you can find out using
1366 something like: {ok, #{port := Port}} = socket:sockname(Socket)
1367 cancel(Socket, SelectInfo) -> ok | {error, Reason}
1369 Types:
1371 Socket = socket()
1373 SelectInfo = select_info()
1374 Reason = closed | invalid()
1375 Cancel an asynchronous (select) request.
1377 Call this function in order to cancel a previous asynchronous
1379 call to, e.g. recv/3.
1380 An ongoing asynchronous operation blocks the socket until the
1382 operation has been finished in good order, or until it has been
1383 cancelled by this function.
1384 Any other process that tries an operation of the same basic type
1386 (accept / send / recv) will be enqueued and notified with the
1387 regular select mechanism for asynchronous operations when the
1388 current operation and all enqueued before it has been completed.
1389 If SelectInfo does not match an operation in progress for the
1391 calling process, this function returns {error, {invalid, Select‐
1392 Info}}.
1393 cancel(Socket, CompletionInfo) -> ok | {error, Reason}
1395 Types:
1397 Socket = socket()
1399 CompletionInfo = completion_info()
1400 Reason = closed | invalid()
1401 Cancel an asynchronous (completion) request.
1403 Call this function in order to cancel a previous asynchronous
1405 call to, e.g. recv/3.
1406 An ongoing asynchronous operation blocks the socket until the
1408 operation has been finished in good order, or until it has been
1409 cancelled by this function.
1410 Any other process that tries an operation of the same basic type
1412 (accept / send / recv) will be enqueued and notified with the
1413 regular select mechanism for asynchronous operations when the
1414 current operation and all enqueued before it has been completed.
1415 If CompletionInfo does not match an operation in progress for
1417 the calling process, this function returns {error, {invalid,
1418 CompletionInfo}}.
1419 close(Socket) -> ok | {error, Reason}
1421 Types:
1423 Socket = socket()
1425 Reason = posix() | closed | timeout
1426 Closes the socket.
1428 Note:
1430 Note that for e.g. protocol = tcp, most implementations doing a
1431 close does not guarantee that any data sent is delivered to the
1432 recipient before the close is detected at the remote side.
1433 One way to handle this is to use the shutdown function
1435 (socket:shutdown(Socket, write)) to signal that no more data is
1436 to be sent and then wait for the read side of the socket to be
1437 closed.
1438 connect(Socket, SockAddr) -> ok | {error, Reason}
1441 connect(Socket, SockAddr, Timeout :: infinity) ->
1443 ok | {error, Reason}
1444 Types:
1446 Socket = socket()
1448 SockAddr = sockaddr()
1449 Reason =
1450 posix() |
1451 closed |
1452 invalid() |
1453 already | not_bound |
1454 {add_socket, posix()} |
1455 {update_connect_context, posix()}
1456 This function connects the socket to the address specified by
1458 the SockAddr argument, and returns when the connection has been
1459 established or failed.
1460 If a connection attempt is already in progress (by another
1462 process), {error, already} is returned.
1463 Note:
1465 On Windows the socket has to be bound.
1466 connect(Socket, SockAddr, Timeout :: integer() >= 0) ->
1469 ok | {error, Reason}
1470 Types:
1472 Socket = socket()
1474 SockAddr = sockaddr()
1475 Reason =
1476 posix() |
1477 closed |
1478 invalid() |
1479 already | not_bound | timeout |
1480 {add_socket, posix()} |
1481 {update_connect_context, posix()}
1482 The same as connect/2 but returns {error, timeout} if no connec‐
1484 tion has been established after Timeout milliseconds.
1485 Note:
1487 On Windows the socket has to be bound.
1488 Note that when this call has returned {error, timeout} the con‐
1490 nection state of the socket is uncertain since the platform's
1491 network stack may complete the connection at any time, up to
1492 some platform specific time-out.
1493 Repeating a connection attempt towards the same address would be
1495 ok, but towards a different address could end up with a connec‐
1496 tion to either address.
1497 The safe play would be to close the socket and start over.
1499 Also note that all this applies to cancelling a connect call
1501 with a no-wait time-out described below.
1502 connect(Socket, SockAddr, Timeout :: nowait) ->
1505 ok |
1506 {select, SelectInfo} |
1507 {completion, CompletionInfo} |
1508 {error, Reason}
1509 connect(Socket, SockAddr,
1511 Handle :: select_handle() | completion_handle()) ->
1512 ok |
1513 {select, SelectInfo} |
1514 {completion, CompletionInfo} |
1515 {error, Reason}
1516 Types:
1518 Socket = socket()
1520 SockAddr = sockaddr()
1521 SelectInfo = select_info()
1522 CompletionInfo = completion_info()
1523 Reason =
1524 posix() |
1525 closed |
1526 invalid() |
1527 already | not_bound |
1528 {add_socket, posix()} |
1529 {update_connect_context, posix()}
1530 The same as connect/2 but returns promptly.
1532 If it is not possible to immediately establish a connection, the
1534 function will return {select, SelectInfo}, and the caller will
1535 later receive a select message, {'$socket', Socket, select, Se‐
1536 lectHandle} ( with the SelectHandle contained in the SelectInfo
1537 ) when the connection has been completed or failed. A subsequent
1538 call to connect/1 will then finalize the connection and return
1539 the result.
1540 If the time-out argument is SelectHandle, that term will be con‐
1542 tained in a returned SelectInfo and the corresponding select
1543 message. The SelectHandle is presumed to be unique to this call.
1544 If the time-out argument is nowait, and a SelectInfo is re‐
1546 turned, it will contain a select_handle() generated by the call.
1547 If the caller doesn't want to wait for the connection to com‐
1549 plete, it must immediately call cancel/2 to cancel the opera‐
1550 tion.
1551 Note:
1553 On Windows the socket has to be bound.
1554 connect(Socket) -> ok | {error, Reason}
1557 Types:
1559 Socket = socket()
1561 Reason = posix() | closed | invalid()
1562 This function finalizes a connection setup on a socket, after
1564 calling connect(_, _, nowait | select_handle()) that returned
1565 {select, SelectInfo}, and receiving the select message
1566 {'$socket', Socket, select, SelectHandle}, and returns whether
1567 the connection setup was successful or not.
1568 Instead of calling this function, for backwards compatibility,
1570 it is allowed to call connect/2,3, but that incurs more overhead
1571 since the connect address and time-out are processed in vain.
1572 Note:
1574 Not used on Windows .
1575 cancel_monitor(MRef) -> boolean()
1578 Types:
1580 MRef = reference()
1582 If MRef is a reference that the calling process obtained by
1584 calling monitor/1, this monitor is turned off. If the monitoring
1585 is already turned off, nothing happens.
1586 The returned value is one of the following:
1588 true:
1590 The monitor was found and removed. In this case, no 'DOWN'
1591 message corresponding to this monitor has been delivered and
1592 will not be delivered.
1593 false:
1595 The monitor was not found and could not be removed. This
1596 probably because a 'DOWN' message corresponding to this mon‐
1597 itor has already been placed in the caller message queue.
1598 Failure: It is an error if MRef refers to a monitor started by
1600 another process.
1601 getopt(X1 :: socket(),
1603 SocketOption :: {Level :: otp, Opt :: otp_socket_option()}) ->
1604 {ok, Value :: term()} | {error, invalid() | closed}
1605 Gets a socket option from the protocol level otp, which is this
1607 implementation's level above the OS protocol layers.
1608 See the type otp_socket_option() for a description of the op‐
1610 tions on this level.
1611 getopt(X1 :: socket(), SocketOption :: socket_option()) ->
1613 {ok, Value :: term()} |
1614 {error, posix() | invalid() | closed}
1615 Gets a socket option from one of the OS's protocol levels. See
1617 the type socket_option() for which options that this implementa‐
1618 tion knows about, how they are related to option names in the
1619 OS, and if there are known peculiarities with any of them.
1620 What options are valid depends on what kind of socket it is (do‐
1622 main(), type() and protocol()).
1623 See the socket options chapter of the users guide for more
1625 info.
1626 Note:
1628 Not all options are valid, nor possible to get, on all plat‐
1629 forms. That is, even if "we" support an option; it does not mean
1630 that the underlying OS does.
1631 getopt(Socket, Level, Opt) -> ok | {error, Reason}
1634 Types:
1636 Socket = socket()
1638 Reason = inet:posix() | invalid() | closed
1639 Backwards compatibility function.
1641 The same as getopt(Socket, {Level, Opt})
1643 getopt_native(X1 :: socket(),
1645 SocketOption ::
1646 socket_option() |
1647 {Level :: level() | (NativeLevel :: integer()),
1648 NativeOpt :: integer()},
1649 ValueType :: integer) ->
1650 {ok, Value :: integer()} |
1651 {error, posix() | invalid() | closed}
1652 getopt_native(X1 :: socket(),
1654 SocketOption ::
1655 socket_option() |
1656 {Level :: level() | (NativeLevel :: integer()),
1657 NativeOpt :: integer()},
1658 ValueType :: boolean) ->
1659 {ok, Value :: boolean()} |
1660 {error, posix() | invalid() | closed}
1661 getopt_native(X1 :: socket(),
1663 SocketOption ::
1664 socket_option() |
1665 {Level :: level() | (NativeLevel :: integer()),
1666 NativeOpt :: integer()},
1667 ValueSize :: integer() >= 0) ->
1668 {ok, Value :: binary()} |
1669 {error, posix() | invalid() | closed}
1670 getopt_native(X1 :: socket(),
1672 SocketOption ::
1673 socket_option() |
1674 {Level :: level() | (NativeLevel :: integer()),
1675 NativeOpt :: integer()},
1676 ValueSpec :: binary()) ->
1677 {ok, Value :: binary()} |
1678 {error, posix() | invalid() | closed}
1679 Gets a socket option that may be unknown to our implementation,
1681 or that has a type not compatible with our implementation, that
1682 is; in "native mode".
1683 The socket option may be specified with an ordinary socket_op‐
1685 tion() tuple, with a known Level = level() and an integer Na‐
1686 tiveOpt, or with both an integer NativeLevel and NativeOpt.
1687 How to decode the option value has to be specified either with
1689 ValueType, by specifying the ValueSize for a binary() that will
1690 contain the fetched option value, or by specifying a binary()
1691 ValueSpec that will be copied to a buffer for the getsockopt()
1692 call to write the value in which will be returned as a new bi‐
1693 nary().
1694 If ValueType is integer a C type (int) will be fetched, if it is
1696 boolean a C type (int) will be fetched and converted into a
1697 boolean() according to the C implementation.
1698 What options are valid depends on what kind of socket it is (do‐
1700 main(), type() and protocol()).
1701 The integer values for NativeLevel and NativeOpt as well as the
1703 Value encoding has to be deduced from the header files for the
1704 running system.
1705 i() -> ok
1707 Print all sockets in table format in the erlang shell.
1709 i(InfoKeys) -> ok
1711 Types:
1713 InfoKeys = info_keys()
1715 Print all sockets in table format in the erlang shell. What in‐
1717 formation is included is defined by InfoKeys.
1718 i(Domain) -> ok
1720 Types:
1722 Domain = inet | inet6 | local
1724 Print a selection, based on domain, of the sockets in table for‐
1726 mat in the erlang shell.
1727 i(Proto) -> ok
1729 Types:
1731 Proto = sctp | tcp | udp
1733 Print a selection, based on protocol, of the sockets in table
1735 format in the erlang shell.
1736 i(Type) -> ok
1738 Types:
1740 Type = dgram | seqpacket | stream
1742 Print a selection, based on type, of the sockets in table format
1744 in the erlang shell.
1745 i(Domain, InfoKeys) -> ok
1747 Types:
1749 Domain = inet | inet6 | local
1751 InfoKeys = info_keys()
1752 Print a selection, based on domain, of the sockets in table for‐
1754 mat in the erlang shell. What information is included is defined
1755 by InfoKeys.
1756 i(Proto, InfoKeys) -> ok
1758 Types:
1760 Proto = sctp | tcp | udp
1762 InfoKeys = info_keys()
1763 Print a selection, based on domain, of the sockets in table for‐
1765 mat in the erlang shell. What information is included is defined
1766 by InfoKeys.
1767 i(Type, InfoKeys) -> ok
1769 Types:
1771 Type = dgram | seqpacket | stream
1773 InfoKeys = info_keys()
1774 Print a selection, based on type, of the sockets in table format
1776 in the erlang shell. What information is included is defined by
1777 InfoKeys.
1778 info() -> info()
1780 Get miscellaneous info about the socket library.
1782 The function returns a map with each info item as a key-value
1784 binding.
1785 Note:
1787 In order to ensure data integrity, mutex'es are taken when
1788 needed. So, do not call this function often.
1789 info(Socket) -> socket_info()
1792 Types:
1794 Socket = socket()
1796 Get miscellaneous info about the socket.
1798 The function returns a map with each info item as a key-value
1800 binding. It reflects the "current" state of the socket.
1801 Note:
1803 In order to ensure data integrity, mutex'es are taken when
1804 needed. So, do not call this function often.
1805 ioctl(Socket, GetRequest :: gifconf) ->
1808 {ok, IFConf :: [#{name := string, addr := sockaddr()}]} |
1809 {error, Reason}
1810 ioctl(Socket, GetRequest :: nread | nwrite | nspace) ->
1812 {ok, NumBytes :: integer() >= 0} | {error, Reason}
1813 ioctl(Socket, GetRequest :: atmark) ->
1815 {ok, Available :: boolean()} | {error, Reason}
1816 ioctl(Socket, GetRequest :: tcp_info) ->
1818 {ok, Info :: map()} | {error, Reason}
1819 Types:
1821 Socket = socket()
1823 Reason = posix() | closed
1824 Retrieve socket (device) parameters.
1826 This function retrieves a specific parameter, according to Ge‐
1828 tRequest argument.
1829 gifconf:
1831 Return a list of interface (transport layer) addresses.
1832 Result, a list of interfaces, map with name and address.
1834 nread:
1836 Get the number of bytes that are immediately available for
1837 reading.
1838 Result, number of bytes, is a integer().
1840 nwrite:
1842 The number of bytes in the send queue.
1843 Result, number of bytes, is a integer().
1845 nspace:
1847 Get the free space in the send queue.
1848 Result, number of bytes, is a integer().
1850 atmark:
1852 Test if there is oob (out-of-bound) data waiting to be read.
1853 Result is a boolean().
1855 tcp_info:
1857 Return miscellaneous TCP related information for a connected
1858 socket.
1859 Result is a map().
1861 Note:
1863 To see if a ioctl request is supported on the current platform:
1864 Request = nread,
1866 {ok, true} = socket:is_supported(ioctl_requests, Request),
1867 .
1868 .
1869 .
1870 ioctl(Socket, GetRequest, NameOrIndex) ->
1874 {ok, Result} | {error, Reason}
1875 Types:
1877 Socket = socket()
1879 GetRequest =
1880 gifname | gifindex | gifaddr | gifdstaddr | gifbrdaddr |
1881 gifnetmask | gifhwaddr | gifmtu | giftxqlen | gifflags |
1882 tcp_info
1883 NameOrIndex = string() | integer()
1884 Result = term()
1885 Reason = posix() | closed
1886 Retrieve socket (device) parameters.
1888 This function retrieves a specific parameter, according to Ge‐
1890 tRequest argument. The third argument is a the (lookup) "key",
1891 identifying the interface (usually the name of the interface) or
1892 a command to set.
1893 gifname:
1895 Get the name of the interface with the specified index (in‐
1896 teger()).
1897 Result, name of the interface, is a string().
1899 gifindex:
1901 Get the index of the interface with the specified name.
1902 Result, interface index, is a integer().
1904 gifaddr:
1906 Get the address of the interface with the specified name.
1907 Result, address of the interface, is a socket:sockaddr().
1908 gifdstaddr:
1910 Get the destination address of the point-to-point interface
1911 with the specified name.
1912 Result, destination address of the interface, is a
1914 socket:sockaddr().
1915 gifbrdaddr:
1917 Get the droadcast address for the interface with the speci‐
1918 fied name.
1919 Result, broadcast address of the interface, is a
1921 socket:sockaddr().
1922 gifnetmask:
1924 Get the network mask for the interface with the specified
1925 name.
1926 Result, network mask of the interface, is a socket:sock‐
1928 addr().
1929 gifhwaddr:
1931 Get the hardware address for the interface with the speci‐
1932 fied name.
1933 Result, hardware address of the interface, is a socket:sock‐
1935 addr(). The family field contains the 'ARPHRD' device type
1936 (or an integer).
1937 gifmtu:
1939 Get the MTU (Maximum Transfer Unit) for the interface with
1940 the specified name.
1941 Result, MTU of the interface, is an integer().
1943 giftxqlen:
1945 Get the transmit queue length of the interface with the
1946 specified name.
1947 Result, transmit queue length of the interface, is an inte‐
1949 ger().
1950 gifflags:
1952 Get the active flag word of the interface with the specified
1953 name.
1954 Result, the active flag word of the interface, is an list of
1956 socket:ioctl_device_flag() | integer().
1957 ioctl(Socket, SetRequest, Value) -> ok | {error, Reason}
1959 Types:
1961 Socket = socket()
1963 SetRequest = rcvall
1964 Value = off | on | iplevel
1965 Reason = posix() | closed
1966 Set socket (device) parameters.
1968 This function sets a specific parameter, according to SetRequest
1970 argument. The third argument is the value to set.
1971 rcvall:
1973 Enables (or disables) a socket to receive all IPv4 or IPv6
1974 packages passing through a network interface.
1975 The socket has to be either one of:
1977 An IPv4 socket:
1979 Created with the address family of inet, socket type of
1980 raw and protocol set to ip.
1981 An IPv6 socket:
1983 Created with the address family of inet6, socket type of
1984 raw and protocol set to ipv6.
1985 The socket must also be bound to an (explicit) local IPv4 or
1987 IPv6 interface (any not allowed).
1988 Setting this IOCTL requires admin privileges.
1990 ioctl(Socket, SetRequest, Value) -> ok | {error, Reason}
1992 Types:
1994 Socket = socket()
1996 SetRequest = rcvall_igmpmcast | rcvall_mcast
1997 Value = off | on
1998 Reason = posix() | closed
1999 Set socket (device) parameters.
2001 This function sets a specific parameter, according to SetRequest
2003 argument. The third argument is the value to set.
2004 rcvall_igmpmcall:
2006 Enables (or disables) a socket to receive IGMP multicast IP
2007 traffic, without receiving any other IP traffic.
2008 The socket has to be created with the address family of
2010 inet, socket type of raw and protocol set to igmp.
2011 The socket must also be bound to an (explicit) local inter‐
2013 face (any not allowed).
2014 Must have a sufficiently large buffer.
2016 Setting this IOCTL requires admin privileges.
2018 rcvall_mcall:
2020 Enables (or disables) a socket to receive all multicast IP
2021 traffic (as in; all IP packets destined for IP addresses in
2022 the range of 224.0.0.0 to 239.255.255.255).
2023 The socket has to be created with the address family of
2025 inet, socket type of raw and protocol set to udp.
2026 The socket must also be bound to an (explicit) local inter‐
2028 face (any not allowed). And bind to port zero
2029 Must have a sufficiently large buffer.
2031 Setting this IOCTL requires admin privileges.
2033 ioctl(Socket, SetRequest, Name, Value) -> ok | {error, Reason}
2035 Types:
2037 Socket = socket()
2039 SetRequest =
2040 sifflags | sifaddr | sifdstaddr | sifbrdaddr | sifnetmask
2041 |
2042 sifhwaddr | gifmtu | siftxqlen
2043 Name = string()
2044 Value = term()
2045 Reason = posix() | closed
2046 Set socket (device) parameters. This function sets a specific
2048 parameter, according to SetRequest argument. The third argument
2049 is the "key", identifying the interface (usually the name of the
2050 interface), and the fourth is the "new" value.
2051 These are privileged operation's.
2053 sifflags:
2055 Set the the active flag word, #{Flag => boolean()}, of the
2056 interface with the specified name.
2057 Each flag to be changed, should be added to the value map,
2059 with the value 'true' if the flag (Flag) should be set and
2060 'false' if the flag should be reset.
2061 sifaddr:
2063 Set the address, sockaddr(), of the interface with the spec‐
2064 ified name.
2065 sifdstaddr:
2067 Set the destination address, sockaddr(), of a point-to-point
2068 interface with the specified name.
2069 sifbrdaddr:
2071 Set the broadcast address, sockaddr(), of the interface with
2072 the specified name.
2073 sifnetmask:
2075 Set the network mask, sockaddr(), of the interface with the
2076 specified name.
2077 sifmtu:
2079 Set the MTU (Maximum Transfer Unit), integer(), for the in‐
2080 terface with the specified name.
2081 siftxqlen:
2083 Set the transmit queue length, integer(), of the interface
2084 with the specified name.
2085 is_supported(Key1 :: term()) -> boolean()
2087 is_supported(Key1 :: term(), Key2 :: term()) -> boolean()
2089 This function retrieves information about what the platform sup‐
2091 ports, such as if SCTP is supported, or if a socket options are
2092 supported.
2093 For keys other than the known false is returned. Note that in a
2095 future version or on a different platform there might be more
2096 supported items.
2097 This functions returns a boolean corresponding to what sup‐
2099 ports/0-2 reports for the same Key1 (and Key2).
2100 listen(Socket) -> ok | {error, Reason}
2102 listen(Socket, Backlog) -> ok | {error, Reason}
2104 Types:
2106 Socket = socket()
2108 Backlog = integer()
2109 Reason = posix() | closed
2110 Listen for connections on a socket.
2112 Note:
2114 On Windows the socket has to be bound.
2115 monitor(Socket) -> reference()
2118 Types:
2120 Socket = socket()
2122 Start monitor the socket Socket.
2124 If the monitored socket does not exist or when the monitor is
2126 triggered, a 'DOWN' message is sent that has the following pat‐
2127 tern:
2128 {'DOWN', MonitorRef, socket, Object, Info}
2130 In the monitor message MonitorRef and Type are the same as de‐
2133 scribed earlier, and:
2134 Object:
2136 The monitored entity, socket, which triggered the event.
2137 Info:
2139 Either the termination reason of the socket or nosock
2140 (socket Socket did not exist at the time of monitor cre‐
2141 ation).
2142 Making several calls to socket:monitor/1 for the same Socket is
2144 not an error; it results in as many independent monitoring in‐
2145 stances.
2146 number_of() -> integer() >= 0
2148 Returns the number of active sockets.
2150 open(FD) -> {ok, Socket} | {error, Reason}
2152 open(FD, Opts) -> {ok, Socket} | {error, Reason}
2154 Types:
2156 FD = integer()
2158 Opts =
2159 #{domain => domain() | integer(),
2160 type => type() | integer(),
2161 protocol => default | protocol() | integer(),
2162 dup => boolean(),
2163 debug => boolean(),
2164 use_registry => boolean()}
2165 Socket = socket()
2166 Reason = posix() | domain | type | protocol
2167 Creates an endpoint (socket) for communication based on an al‐
2169 ready existing file descriptor. The function attempts to re‐
2170 trieve domain, type and protocol from the system. This is how‐
2171 ever not possible on all platforms, and they should then be
2172 specified in Opts.
2173 The Opts argument is intended for providing extra information
2175 for the open call:
2176 domain:
2178 Which protocol domain is the descriptor of. See also
2179 open/2,3,4.
2180 type:
2182 Which protocol type type is the descriptor of.
2183 See also open/2,3,4.
2185 protocol:
2187 Which protocol is the descriptor of. The atom default is
2188 equivalent to the integer protocol number 0 which means the
2189 default protocol for a given domain and type.
2190 If the protocol can not be retrieved from the platform for
2192 the socket, and protocol is not specified, the default pro‐
2193 tocol is used, which may or may not be correct.
2194 See also open/2,3,4.
2196 dup:
2198 Shall the provided descriptor be duplicated (dup) or not.
2199 Defaults to true.
2200 debug:
2202 Enable or disable debug during the open call.
2203 Defaults to false.
2204 use_registry:
2206 Enable or disable use of the socket registry for this
2207 socket. This overrides the global value.
2208 Defaults to the global value, see use_registry/1.
2209 Note:
2211 This function should be used with care!
2212 On some platforms it is necessary to provide domain, type and
2214 protocol since they cannot be retrieved from the platform.
2215 open(Domain, Type) -> {ok, Socket} | {error, Reason}
2218 open(Domain, Type, Opts) -> {ok, Socket} | {error, Reason}
2220 Types:
2222 Domain = domain() | integer()
2224 Type = type() | integer()
2225 Opts = map()
2226 Socket = socket()
2227 Reason = posix() | protocol
2228 Creates an endpoint (socket) for communication.
2230 The same as open(Domain, Type, default) and open(Domain, Type,
2232 default, Opts) respectively.
2233 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
2235 open(Domain, Type, Protocol, Opts) ->
2237 {ok, Socket} | {error, Reason}
2238 Types:
2240 Domain = domain() | integer()
2242 Type = type() | integer()
2243 Protocol = default | protocol() | integer()
2244 Opts =
2245 #{netns => string(),
2246 debug => boolean(),
2247 use_registry => boolean()}
2248 Socket = socket()
2249 Reason = posix() | protocol
2250 Creates an endpoint (socket) for communication.
2252 Domain and Type may be integer()s, as defined in the platform's
2254 header files. The same goes for Protocol as defined in the plat‐
2255 form's services(5) database. See also the OS man page for the
2256 library call socket(2).
2257 Note:
2259 For some combinations of Domain and Type the platform has got a
2260 default protocol that can be selected with Protocol = default,
2261 and the platform may allow or require selecting the default pro‐
2262 tocol, a specific protocol, or either.
2263 Examples:
2265 socket:open(inet, stream, tcp):
2267 It is common that for protocol domain and type inet,stream
2268 it is allowed to select the tcp protocol although that
2269 mostly is the default.
2270 socket:open(local, dgram):
2272 It is common that for the protocol domain local it is manda‐
2273 tory to not select a protocol, that is; to select the de‐
2274 fault protocol.
2275 The Opts argument is intended for "other" options. The supported
2278 option(s) are described below:
2279 netns: string():
2281 Used to set the network namespace during the open call. Only
2282 supported on the Linux platform.
2283 debug: boolean():
2285 Enable or disable debug during the open call.
2286 Defaults to false.
2287 use_registry: boolean():
2289 Enable or disable use of the socket registry for this
2290 socket. This overrides the global value.
2291 Defaults to the global value, see use_registry/1.
2292 peername(Socket) -> {ok, SockAddr} | {error, Reason}
2294 Types:
2296 Socket = socket()
2298 SockAddr = sockaddr_recv()
2299 Reason = posix() | closed
2300 Returns the address of the peer connected to the socket.
2302 recv(Socket) ->
2304 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2305 recv(Socket, Flags) ->
2307 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2308 recv(Socket, Length) ->
2310 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2311 recv(Socket, Flags, Timeout :: infinity) ->
2313 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2314 recv(Socket, Length, Flags) ->
2316 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2317 recv(Socket, Length, Timeout :: infinity) ->
2319 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2320 recv(Socket, Length, Flags, Timeout :: infinity) ->
2322 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2323 Types:
2325 Socket = socket()
2327 Length = integer() >= 0
2328 Flags = [msg_flag() | integer()]
2329 Data = binary()
2330 Reason = posix() | closed | invalid()
2331 Receives data from a socket, waiting for it to arrive.
2333 The argument Length specifies how many bytes to receive, with
2335 the special case 0 meaning "all available".
2336 For a socket of type stream this call will not return until all
2338 requested data can be delivered, or if "all available" data was
2339 requested when the first data chunk arrives.
2340 The message Flags may be symbolic msg_flag()s and/or integer()s,
2342 as in the platform's appropriate header files. The values of all
2343 symbolic flags and integers are or:ed together.
2344 When there is a socket error this function returns {error, Rea‐
2346 son}, or if some data arrived before the error; {error, {Reason,
2347 Data}}.
2348 recv(Socket, Flags, Timeout :: integer() >= 0) ->
2350 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2351 recv(Socket, Length, Timeout :: integer() >= 0) ->
2353 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2354 recv(Socket, Length, Flags, Timeout :: integer() >= 0) ->
2356 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2357 Types:
2359 Socket = socket()
2361 Length = integer() >= 0
2362 Flags = [msg_flag() | integer()]
2363 Data = binary()
2364 Reason = posix() | closed | invalid() | timeout
2365 Receives data from a socket, waiting at most Timeout millisec‐
2367 onds for it to arrive.
2368 The same as infinite time-out recv/1,2,3,4 but returns {error,
2370 timeout} or {error, {timeout, Data}} after Timeout milliseconds,
2371 if the requested data has not been delivered.
2372 recv(Socket, Flags, Handle :: nowait) ->
2374 {ok, Data} |
2375 {select, SelectInfo} |
2376 {select, {SelectInfo, Data}} |
2377 {completion, CompletionInfo} |
2378 {error, Reason} |
2379 {error, {Reason, Data}}
2380 recv(Socket, Flags,
2382 Handle :: select_handle() | completion_handle()) ->
2383 {ok, Data} |
2384 {select, SelectInfo} |
2385 {select, {SelectInfo, Data}} |
2386 {completion, CompletionInfo} |
2387 {error, Reason} |
2388 {error, {Reason, Data}}
2389 recv(Socket, Length, Handle :: nowait) ->
2391 {ok, Data} |
2392 {select, SelectInfo} |
2393 {select, {SelectInfo, Data}} |
2394 {completion, CompletionInfo} |
2395 {error, Reason} |
2396 {error, {Reason, Data}}
2397 recv(Socket, Length,
2399 Handle :: select_handle() | completion_handle()) ->
2400 {ok, Data} |
2401 {select, SelectInfo} |
2402 {select, {SelectInfo, Data}} |
2403 {completion, CompletionInfo} |
2404 {error, Reason} |
2405 {error, {Reason, Data}}
2406 recv(Socket, Length, Flags, Handle :: nowait) ->
2408 {ok, Data} |
2409 {select, SelectInfo} |
2410 {select, {SelectInfo, Data}} |
2411 {completion, CompletionInfo} |
2412 {error, Reason} |
2413 {error, {Reason, Data}}
2414 recv(Socket, Length, Flags,
2416 Handle :: select_handle() | completion_handle()) ->
2417 {ok, Data} |
2418 {select, SelectInfo} |
2419 {select, {SelectInfo, Data}} |
2420 {completion, CompletionInfo} |
2421 {error, Reason} |
2422 {error, {Reason, Data}}
2423 Types:
2425 Socket = socket()
2427 Length = integer() >= 0
2428 Flags = [msg_flag() | integer()]
2429 Data = binary()
2430 SelectInfo = select_info()
2431 CompletionInfo = completion_info()
2432 Reason = posix() | closed | invalid()
2433 Receives data from a socket, but returns a select or completion
2435 continuation if the data could not be returned immediately.
2436 The same as infinite time-out recv/1,2,3,4 but if the data can
2438 be delivered immediately, the function returns (on Unix ) {se‐
2439 lect, SelectInfo} or (on Windows ) {completion, CompletionInfo},
2440 and the caller will then receive one of these messages:
2441 select message:
2443 {'$socket', Socket, select, SelectHandle} (with the Selec‐
2444 tHandle that was contained in the SelectInfo) when data has
2445 arrived.
2446 A subsequent call to recv/1,2,3,4 will then return the data.
2448 completion message:
2450 {'$socket', Socket, completion, {CompletionHandle, Comple‐
2451 tionStatus}} (with the CompletionHandle contained in the
2452 CompletionInfo).
2453 The result of the receive will be in the CompletionStatus.
2455 If Handle is a select_handle() or completion_handle(), that term
2457 will be contained in a returned SelectInfo or CompletionInfo and
2458 the corresponding (select or completion) message. The Handle is
2459 presumed to be unique to this call.
2460 If the time-out argument is nowait, and a SelectInfo or Comple‐
2462 tionInfo is returned, it will contain a select_handle() or com‐
2463 pletion_handle() generated by the call.
2464 Note that for a socket of type stream (on Unix ), if Length > 0
2466 and only part of that amount of data is available, the function
2467 will return {ok, {Data, SelectInfo}} with partial data. If the
2468 caller doesn't want to wait for more data, it must immediately
2469 call cancel/2 to cancel the operation.
2470 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
2472 recvfrom(Socket, Flags) -> {ok, {Source, Data}} | {error, Reason}
2474 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
2476 recvfrom(Socket, Flags, Timeout :: infinity) ->
2478 {ok, {Source, Data}} | {error, Reason}
2479 recvfrom(Socket, BufSz, Flags) ->
2481 {ok, {Source, Data}} | {error, Reason}
2482 recvfrom(Socket, BufSz, Timeout :: infinity) ->
2484 {ok, {Source, Data}} | {error, Reason}
2485 recvfrom(Socket, BufSz, Flags, Timeout :: infinity) ->
2487 {ok, {Source, Data}} | {error, Reason}
2488 Types:
2490 Socket = socket()
2492 BufSz = integer() >= 0
2493 Flags = [msg_flag() | integer()]
2494 Source = sockaddr_recv()
2495 Data = binary()
2496 Reason = posix() | closed | invalid()
2497 Receive a message from a socket, waiting for it to arrive.
2499 The function returns when a message is received, or when there
2501 is a socket error. Argument BufSz specifies the number of bytes
2502 for the receive buffer. If the buffer size is too small, the
2503 message will be truncated.
2504 If BufSz is not specified or 0, a default buffer size is used,
2506 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2507 If it is impossible to know the appropriate buffer size, it may
2509 be possible to use the receive message flag peek. When this flag
2510 is used, the message is not "consumed" from the underlying buf‐
2511 fers, so another recvfrom/1,2,3,4 call is needed, possibly with
2512 an adjusted buffer size.
2513 The message Flags may be symbolic msg_flag()s and/or integer()s,
2515 as in the platform's appropriate header files. The values of all
2516 symbolic flags and integers are or:ed together.
2517 recvfrom(Socket, Flags, Timeout :: integer() >= 0) ->
2519 {ok, {Source, Data}} | {error, Reason}
2520 recvfrom(Socket, BufSz, Timeout :: integer() >= 0) ->
2522 {ok, {Source, Data}} | {error, Reason}
2523 recvfrom(Socket, BufSz, Flags, Timeout :: integer() >= 0) ->
2525 {ok, {Source, Data}} | {error, Reason}
2526 Types:
2528 Socket = socket()
2530 BufSz = integer() >= 0
2531 Flags = [msg_flag() | integer()]
2532 Source = sockaddr_recv()
2533 Data = binary()
2534 Reason = posix() | closed | invalid() | timeout
2535 Receives a message from a socket, waiting at most Timeout mil‐
2537 liseconds for it to arrive.
2538 The same as infinite time-out recvfrom/1,2,3,4 but returns {er‐
2540 ror, timeout} after Timeout milliseconds, if no message has been
2541 delivered.
2542 recvfrom(Socket, Flags, Handle :: nowait) ->
2544 {ok, {Source, Data}} |
2545 {select, SelectInfo} |
2546 {completion, CompletionInfo} |
2547 {error, Reason}
2548 recvfrom(Socket, Flags,
2550 Handle :: select_handle() | completion_handle()) ->
2551 {ok, {Source, Data}} |
2552 {select, SelectInfo} |
2553 {completion, CompletionInfo} |
2554 {error, Reason}
2555 recvfrom(Socket, BufSz, Handle :: nowait) ->
2557 {ok, {Source, Data}} |
2558 {select, SelectInfo} |
2559 {completion, CompletionInfo} |
2560 {error, Reason}
2561 recvfrom(Socket, BufSz,
2563 Handle :: select_handle() | completion_handle()) ->
2564 {ok, {Source, Data}} |
2565 {select, SelectInfo} |
2566 {completion, CompletionInfo} |
2567 {error, Reason}
2568 recvfrom(Socket, BufSz, Flags, Handle :: nowait) ->
2570 {ok, {Source, Data}} |
2571 {select, SelectInfo} |
2572 {completion, CompletionInfo} |
2573 {error, Reason}
2574 recvfrom(Socket, BufSz, Flags,
2576 Handle :: select_handle() | completion_handle()) ->
2577 {ok, {Source, Data}} |
2578 {select, SelectInfo} |
2579 {completion, CompletionInfo} |
2580 {error, Reason}
2581 Types:
2583 Socket = socket()
2585 BufSz = integer() >= 0
2586 Flags = [msg_flag() | integer()]
2587 Source = sockaddr_recv()
2588 Data = binary()
2589 SelectInfo = select_info()
2590 CompletionInfo = completion_info()
2591 Reason = posix() | closed | invalid()
2592 Receives a message from a socket, but returns a select continua‐
2594 tion or a completion term if no message could be returned imme‐
2595 diately.
2596 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2598 sage can be delivered immediately, the function returns (on
2599 /Unix ) {select, SelectInfo} or (on Windows ) {completion, Com‐
2600 pletionInfo}, and the caller will then receive one of these mes‐
2601 sages:
2602 select message:
2604 {'$socket', Socket, select, SelectHandle} (with the Selec‐
2605 tHandle that was contained in the SelectInfo) when data has
2606 arrived.
2607 A subsequent call to recvfrom/1,2,3,4 will then return the
2609 message.
2610 completion message:
2612 {'$socket', Socket, completion, {CompletionHandle, Comple‐
2613 tionStatus}} (with the CompletionHandle contained in the
2614 CompletionInfo).
2615 The result of the receive will be in the CompletionStatus.
2617 If the Handle is a select_handle() or completion_handle(), that
2619 term will be contained in a returned SelectInfo or Completion‐
2620 Info and the corresponding (select or completion) message. The
2621 Handle is presumed to be unique to this call.
2622 If the time-out argument is nowait, and a SelectInfo or Comple‐
2624 tionInfo is returned, it will contain a select_handle() or com‐
2625 pletion_handle() generated by the call.
2626 If the caller doesn't want to wait for the data, it must immedi‐
2628 ately call cancel/2 to cancel the operation.
2629 recvmsg(Socket) -> {ok, Msg} | {error, Reason}
2631 recvmsg(Socket, Flags) -> {ok, Msg} | {error, Reason}
2633 recvmsg(Socket, Timeout :: infinity) ->
2635 {ok, Msg} | {error, Reason}
2636 recvmsg(Socket, Flags, Timeout :: infinity) ->
2638 {ok, Msg} | {error, Reason}
2639 recvmsg(Socket, BufSz, CtrlSz) -> {ok, Msg} | {error, Reason}
2641 recvmsg(Socket, BufSz, CtrlSz, Timeout :: infinity) ->
2643 {ok, Msg} | {error, Reason}
2644 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: infinity) ->
2646 {ok, Msg} | {error, Reason}
2647 Types:
2649 Socket = socket()
2651 BufSz = CtrlSz = integer() >= 0
2652 Flags = [msg_flag() | integer()]
2653 Msg = msg_recv()
2654 Reason = posix() | closed | invalid()
2655 Receive a message from a socket, waiting for it to arrive.
2657 The function returns when a message is received, or when there
2659 is a socket error. Arguments BufSz and CtrlSz specifies the num‐
2660 ber of bytes for the receive buffer and the control message buf‐
2661 fer. If the buffer size(s) is(are) too small, the message and/or
2662 control message list will be truncated.
2663 If BufSz is not specified or 0, a default buffer size is used,
2665 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2666 The same applies to CtrlSz and socket:setopt(Socket, {otp,recvc‐
2667 trlbuf}, CtrlSz).
2668 If it is impossible to know the appropriate buffer size, it may
2670 be possible to use the receive message flag peek. When this flag
2671 is used, the message is not "consumed" from the underlying buf‐
2672 fers, so another recvfrom/1,2,3,4,5 call is needed, possibly
2673 with an adjusted buffer size.
2674 The message Flags may be symbolic msg_flag()s and/or integer()s,
2676 as in the platform's appropriate header files. The values of all
2677 symbolic flags and integers are or:ed together.
2678 recvmsg(Socket, Timeout :: integer() >= 0) ->
2680 {ok, Msg} | {error, Reason}
2681 recvmsg(Socket, Flags, Timeout :: integer() >= 0) ->
2683 {ok, Msg} | {error, Reason}
2684 recvmsg(Socket, BufSz, CtrlSz, Timeout :: integer() >= 0) ->
2686 {ok, Msg} | {error, Reason}
2687 recvmsg(Socket, BufSz, CtrlSz, Flags,
2689 Timeout :: integer() >= 0) ->
2690 {ok, Msg} | {error, Reason}
2691 Types:
2693 Socket = socket()
2695 BufSz = CtrlSz = integer() >= 0
2696 Flags = [msg_flag() | integer()]
2697 Msg = msg_recv()
2698 Reason = posix() | closed | invalid() | timeout
2699 Receives a message from a socket, waiting at most Timeout mil‐
2701 liseconds for it to arrive.
2702 The same as recvmsg/1,2,3,4,5 but returns {error, timeout} after
2704 Timeout milliseconds, if no message has been delivered.
2705 recvmsg(Socket, Timeout :: nowait) ->
2707 {ok, Msg} |
2708 {select, SelectInfo} |
2709 {completion, CompletionInfo} |
2710 {error, Reason}
2711 recvmsg(Socket, Handle :: select_handle() | completion_handle()) ->
2713 {ok, Msg} |
2714 {select, SelectInfo} |
2715 {completion, CompletionInfo} |
2716 {error, Reason}
2717 recvmsg(Socket, Flags, Timeout :: nowait) ->
2719 {ok, Msg} |
2720 {select, SelectInfo} |
2721 {completion, CompletionInfo} |
2722 {error, Reason}
2723 recvmsg(Socket, Flags,
2725 Handle :: select_handle() | completion_handle()) ->
2726 {ok, Msg} |
2727 {select, SelectInfo} |
2728 {completion, CompletionInfo} |
2729 {error, Reason}
2730 recvmsg(Socket, BufSz, CtrlSz, Timeout :: nowait) ->
2732 {ok, Msg} |
2733 {select, SelectInfo} |
2734 {completion, CompletionInfo} |
2735 {error, Reason}
2736 recvmsg(Socket, BufSz, CtrlSz,
2738 Handle :: select_handle() | completion_handle()) ->
2739 {ok, Msg} |
2740 {select, SelectInfo} |
2741 {completion, CompletionInfo} |
2742 {error, Reason}
2743 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: nowait) ->
2745 {ok, Msg} |
2746 {select, SelectInfo} |
2747 {completion, CompletionInfo} |
2748 {error, Reason}
2749 recvmsg(Socket, BufSz, CtrlSz, Flags,
2751 Handle :: select_handle() | completion_handle()) ->
2752 {ok, Msg} |
2753 {select, SelectInfo} |
2754 {completion, CompletionInfo} |
2755 {error, Reason}
2756 Types:
2758 Socket = socket()
2760 BufSz = CtrlSz = integer() >= 0
2761 Flags = [msg_flag() | integer()]
2762 Msg = msg_recv()
2763 SelectInfo = select_info()
2764 CompletionInfo = completion_info()
2765 Reason = posix() | closed | invalid()
2766 Receives a message from a socket, but returns a select continua‐
2768 tion or a completion term if no message could be returned imme‐
2769 diately.
2770 The same as infinite time-out recvmsg/1,2,3,4 but if no message
2772 can delivered immediately, the function returns (on Unix ) {se‐
2773 lect, SelectInfo} or (on Windows ) {completion, CompletionInfo},
2774 and the caller will then receive one of these messages:
2775 select message:
2777 {'$socket', Socket, select, SelectHandle} (with the Selec‐
2778 tHandle that was contained in the SelectInfo) when data has
2779 arrived.
2780 A subsequent call to recvmsg/1,2,3,4,5 will then return the
2782 data.
2783 completion message:
2785 {'$socket', Socket, completion, {CompletionHandle, Comple‐
2786 tionStatus}} (with the CompletionHandle contained in the
2787 CompletionInfo).
2788 The result of the receive will be in the CompletionStatus.
2790 If the Handle is a select_handle() or completion_handle(), that
2792 term will be contained in a returned SelectInfo or Completion‐
2793 Info and the corresponding (select or completion) message. The
2794 Handle is presumed to be unique to this call.
2795 If the time-out argument is nowait, and a SelectInfo or Comple‐
2797 tionInfo is returned, it will contain a select_handle() or com‐
2798 pletion_handle() generated by the call.
2799 If the caller doesn't want to wait for the data, it must immedi‐
2801 ately call cancel/2 to cancel the operation.
2802 send(Socket, Data) ->
2804 ok |
2805 {ok, RestData} |
2806 {error, Reason} |
2807 {error, {Reason, RestData}}
2808 send(Socket, Data, Flags) ->
2810 ok |
2811 {ok, RestData} |
2812 {error, Reason} |
2813 {error, {Reason, RestData}}
2814 send(Socket, Data, Timeout :: infinity) ->
2816 ok |
2817 {ok, RestData} |
2818 {error, Reason} |
2819 {error, {Reason, RestData}}
2820 send(Socket, Data, Flags, Timeout :: infinity) ->
2822 ok |
2823 {ok, RestData} |
2824 {error, Reason} |
2825 {error, {Reason, RestData}}
2826 Types:
2828 Socket = socket()
2830 Data = iodata()
2831 Flags = [msg_flag() | integer()]
2832 RestData = binary()
2833 Reason =
2834 posix() |
2835 closed |
2836 invalid() |
2837 netname_deleted | too_many_cmds |
2838 eei()
2839 Sends data on a connected socket, waiting for it to be sent.
2841 This call will not return until the Data has been accepted by
2843 the platform's network layer, or it reports an error.
2844 The message Flags may be symbolic msg_flag()s and/or integer()s,
2846 matching the platform's appropriate header files. The values of
2847 all symbolic flags and integers are or:ed together.
2848 The Data, if it is not a binary(), is copied into one before
2850 calling the platform network API, because a single buffer is re‐
2851 quired. A returned RestData is a sub binary of this data binary.
2852 The return value indicates the result from the platform's net‐
2854 work layer:
2855 ok:
2857 All data has been accepted.
2858 {ok, RestData}:
2860 Not all data has been accepted, but no error has been re‐
2861 ported. RestData is the tail of Data that has not been ac‐
2862 cepted.
2863 This cannot happen for a socket of type stream where a par‐
2865 tially successful send is retried until the data is either
2866 accepted or there is an error.
2867 For a socket of type dgram this should probably also not
2869 happen since a message that cannot be passed atomically
2870 should render an error.
2871 It is nevertheless possible for the platform's network layer
2873 to return this.
2874 {error, Reason}:
2876 An error has been reported and no data has been accepted.
2877 The posix() Reasons are from the platform's network layer.
2878 closed means that this socket library knows that the socket
2879 is closed, and invalid() means that something about an argu‐
2880 ment is invalid.
2881 {error, {Reason, RestData}} :
2883 An error has been reported but before that some data was ac‐
2884 cepted. RestData is the tail of Data that has not been ac‐
2885 cepted. See {error, Reason} above.
2886 This can only happen for a socket of type stream when a par‐
2888 tially successful send is retried until there is an error.
2889 send(Socket, Data, Timeout :: integer() >= 0) ->
2891 ok |
2892 {ok, RestData} |
2893 {error, Reason | timeout} |
2894 {error, {Reason | timeout, RestData}}
2895 send(Socket, Data, Flags, Timeout :: integer() >= 0) ->
2897 ok |
2898 {ok, RestData} |
2899 {error, Reason | timeout} |
2900 {error, {Reason | timeout, RestData}}
2901 Types:
2903 Socket = socket()
2905 Data = iodata()
2906 Flags = [msg_flag() | integer()]
2907 RestData = binary()
2908 Reason =
2909 posix() |
2910 closed |
2911 invalid() |
2912 netname_deleted | too_many_cmds |
2913 eei()
2914 Sends data on a connected socket, waiting at most Timeout mil‐
2916 liseconds for it to be sent.
2917 The same as infinite time-out send/2,3,4 but returns {error,
2919 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2920 onds, if no Data or only some of it was accepted by the plat‐
2921 form's network layer.
2922 send(Socket, Data, Handle :: nowait) ->
2924 ok |
2925 {ok, RestData} |
2926 {select, SelectInfo} |
2927 {select, {SelectInfo, RestData}} |
2928 {completion, CompletionInfo} |
2929 {error, Reason}
2930 send(Socket, Data,
2932 Handle :: select_handle() | completion_handle()) ->
2933 ok |
2934 {ok, RestData} |
2935 {select, SelectInfo} |
2936 {select, {SelectInfo, RestData}} |
2937 {completion, CompletionInfo} |
2938 {error, Reason}
2939 send(Socket, Data, Flags, Handle :: nowait) ->
2941 ok |
2942 {ok, RestData} |
2943 {select, SelectInfo} |
2944 {select, {SelectInfo, RestData}} |
2945 {completion, CompletionInfo} |
2946 {error, Reason}
2947 send(Socket, Data, Flags,
2949 Handle :: select_handle() | completion_handle()) ->
2950 ok |
2951 {ok, RestData} |
2952 {select, SelectInfo} |
2953 {select, {SelectInfo, RestData}} |
2954 {completion, CompletionInfo} |
2955 {error, Reason}
2956 Types:
2958 Socket = socket()
2960 Data = iodata()
2961 Flags = [msg_flag() | integer()]
2962 RestData = binary()
2963 SelectInfo = select_info()
2964 CompletionInfo = completion_info()
2965 Reason =
2966 posix() |
2967 closed |
2968 invalid() |
2969 netname_deleted | too_many_cmds |
2970 eei()
2971 Sends data on a connected socket, but returns completion or a
2973 select continuation if the data could not be sent immediately.
2974 The same as infinite time-out send/2,3 but if the data is not
2976 immediately accepted by the platform network layer, the function
2977 returns (on Unix ) {select, SelectInfo} or (on Windows ) {com‐
2978 pletion, CompletionInfo}, and the caller will then receive one
2979 of these messages:
2980 select message:
2982 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2983 tHandle that was contained in the SelectInfo ) when there is
2984 room for more data.
2985 A subsequent call to send/2-4 will then send the data.
2987 completion message:
2989 {'$socket', Socket, completion, {CompletionHandle, Comple‐
2990 tionStatus}} (with the CompletionHandle contained in the
2991 CompletionInfo).
2992 The result of the send will be in the CompletionStatus.
2994 If Handle is a select_handle() or completion_handle(), that term
2996 will be contained in a returned SelectInfo or CompletionInfo and
2997 the corresponding select or completion message. The Handle is
2998 presumed to be unique to this call.
2999 If Handle is nowait, and a SelectInfo or CompletionInfo is re‐
3001 turned, it will contain a select_handle() or completion_handle()
3002 generated by the call.
3003 If some of the data was sent, the function will return {select,
3005 {RestData, SelectInfo}, which can only happen (on Unix ) for a
3006 socket of type stream. If the caller does not want to wait to
3007 send the rest of the data, it should immediately cancel the op‐
3008 eration with cancel/2.
3009 send(Socket, Data, Cont) ->
3011 ok |
3012 {ok, RestData} |
3013 {error, Reason} |
3014 {error, {Reason, RestData}}
3015 send(Socket, Data, Cont, Timeout :: infinity) ->
3017 ok |
3018 {ok, RestData} |
3019 {error, Reason} |
3020 {error, {Reason, RestData}}
3021 send(Socket, Data, Cont, Timeout :: integer() >= 0) ->
3023 ok |
3024 {ok, RestData} |
3025 {error, Reason | timeout} |
3026 {error, {Reason | timeout, RestData}}
3027 send(Socket, Data, Cont, SelectHandle :: nowait) ->
3029 ok |
3030 {ok, RestData} |
3031 {select, SelectInfo} |
3032 {select, {SelectInfo, RestData}} |
3033 {error, Reason}
3034 send(Socket, Data, Cont, SelectHandle :: select_handle()) ->
3036 ok |
3037 {ok, RestData} |
3038 {select, SelectInfo} |
3039 {select, {SelectInfo, RestData}} |
3040 {error, Reason}
3041 Types:
3043 Socket = socket()
3045 Data = iodata()
3046 Cont = select_info()
3047 RestData = binary()
3048 SelectInfo = select_info()
3049 Reason = posix() | closed | invalid()
3050 Continues sending data on a connected socket, where the send op‐
3052 eration was initiated by send/3,4 that returned a SelectInfo
3053 continuation. Otherwise like infinite time-out send/2,3,4 ,
3054 limited time-out send/3,4 or nowait send/3,4 respectively.
3055 Cont is the SelectInfo that was returned from the previous
3057 send() call.
3058 If Data is not a binary(), it will be copied into one, again.
3060 The return value indicates the result from the platform's net‐
3062 work layer. See send/2,3,4 and nowait send/3,4.
3063 sendmsg(Socket, Msg) ->
3065 ok |
3066 {ok, RestData} |
3067 {error, Reason} |
3068 {error, {Reason, RestData}}
3069 sendmsg(Socket, Msg, Flags) ->
3071 ok |
3072 {ok, RestData} |
3073 {error, Reason} |
3074 {error, {Reason, RestData}}
3075 sendmsg(Socket, Msg, Timeout :: infinity) ->
3077 ok |
3078 {ok, RestData} |
3079 {error, Reason} |
3080 {error, {Reason, RestData}}
3081 sendmsg(Socket, Msg, Flags, Timeout :: infinity) ->
3083 ok |
3084 {ok, RestData} |
3085 {error, Reason} |
3086 {error, {Reason, RestData}}
3087 Types:
3089 Socket = socket()
3091 Msg = msg_send()
3092 Flags = [msg_flag() | integer()]
3093 RestData = erlang:iovec()
3094 Reason = posix() | closed | invalid()
3095 Sends a message on a socket, waiting for it to be sent.
3097 The destination, if needed, that is: if the socket is not con‐
3099 nected, is provided in Msg, which also contains the data to send
3100 as a list of binaries. Msg may also contain an list of optional
3101 control messages (depending on what the protocol and platform
3102 supports).
3103 For a connected socket no address field should be present in
3105 Msg, the platform may return an error or ignore one.
3106 The message data is given to to the platform's network layer in
3108 the form of an I/O vector without copying the content. If the
3109 number of elements in the I/O vector is larger than allowed on
3110 the platform (reported in the iov_max field from info/0), on a
3111 socket of type stream the send is iterated over all elements,
3112 but for other socket types the call fails.
3113 This call will not return until the data has been handed over to
3115 the platform's network layer, or when it reports an error.
3116 The message Flags may be symbolic msg_flag()s and/or integer()s,
3118 matching the platform's appropriate header files. The values of
3119 all symbolic flags and integers are or:ed together.
3120 The return value indicates the result from the platform's net‐
3122 work layer. See send/2,3,4.
3123 Note:
3125 On Windows, this function can only be used with datagram and raw
3126 sockets.
3127 sendmsg(Socket, Msg, Timeout :: integer() >= 0) ->
3130 ok |
3131 {ok, RestData} |
3132 {error, Reason | timeout} |
3133 {error, {Reason | timeout, RestData}}
3134 sendmsg(Socket, Msg, Flags, Timeout :: integer() >= 0) ->
3136 ok |
3137 {ok, RestData} |
3138 {error, Reason | timeout} |
3139 {error, {Reason | timeout, RestData}}
3140 Types:
3142 Socket = socket()
3144 Msg = msg_send()
3145 Flags = [msg_flag() | integer()]
3146 RestData = erlang:iovec()
3147 Reason = posix() | closed | invalid()
3148 Sends a message on a socket, waiting at most Timeout millisec‐
3150 onds for it to be sent.
3151 The same as infinite time-out sendmsg/2,3,4 but returns {error,
3153 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
3154 onds, if no data or only some of it was accepted by the plat‐
3155 form's network layer.
3156 Note:
3158 On Windows, this function can only be used with datagram and raw
3159 sockets.
3160 sendmsg(Socket, Msg, Timeout :: nowait) ->
3163 ok |
3164 {ok, RestData} |
3165 {select, SelectInfo} |
3166 {select, {SelectInfo, RestData}} |
3167 {completion, CompletionInfo} |
3168 {error, Reason} |
3169 {error, {Reason, RestData}}
3170 sendmsg(Socket, Msg,
3172 Handle :: select_handle() | completion_handle()) ->
3173 ok |
3174 {ok, RestData} |
3175 {select, SelectInfo} |
3176 {select, {SelectInfo, RestData}} |
3177 {completion, CompletionInfo} |
3178 {error, Reason} |
3179 {error, {Reason, RestData}}
3180 sendmsg(Socket, Msg, Flags, Timeout :: nowait) ->
3182 ok |
3183 {ok, RestData} |
3184 {select, SelectInfo} |
3185 {select, {SelectInfo, RestData}} |
3186 {completion, CompletionInfo} |
3187 {error, Reason} |
3188 {error, {Reason, RestData}}
3189 sendmsg(Socket, Msg, Flags,
3191 Handle :: select_handle() | completion_handle()) ->
3192 ok |
3193 {ok, RestData} |
3194 {select, SelectInfo} |
3195 {select, {SelectInfo, RestData}} |
3196 {completion, CompletionInfo} |
3197 {error, Reason} |
3198 {error, {Reason, RestData}}
3199 Types:
3201 Socket = socket()
3203 Msg = msg_send()
3204 Flags = [msg_flag() | integer()]
3205 RestData = erlang:iovec()
3206 SelectInfo = select_info()
3207 CompletionInfo = completion_info()
3208 Reason = posix() | closed | invalid()
3209 Sends a message on a socket, but returns completion or a select
3211 continuation if the data could not be sent immediately.
3212 The same as infinity time-out sendmsg/2,3 but if the data is
3214 not immediately accepted by the platform network layer, the
3215 function returns (on Unix ) {select, SelectInfo} or (on Windows
3216 ) {completion, CompletionInfo}, and the caller will then receive
3217 one of these messages:
3218 select message:
3220 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
3221 tHandle that was contained in the SelectInfo ) when there is
3222 room for more data. A subsequent call to sendmsg/2-4 will
3223 then send the data.
3224 completion message:
3226 {'$socket', Socket, completion, {CompletionHandle, Comple‐
3227 tionStatus}} (with the CompletionHandle contained in the
3228 CompletionInfo).
3229 The result of the send will be in the CompletionStatus.
3231 If Handle, is a select_handle() or completion_handle(), that
3233 term will be contained in a returned SelectInfo or Completion‐
3234 Info and the corresponding select or completion message. The
3235 Handle is presumed to be unique to this call.
3236 If Timeout is nowait, and a SelectInfo or CompletionInfo is re‐
3238 turned, it will contain a select_handle() or completion_handle()
3239 generated by the call.
3240 If some of the data was sent, the function will return {select,
3242 {RestData, SelectInfo}, which can only happen for a socket of
3243 type stream. If the caller does not want to wait to send the
3244 rest of the data, it should immediately cancel the operation
3245 with cancel/2.
3246 Note:
3248 On Windows, this function can only be used with datagram and raw
3249 sockets.
3250 sendmsg(Socket, Data, Cont) ->
3253 ok |
3254 {ok, RestData} |
3255 {error, Reason} |
3256 {error, {Reason, RestData}}
3257 sendmsg(Socket, Data, Cont, Timeout :: infinity) ->
3259 ok |
3260 {ok, RestData} |
3261 {error, Reason} |
3262 {error, {Reason, RestData}}
3263 sendmsg(Socket, Data, Cont, Timeout :: integer() >= 0) ->
3265 ok |
3266 {ok, RestData} |
3267 {error, Reason | timeout} |
3268 {error, {Reason | timeout, RestData}}
3269 sendmsg(Socket, Data, Cont, Timeout :: nowait) ->
3271 ok |
3272 {ok, RestData} |
3273 {select, SelectInfo} |
3274 {select, {SelectInfo, RestData}} |
3275 {completion, CompletionInfo} |
3276 {error, Reason} |
3277 {error, {Reason, RestData}}
3278 sendmsg(Socket, Data, Cont, SelectHandle :: select_handle()) ->
3280 ok |
3281 {ok, RestData} |
3282 {select, SelectInfo} |
3283 {select, {SelectInfo, RestData}} |
3284 {error, Reason} |
3285 {error, {Reason, RestData}}
3286 Types:
3288 Socket = socket()
3290 Data = msg_send() | erlang:iovec()
3291 Cont = select_info()
3292 RestData = erlang:iovec()
3293 SelectInfo = select_info()
3294 Reason = posix() | closed | invalid()
3295 Continues sending a message data on a socket, where the send op‐
3297 eration was initiated by sendmsg/3,4 that returned a SelectInfo
3298 continuation. Otherwise like infinite time-out sendmsg/2,3,4 ,
3299 limited time-out sendmsg/3,4 or nowait sendmsg/3,4 respec‐
3300 tively.
3301 Cont is the SelectInfo that was returned from the previous
3303 sendmsg() call.
3304 The return value indicates the result from the platform's net‐
3306 work layer. See send/2,3,4 and nowait sendmsg/3,4.
3307 sendto(Socket, Data, Dest) ->
3309 ok |
3310 {ok, RestData} |
3311 {error, Reason} |
3312 {error, {Reason, RestData}}
3313 sendto(Socket, Data, Dest, Flags) ->
3315 ok |
3316 {ok, RestData} |
3317 {error, Reason} |
3318 {error, {Reason, RestData}}
3319 sendto(Socket, Data, Dest, Timeout :: infinity) ->
3321 ok |
3322 {ok, RestData} |
3323 {error, Reason} |
3324 {error, {Reason, RestData}}
3325 sendto(Socket, Data, Dest, Flags, Timeout :: infinity) ->
3327 ok |
3328 {ok, RestData} |
3329 {error, Reason} |
3330 {error, {Reason, RestData}}
3331 Types:
3333 Socket = socket()
3335 Data = iodata()
3336 Dest = sockaddr()
3337 Flags = [msg_flag() | integer()]
3338 RestData = binary()
3339 Reason = posix() | closed | invalid()
3340 Sends data on a socket, to the specified destination, waiting
3342 for it to be sent.
3343 This call will not return until the data has been accepted by
3345 the platform's network layer, or it reports an error.
3346 If this call is used on a connection mode socket or on a con‐
3348 nected socket, the platforms's network layer may return an error
3349 or ignore the destination address.
3350 The message Flags may be symbolic msg_flag()s and/or integer()s,
3352 matching the platform's appropriate header files. The values of
3353 all symbolic flags and integers are or:ed together.
3354 The return value indicates the result from the platform's net‐
3356 work layer. See send/2,3,4.
3357 sendto(Socket, Data, Dest, Timeout :: integer() >= 0) ->
3359 ok |
3360 {ok, RestData} |
3361 {error, Reason | timeout} |
3362 {error, {Reason | timeout, RestData}}
3363 sendto(Socket, Data, Dest, Flags, Timeout :: integer() >= 0) ->
3365 ok |
3366 {ok, RestData} |
3367 {error, Reason | timeout} |
3368 {error, {Reason | timeout, RestData}}
3369 Types:
3371 Socket = socket()
3373 Data = iodata()
3374 Dest = sockaddr()
3375 Flags = [msg_flag() | integer()]
3376 RestData = binary()
3377 Reason = posix() | closed | invalid()
3378 Sends data on a socket, waiting at most Timeout milliseconds for
3380 it to be sent.
3381 The same as infinite time-out sendto/3,4,5 but returns {error,
3383 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
3384 onds, if no Data or only some of it was accepted by the plat‐
3385 form's network layer.
3386 sendto(Socket, Data, Dest, Handle :: nowait) ->
3388 ok |
3389 {ok, RestData} |
3390 {select, SelectInfo} |
3391 {select, {SelectInfo, RestData}} |
3392 {completion, CompletionInfo} |
3393 {error, Reason}
3394 sendto(Socket, Data, Dest,
3396 Handle :: select_handle() | completion_handle()) ->
3397 ok |
3398 {ok, RestData} |
3399 {select, SelectInfo} |
3400 {select, {SelectInfo, RestData}} |
3401 {completion, CompletionInfo} |
3402 {error, Reason}
3403 sendto(Socket, Data, Dest, Flags, Handle :: nowait) ->
3405 ok |
3406 {ok, RestData} |
3407 {select, SelectInfo} |
3408 {select, {SelectInfo, RestData}} |
3409 {completion, CompletionInfo} |
3410 {error, Reason}
3411 sendto(Socket, Data, Dest, Flags,
3413 Handle :: select_handle() | completion_handle()) ->
3414 ok |
3415 {ok, RestData} |
3416 {select, SelectInfo} |
3417 {select, {SelectInfo, RestData}} |
3418 {completion, CompletionInfo} |
3419 {error, Reason}
3420 Types:
3422 Socket = socket()
3424 Data = iodata()
3425 Dest = sockaddr()
3426 Flags = [msg_flag() | integer()]
3427 RestData = binary()
3428 SelectInfo = select_info()
3429 CompletionInfo = completion_info()
3430 Reason = posix() | closed | invalid()
3431 Sends data on a socket, but returns completion or a select con‐
3433 tinuation if the data could not be sent immediately.
3434 The same as infinity time-out sendto/3,4 but if the data is not
3436 immediately accepted by the platform network layer, the function
3437 returns (on Unix ) {select, SelectInfo} or (on Windows ) {com‐
3438 pletion, CompletionInfo}, and the caller will then receive one
3439 of these messages:
3440 select message:
3442 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
3443 tHandle that was contained in the SelectInfo ) when there is
3444 room for more data.
3445 A subsequent call to send/2-4 will then send the data.
3447 completion message:
3449 {'$socket', Socket, completion, {CompletionHandle, Comple‐
3450 tionStatus}} (with the CompletionHandle contained in the
3451 CompletionInfo).
3452 The result of the send will be in the CompletionStatus.
3454 If Handle is a select_handle() or completion_handle(), that term
3456 will be contained in a returned SelectInfo or CompletionInfo and
3457 the corresponding select or completion message. The Handle is
3458 presumed to be unique to this call.
3459 If Handle is nowait, and a SelectInfo or CompletionInfo is re‐
3461 turned, it will contain a select_handle() or completion_handle()
3462 generated by the call.
3463 If some of the data was sent, the function will return {select,
3465 {RestData, SelectInfo}, which can only happen (on Unix ) for a
3466 socket of type stream. If the caller does not want to wait to
3467 send the rest of the data, it should immediately cancel the op‐
3468 eration with cancel/2.
3469 sendto(Socket, Data, Cont) ->
3471 ok |
3472 {ok, RestData} |
3473 {error, Reason} |
3474 {error, {Reason, RestData}}
3475 sendto(Socket, Data, Cont, Timeout :: infinity) ->
3477 ok |
3478 {ok, RestData} |
3479 {error, Reason} |
3480 {error, {Reason, RestData}}
3481 sendto(Socket, Data, Cont, Timeout :: integer() >= 0) ->
3483 ok |
3484 {ok, RestData} |
3485 {error, Reason | timeout} |
3486 {error, {Reason | timeout, RestData}}
3487 sendto(Socket, Data, Cont, SelectHandle :: nowait) ->
3489 ok |
3490 {ok, RestData} |
3491 {select, SelectInfo} |
3492 {select, {SelectInfo, RestData}} |
3493 {error, Reason}
3494 sendto(Socket, Data, Cont, SelectHandle :: select_handle()) ->
3496 ok |
3497 {ok, RestData} |
3498 {select, SelectInfo} |
3499 {select, {SelectInfo, RestData}} |
3500 {error, Reason}
3501 Types:
3503 Socket = socket()
3505 Data = iodata()
3506 Cont = select_info()
3507 RestData = binary()
3508 SelectInfo = select_info()
3509 Reason = posix() | closed | invalid()
3510 Continues sending data on a socket, where the send operation was
3512 initiated by sendto/4,5 that returned a SelectInfo continuation.
3513 Otherwise like infinite time-out sendto/3,4,5 , limited time-
3514 out sendto/4,5 or nowait sendto/4,5 respectively.
3515 Cont is the SelectInfo that was returned from the previous
3517 sendto() call.
3518 If Data is not a binary(), it will be copied into one, again.
3520 The return value indicates the result from the platform's net‐
3522 work layer. See send/2,3,4 and nowait sendto/4,5.
3523 sendfile(Socket, FileHandle, Offset, Count, Timeout :: infinity) ->
3525 {ok, BytesSent} |
3526 {error, Reason} |
3527 {error, {Reason, BytesSent}}
3528 Types:
3530 Socket = socket()
3532 FileHandle = file:fd()
3533 Offset = integer()
3534 Count = BytesSent = integer() >= 0
3535 Reason = posix() | closed | invalid()
3536 Sends file data on a socket, to the specified destination, wait‐
3538 ing for it to be sent ("infinite" time-out).
3539 The FileHandle must refer to an open raw file as described in
3541 file:open/2.
3542 This call will not return until the data has been accepted by
3544 the platform's network layer, or it reports an error.
3545 The Offset argument is the file offset to start reading from.
3547 The default value is 0.
3548 The Count argument is the number of bytes to transfer from File‐
3550 Handle to Socket. If Count =:= 0 (the default) the transfer
3551 stops at the end of file.
3552 The return value indicates the result from the platform's net‐
3554 work layer:
3555 {ok, BytesSent}:
3557 The transfer completed successfully after BytesSent bytes of
3558 data.
3559 {error, Reason}:
3561 An error has been reported and no data has been transferred.
3562 The posix() Reasons are from the platform's network layer.
3563 closed means that this socket library knows that the socket
3564 is closed, and invalid() means that something about an argu‐
3565 ment is invalid.
3566 {error, {Reason, BytesSent}} :
3568 An error has been reported but before that some data was
3569 transferred. See {error, Reason} and {ok, BytesSent} above.
3570 sendfile(Socket, FileHandle, Offset, Count,
3572 Timeout :: integer() >= 0) ->
3573 {ok, BytesSent} |
3574 {error, Reason | timeout} |
3575 {error, {Reason | timeout, BytesSent}}
3576 Types:
3578 Socket = socket()
3580 FileHandle = file:fd()
3581 Offset = integer()
3582 Count = BytesSent = integer() >= 0
3583 Reason = posix() | closed | invalid()
3584 Sends file data on a socket, waiting at most Timeout millisec‐
3586 onds for it to be sent (limited time-out).
3587 The same as "infinite" time-out sendfile/5 but returns {error,
3589 timeout} or {error, {timeout, BytesSent}} after Timeout mil‐
3590 liseconds, if not all file data was transferred by the plat‐
3591 form's network layer.
3592 sendfile(Socket, FileHandle, Offset, Count,
3594 SelectHandle :: nowait) ->
3595 {ok, BytesSent} |
3596 {select, SelectInfo} |
3597 {select, {SelectInfo, BytesSent}} |
3598 {error, Reason}
3599 sendfile(Socket, FileHandle, Offset, Count,
3601 SelectHandle :: select_handle()) ->
3602 {ok, BytesSent} |
3603 {select, SelectInfo} |
3604 {select, {SelectInfo, BytesSent}} |
3605 {error, Reason}
3606 Types:
3608 Socket = socket()
3610 FileHandle = file:fd()
3611 Offset = integer()
3612 Count = BytesSent = integer() >= 0
3613 SelectInfo = select_info()
3614 Reason = posix() | closed | invalid()
3615 Sends file data on a socket, but returns a select continuation
3617 if the data could not be sent immediately (nowait).
3618 The same as "infinite" time-out sendfile/5 but if the data is
3620 not immediately accepted by the platform network layer, the
3621 function returns {select, SelectInfo}, and the caller will then
3622 receive a select message, {'$socket', Socket, select, Selec‐
3623 tHandle} ( with the SelectHandle that was contained in the Se‐
3624 lectInfo ) when there is room for more data. Then a call to
3625 sendfile/3 with SelectInfo as the second argument will continue
3626 the data transfer.
3627 If SelectHandle is a select_handle(), that term will be con‐
3629 tained in a returned SelectInfo and the corresponding select
3630 message. The SelectHandle is presumed to be unique to this call.
3631 If SelectHandle is nowait, and a SelectInfo is returned, it will
3633 contain a select_handle() generated by the call.
3634 If some file data was sent, the function will return {ok,
3636 {BytesSent, SelectInfo}. If the caller does not want to wait to
3637 send the rest of the data, it should immediately cancel the op‐
3638 eration with cancel/2.
3639 sendfile(Socket, Cont, Offset, Count, Timeout :: infinity) ->
3641 {ok, BytesSent} |
3642 {error, Reason} |
3643 {error, {Reason, BytesSent}}
3644 sendfile(Socket, Cont, Offset, Count,
3646 Timeout :: integer() >= 0) ->
3647 {ok, BytesSent} |
3648 {error, Reason | timeout} |
3649 {error, {Reason | timeout, BytesSent}}
3650 sendfile(Socket, Cont, Offset, Count, SelectHandle :: nowait) ->
3652 {ok, BytesSent} |
3653 {select, SelectInfo} |
3654 {select, {SelectInfo, BytesSent}} |
3655 {error, Reason}
3656 sendfile(Socket, Cont, Offset, Count,
3658 SelectHandle :: select_handle()) ->
3659 {ok, BytesSent} |
3660 {select, SelectInfo} |
3661 {select, {SelectInfo, BytesSent}} |
3662 {error, Reason}
3663 Types:
3665 Socket = socket()
3667 Cont = select_info()
3668 Offset = integer()
3669 Count = BytesSent = integer() >= 0
3670 SelectInfo = select_info()
3671 Reason = posix() | closed | invalid()
3672 Continues sending file data on a socket, where the send opera‐
3674 tion was initiated by sendfile/3,5 that returned a SelectInfo
3675 continuation. Otherwise like "infinite" time-out sendfile/5 ,
3676 limited time-out sendfile/5 or nowait sendfile/5 respectively.
3677 Cont is the SelectInfo that was returned from the previous send‐
3679 file() call.
3680 The return value indicates the result from the platform's net‐
3682 work layer. See "infinite" time-out sendfile/5.
3683 sendfile(Socket, FileHandle, Offset, Count) -> Result
3685 Types:
3687 Socket = socket()
3689 FileHandle = file:fd()
3690 Offset = integer()
3691 Count = integer() >= 0
3692 The same as sendfile(Socket, FileHandle, Offset, Count, infin‐
3694 ity), that is: send the file data at Offset and Count to the
3695 socket, without time-out other than from the platform's network
3696 stack.
3697 sendfile(Socket, FileHandle, Timeout) -> Result
3699 Types:
3701 Socket = socket()
3703 FileHandle = file:fd()
3704 Timeout = timeout() | 'nowait' | select_handle()
3705 Depending on the Timeout argument; the same as sendfile(Socket,
3707 FileHandle, 0, 0, infinity), sendfile(Socket, FileHandle, 0,
3708 0, Timeout), or sendfile(Socket, FileHandle, 0, 0, Selec‐
3709 tHandle), that is: send all data in the file to the socket,
3710 with the given Timeout.
3711 sendfile(Socket, FileHandle) -> Result
3713 Types:
3715 Socket = socket()
3717 FileHandle = file:fd()
3718 The same as sendfile(Socket, FileHandle, 0, 0, infinity), that
3720 is: send all data in the file to the socket, without time-out
3721 other than from the platform's network stack.
3722 setopt(Socket :: socket(),
3724 SocketOption :: {Level :: otp, Opt :: otp_socket_option()},
3725 Value :: term()) ->
3726 ok | {error, invalid() | closed}
3727 Sets a socket option in the protocol level otp, which is this
3729 implementation's level above the OS protocol layers.
3730 See the type otp_socket_option() for a description of the op‐
3732 tions on this level.
3733 setopt(Socket :: socket(),
3735 SocketOption :: socket_option(),
3736 Value :: term()) ->
3737 ok | {error, posix() | invalid() | closed}
3738 Set a socket option in one of the OS's protocol levels. See the
3740 type socket_option() for which options that this implementation
3741 knows about, how they are related to option names in the OS, and
3742 if there are known peculiarities with any of them.
3743 What options are valid depends on what kind of socket it is (do‐
3745 main(), type() and protocol()).
3746 See the socket options chapter of the users guide for more
3748 info.
3749 Note:
3751 Not all options are valid, nor possible to set, on all plat‐
3752 forms. That is, even if "we" support an option; it does not mean
3753 that the underlying OS does.
3754 setopt(Socket, Level, Opt, Value) -> ok | {error, Reason}
3757 Types:
3759 Socket = socket()
3761 Value = term()
3762 Reason = inet:posix() | invalid() | closed
3763 Backwards compatibility function.
3765 The same as setopt(Socket, {Level, Opt}, Value)
3767 setopt_native(Socket :: socket(),
3769 SocketOption ::
3770 socket_option() |
3771 {Level :: level() | (NativeLevel :: integer()),
3772 NativeOpt :: integer()},
3773 Value :: native_value()) ->
3774 ok | {error, posix() | invalid() | closed}
3775 Sets a socket option that may be unknown to our implementation,
3777 or that has a type not compatible with our implementation, that
3778 is; in "native mode".
3779 If Value is an integer() it will be used as a C type (int), if
3781 it is a boolean() it will be used as a C type (int) with the C
3782 implementations values for false or true, and if it is a bi‐
3783 nary() its content and size will be used as the option value.
3784 The socket option may be specified with an ordinary socket_op‐
3786 tion() tuple, with a known Level = level() and an integer Na‐
3787 tiveOpt, or with both an integer NativeLevel and NativeOpt.
3788 What options are valid depends on what kind of socket it is (do‐
3790 main(), type() and protocol()).
3791 The integer values for NativeLevel and NativeOpt as well as the
3793 encoding of Value has to be deduced from the header files for
3794 the running system.
3795 shutdown(Socket, How) -> ok | {error, Reason}
3797 Types:
3799 Socket = socket()
3801 How = read | write | read_write
3802 Reason = posix() | closed
3803 Shut down all or part of a full-duplex connection.
3805 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
3807 Types:
3809 Socket = socket()
3811 SockAddr = sockaddr_recv()
3812 Reason = posix() | closed
3813 Returns the current address to which the socket is bound.
3815 supports() ->
3817 [{Key1 :: term(),
3818 boolean() |
3819 [{Key2 :: term(),
3820 boolean() | [{Key3 :: term(), boolean()}]}]}]
3821 supports(Key1 :: term()) ->
3823 [{Key2 :: term(),
3824 boolean() | [{Key3 :: term(), boolean()}]}]
3825 supports(Key1 :: term(), Key2 :: term()) ->
3827 [{Key3 :: term(), boolean()}]
3828 These functions function retrieves information about what the
3830 platform supports, such which platform features or which socket
3831 options, are supported.
3832 For keys other than the known the empty list is returned, Note
3834 that in a future version or on a different platform there might
3835 be more supported items.
3836 supports():
3838 Returns a list of {Key1, supports(Key1)} tuples for every
3839 Key1 described in supports/1 and {Key1, boolean()} tuples
3840 for each of the following keys:
3841 sctp:
3843 SCTP support
3844 ipv6:
3846 IPv6 support
3847 local:
3849 Unix Domain sockets support (AF_UNIX | AF_LOCAL)
3850 netns:
3852 Network Namespaces support (Linux, setns(2))
3853 sendfile:
3855 Sendfile support (sendfile(2))
3856 supports(msg_flags = Key1):
3858 Returns a list of {Flag, boolean()} tuples for every Flag in
3859 msg_flag() with the boolean() indicating if the flag is sup‐
3860 ported on this platform.
3861 supports(protocols = Key1):
3863 Returns a list of {Name :: atom(), boolean()} tuples for ev‐
3864 ery Name in protocol() with the boolean() indicating if the
3865 protocol is supported on this platform.
3866 supports(options = Key1):
3868 Returns a list of {SocketOption, boolean()} tuples for every
3869 SocketOption in socket_option() with the boolean() indicat‐
3870 ing if the socket option is supported on this platform.
3871 supports(options = Key1, Key2) :
3873 For a Key2 in level() returns a list of {Opt, boolean()} tu‐
3874 ples for all known socket options Opt on that Level =:=
3875 Key2, and the boolean() indicating if the socket option is
3876 supported on this platform. See setopt/3 and getopt/2.
3877 use_registry(D :: boolean()) -> ok
3879 Globally change if the socket registry is to be used or not.
3881 Note that its still possible to override this explicitly when
3882 creating an individual sockets, see open/2 or open/4 for more
3883 info (use the Extra argument).
3884 which_sockets() -> [socket()]
3886 which_sockets(FilterRule) -> [socket()]
3888 Types:
3890 FilterRule =
3892 inet | inet6 | local | stream | dgram | seqpacket | sctp
3893 |
3894 tcp | udp |
3895 pid() |
3896 fun((socket_info()) -> boolean())
3897 Returns a list of all sockets, according to the filter rule.
3899 There are several pre-made filter rule(s) and one general:
3901 inet | inet6:
3903 Selection based on the domain of the socket.
3904 Only a subset is valid.
3905 stream | dgram | seqpacket:
3907 Selection based on the type of the socket.
3908 Only a subset is valid.
3909 sctp | tcp | udp:
3911 Selection based on the protocol of the socket.
3912 Only a subset is valid.
3913 pid():
3915 Selection base on which sockets has this pid as Controlling
3916 Process.
3917 fun((socket_info()) -> boolean()):
3919 The general filter rule.
3920 A fun that takes the socket info and returns a boolean()
3921 (true if the socket could be included and false if should
3922 not).
3923
3925 client(SAddr, SPort) ->
3926 {ok, Sock} = socket:open(inet, stream, tcp),
3927 ok = socket:connect(Sock, #{family => inet,
3928 addr => SAddr,
3929 port => SPort}),
3930 Msg = <<"hello">>,
3931 ok = socket:send(Sock, Msg),
3932 ok = socket:shutdown(Sock, write),
3933 {ok, Msg} = socket:recv(Sock),
3934 ok = socket:close(Sock).
3935 server(Addr, Port) ->
3937 {ok, LSock} = socket:open(inet, stream, tcp),
3938 ok = socket:bind(LSock, #{family => inet,
3939 port => Port,
3940 addr => Addr}),
3941 ok = socket:listen(LSock),
3942 {ok, Sock} = socket:accept(LSock),
3943 {ok, Msg} = socket:recv(Sock),
3944 ok = socket:send(Sock, Msg),
3945 ok = socket:close(Sock),
3946 ok = socket:close(LSock).
3947Ericsson AB kernel 9.1 socket(3)